graphics.md

graphics

mud gfx library uses the same immediate paradigm as the ui. instead of nesting ui nodes (widgets) calls, you nest graphics nodes calls. as such it is perfect for quickly setting up some debug graphics rendering.

mud rendering primitives :

• shapes: parametric definitions of standard shapes : circle, sphere, cylinder, cube, rectangle, etc...
• symbols: how a given shape should be rendered : color, fill and outline, level of detail
• meshes: rendering primitives and their index and vertex data
• models: a sum of meshes and optionally a skeleton
• textures: immutable or dynamic 2D-, 3D-, cubemap- and array-textures
• shaders: a shader (vertex, fragment, geometry, compute) is linked to a sequence of blocks
• programs: a program is the sum of shaders and blocks that governs the rendering of a primitive
• materials: a material associated to a program, contains all the data parameters of this program
• blocks: a render block holds all the state and logic of a given rendering feature
• passes: a pass is a unit of renderer work, which can do virtually any render operation
• renderers: a renderer is a sequence of passes, it dictates how is a viewport rendered
• pipelines: a pipeline is a collection of all render blocks needed by its renderers

the graph is composed of the following primitives :

• nodes: a node is a transform an a user object
• items: an instance of a model

here are all the functions of the immediate gfx API :

graph

this function adds a node to the hierarchy :

namespace gfx
{
    Gnode& node(Gnode& parent, Ref object, const vec3& position, const quat& rotation, const vec3& scale);
}

these functions add a shape item to the hierarchy :

namespace gfx
{
    Item& shape(Gnode& parent, const Shape& shape, const Symbol& symbol, uint32_t flags, Material* material, size_t instances);
    void draw(Gnode& parent, const Shape& shape, const Symbol& symbol, uint32_t flags);
}

these functions add a model item to the hierarchy :

namespace gfx
{
    Item& item(Gnode& parent, const Model& model, uint32_t flags, Material* material, size_t instances);
    Item& model(Gnode& parent, const string& name, uint32_t flags, Material* material, size_t instances);
    Animated& animated(Gnode& parent, Item& item);
}

this function adds a particles emitter to the hierarchy :

namespace gfx
{
    Particles& particles(Gnode& parent, const ParticleGenerator& emitter, uint32_t flags, size_t instances);
}

these functions add lights to the hierarchy :

namespace gfx
{
    Light& light(Gnode& parent, LightType type, bool shadows, Colour colour, float range, float attenuation);
    Light& sun_light(Gnode& parent, float azimuth, float elevation);
    GIProbe& gi_probe(Gnode& parent);
    void radiance(Gnode& parent, const string& texture);
}

this function sets the background :

namespace gfx
{
    void custom_sky(Gnode& parent, std::function<void(Render&)> renderer);
}

these functions create a material in the hierarchy :

namespace gfx
{
    Material& material(Gnode& parent, UnshadedMaterialBlock& unshaded_block);
    Material& material(Gnode& parent, PbrMaterialBlock& pbr_block);
}

create a viewer to render into

SceneViewer& viewer = ui::scene_viewer(uroot);
Gnode& groot = viewer.m_scene.m_graph.begin();

draw a node, setting the transform for all children of this node

Gnode& gnode gfx::node(root, {}, vec3(0.f, 15.f, 7.5f));

shapes

the math module offers standard parametric definitions of various 3D and 2D shapes
these shapes can be used in various operations : rendering, random point distribution, physics collisions

to draw any arbitrary shape, call the gfx::shape function, passing a shape and a symbol object
the symbol parameter drives how the shape should be rendered : outline color, fill color, image, lod, double-sided

gfx::shape(gnode, Symbol(Colour::White), Cube());

meshes

a mesh is a rendering primitive that maps roughly 1:1 to the API primitives and their buffers
meshes are usually created by mud when loading a model so you don't have to deal with them directly

meshes are composed of indices, vertices, and a primitive types :

enum class refl_ PrimitiveType : unsigned int
{
    Points = 0,
    Lines = 1,
    LineLoop = 2,
    LineStrip = 3,
    Triangles = 4,
    TriangleStrip = 5,
    TriangleFan = 6
};

• this section will be fleshed out as the interface to create meshes gets polished

models

a model is a collection of primitives (meshes) to be rendered as a single entity
anything rendered to the screen by the gfx module, except immediate geometry, is a model

to draw an instance of a model, call the gfx::item function, passing either the name of the model or directly a modelobject

gfx::item(gnode, "my_3d_model.obj");

textures

a texture is an image file loaded and ready to be used for rendering
the main use of textures is for them to be sampled in materials

Texture& texture = gfx::texture("my_texture.jpg");
UnshadedMaterialBlock unshaded_block = { &texture };
Material& material = gfx::material(gnode, unshaded_block);
gfx::item(gnode, model, material);

animate a model item

Item& item = gfx::model(gnode, "my_3d_model.obj");
Animated& animated = gfx::animated(gnode, item);
animated.play("walk");