When I started working on the new frame graph and render passes (and related classes), I knew they were a bit of a pain to work with. Simply put, they are just too verbose.
Let me give you an example: Let’s assume you want to render a simple triangle? Then, it’s just as simple as:
- Create one or more attachments, each of them including:
- Usage flags (is it a color or a depth attachment?)
- Format flags (is it RGB, RGBA, whatever the swapchain supports, RGB8, RGB32?)
- Is it supposed to be used as a texture? Then you also need to specify image views
- Create a pipeline
- Lot’s of settings (rasterization, depth)
- More settings (alpha, cull mode)
- Plus, you need to create and configure shaders
- Also, more settings (viewport modes, etc)
- Create descriptors for
- Textures
- Uniform buffers
- So many options
- Create a render pass
- Link it with attachments and descriptors
- Is it rendering offscreen?
- Link it with more attachments and descriptors from other render passes
- Record render commands
- You need a pointer to your scene here, BTW…
See? Easy… (that’s the simplest scenario I can think of)
Ok, I’m not being fair here.
Yes, the API is verbose. But that’s exactly how the API is supposed to be. And that is OK, because I wanted it to be verbose. That kind of verbosity is exactly what allows us to customize our rendering process to whatever needs we have in our simulation. Besides, we are only supposed to do that once in our code (unless our rendering process for some reason). So all that verbosity is acceptable.
Wait. If we only need to deal with that verbosity only a few times in our program, why am I complaining about it?
The problem is that as I am re-organizing the demos and examples, I suddenly found myself writing lots of new applications. And that means, having to deal with that verbosity in each of them. Which is annoying, not only because I have to repeat myself every time I want to render a scene, but also because the API is still changing and I have to go over all of the examples time and time again in order to make sure they’re all up-to-date.
Therefore, I need a simpler way to deal with this verbosity.
But let me be clear here. I don’t want to get rid of the verbosity by introducing a simpler API. That’s a big NO. I like that verbosity. I’m very happy with that verbosity and I know that is the cost I have to pay for having that kind of customization power.
What I want is just a way to not having to repeat myself every time I create a new demo. To be honest, I don’t care if this is not good enough for real-world applications (more on that later).
So, I need a tool to compose different render passes and mix them in an expressive way. Therefore, I need a… oh, right. I spoiled it already with the title of this post. Mmm. Ok, I’m going to say it anyways and you promise you’ll make your best surprised face, ok? Here we go:
What I need is a Composition tool.
Surprise!
About compositions
Let’s go over our requirements again:
- We’re going to be creating lots of objects when defining the different render passes and they need to be kept alive for as long as our composition is valid. In order to accomplish this requirement, we can store them in a struct called Composition, containing a list of objects. If a composition is destroyed (i.e. the app ends, or we swap the composition with a different one), all of its internal objects will also be destroyed.
- We’re going to be rendering images, so we need to treat Attachments in a special way. We need to declare at least one of them to be the resulting image (the one that is going to be presented to the screen). We also need to access them by name so we can link different render passes if needed (for example, we might need to apply some special effect to an image generated by rendering a 3D scene). For this purpose, the Composition type also keeps a map with references to all of the existing attachments (there is a chance for name collisions between attachments, but I don’t care for the moment. I don’t want to complicate things too much at this stage).
- Obviously, we need a mechanism for creating compositions that is reusable. That is the whole point of this discussion. This mechanism will deal with all the verbosity I mentioned above but, since it’s reusable, that’s not a problem. These mechanisms are called generators and they’re simple functions that return Composition objects.
- Finally, we want to be able to mix generators in order to produce more complex effects. For example, we might want to apply some special effect to an image containing a rendered scene. And then overlay UI elements on top of it. So, the generators receive an optional Composition argument, which can be augmented with new objects (and it should produce images).
So, how do all that look like in practice?
Composition myGenerator( void )
{
Composition cmp;
auto color = cmp.create< Attachment >( "color" );
auto depth = cmp.create< Attachment >( "depth" );
auto renderPass = cmp.create< RenderPass >();
renderPass->attachments = { color, depth };
renderPass->recordCommands();
cmp->setOutput( color ); // the main attachment
return cmp;
}
Composition anotherGenerator( Composition cmp )
{
auto baseColor = cmp.getOutput();
auto color = cmp.create< Attachment >( "anotherColor" );
auto descriptorSet = cmp.create< DescriptorSet >();
descriptorSet->descriptors = {
Descriptor {
.type = TEXTURE,
.texture = baseColor->getTexture(),
},
};
auto renderPass = cmp.create< RenderPass >();
renderPass->attachments = { color };
renderPass->descriptors = descriptorSet;
renderPass->recordCommands();
return cmp;
}
auto finalComposition = anotherGenerator( myGenerator() );
A more real-world example might look like this:
namespace crimild {
namespace compositions {
Composition present( Composition cmp );
Composition sepia( Composition cmp );
Composition vignette( Composition cmp );
Composition overlay( Composition cmp1, Composition cmp2 );
// pure generators
Composition renderScene( Node *scene );
Composition renderUI( Node *ui );
}
}
auto composition = present(
overlay(
sepia( vignette( renderScene( aScene ) ) ),
renderUI( aUI )
)
);
Notice how some generators can augment existing compositions in order to apply effects. For this purpose, they can access existing attachments (or maybe other resources) inside the composition by name.
Also, renderScene and renderUI are consider pure generators, since they will create a new composition from scratch (it receives no composition argument).
Finally, overlay takes two compositions and produce a new one that is a mix of both. In this case, both input compositions are merged. Then, the resulting one contains all objects.
Now it’s really easy to create new applications combining these compositions together:
I even when as far as creating a debug composition generator, that takes every single attachment ever created by other generators and display them on screen:
Final Thoughs
I like this approach because it’s simple and we can combine different generators together. Performance is not the best at the moment, since every time we pass a composition from one generator to another we’re (probably?) copying the internal collections (not the objects themselves, though), which is not great.
This is done only once in our app (usually at the very beginning), which is not that bad, but it might not be a good solution for performance-heavy applications or games.
Yet, it’s more than enough for examples or simple simulations, which is exactly what I needed.
CRIMILD 