Class GraphicsCompositorExtensions

Namespace

Stride.CommunityToolkit.Rendering.Compositing

Assembly

Stride.CommunityToolkit.dll

Extension methods for GraphicsCompositor: UI stages, scene renderers, post effects, particles and render stages.

public static class GraphicsCompositorExtensions

Inheritance

object

GraphicsCompositorExtensions

Methods

AddCleanUIStage(GraphicsCompositor)

Adds a UI render stage to the given GraphicsCompositor and resets its post effects to tone mapping only, so UI text and shapes come out clean and white rather than bloomed or blurred. This alters the GraphicsCompositor's PostProcessingEffects, RenderStage, and RenderFeature.

public static GraphicsCompositor AddCleanUIStage(this GraphicsCompositor graphicsCompositor)

Parameters

graphicsCompositor GraphicsCompositor

The GraphicsCompositor to modify.

Returns

GraphicsCompositor

Returns the modified GraphicsCompositor instance, allowing for method chaining.

Examples

game.AddGraphicsCompositor().AddCleanUIStage();

Remarks

"Reset" means what CreateDefault(bool, string, CameraComponent, Color4?, GraphicsProfile, RenderGroupMask) produces: a PostProcessingEffects with every effect disabled except the colour transforms, which hold a ToneMap, unlike a bare new PostProcessingEffects(), which enables bloom, ambient occlusion, screen-space reflections, light streaks, lens flare and FXAA. Enable effects after this call, not before it.

Renderers already hanging off the compositor (see AddSceneRenderer(GraphicsCompositor, SceneRendererBase)) are kept; the UI stage is drawn last, after them.

AddParticleStagesAndFeatures(GraphicsCompositor)

Adds particle rendering stages and features to the specified graphics compositor.

public static void AddParticleStagesAndFeatures(this GraphicsCompositor graphicsCompositor)

Parameters

graphicsCompositor GraphicsCompositor

The graphics compositor to which the particle stages and features will be added.

Remarks

This method configures the graphics compositor to support particle rendering by adding a ParticleEmitterRenderFeature. It requires the presence of both "Opaque" and "Transparent" render stages in the compositor. The method will throw a NullReferenceException if either stage is missing.

Exceptions

NullReferenceException

Thrown if the "Opaque" or "Transparent" render stage is not found in the graphics compositor.

AddRootRenderFeature(GraphicsCompositor, RootRenderFeature)

Adds a root render feature to the specified graphics compositor.

public static void AddRootRenderFeature(this GraphicsCompositor graphicsCompositor, RootRenderFeature renderFeature)

Parameters

graphicsCompositor GraphicsCompositor

The graphics compositor to which the render feature will be added. Cannot be null.

renderFeature RootRenderFeature

The root render feature to add. Cannot be null.

AddSceneRenderer(GraphicsCompositor, SceneRendererBase)

Adds a new scene renderer to the specified GraphicsCompositor's game. If the game is already a scene renderer collection, the new scene renderer is added to that collection. Otherwise, a new scene renderer collection is created to house both the existing game and the new scene renderer.

public static GraphicsCompositor AddSceneRenderer(this GraphicsCompositor graphicsCompositor, SceneRendererBase sceneRenderer)

Parameters

graphicsCompositor GraphicsCompositor

The GraphicsCompositor to which the scene renderer will be added.

sceneRenderer SceneRendererBase

The new SceneRendererBase instance that will be added to the GraphicsCompositor's game.

Returns

GraphicsCompositor

Returns the modified GraphicsCompositor instance, allowing for method chaining.

AddUIStage(GraphicsCompositor)

Adds a UI render stage to the given GraphicsCompositor, leaving its post effects as they are. This alters the GraphicsCompositor's RenderStage and RenderFeature.

public static GraphicsCompositor AddUIStage(this GraphicsCompositor graphicsCompositor)

Parameters

graphicsCompositor GraphicsCompositor

The GraphicsCompositor to modify.

Returns

GraphicsCompositor

Returns the modified GraphicsCompositor instance, allowing for method chaining.

Remarks

Renderers already hanging off the compositor (see AddSceneRenderer(GraphicsCompositor, SceneRendererBase)) are kept; the UI stage is drawn last, after them.

ConfigurePostEffects(GraphicsCompositor, Action<PostProcessingEffects>)

Runs configure against the compositor's post effects - the place to switch on bloom, fog, ambient occlusion and the rest, all of which start disabled.

public static GraphicsCompositor ConfigurePostEffects(this GraphicsCompositor graphicsCompositor, Action<PostProcessingEffects> configure)

Parameters

graphicsCompositor GraphicsCompositor

The compositor to configure.

configure Action<PostProcessingEffects>

Receives the live PostProcessingEffects; set Enabled and tune as needed.

Returns

GraphicsCompositor

The compositor, for chaining.

Examples

game.AddGraphicsCompositor()
    .AddCleanUIStage()
    .ConfigurePostEffects(fx =>
    {
        fx.Bloom.Enabled = true;
        fx.Fog.Enabled = true;
        fx.ColorTransforms.Transforms.Add(new Vignetting());
    });

Remarks

The default compositor ships every effect switched off and only a ToneMap in the colour transforms, so enabling is always explicit: fx.Bloom.Enabled = true. Colour transforms other than tone mapping - Vignetting, FilmGrain, Dither - are not present at all and must be added: fx.ColorTransforms.Transforms.Add(new Vignetting()).

Call this after AddCleanUIStage(GraphicsCompositor), which resets the post effects to tone mapping only; anything enabled before it is lost.

Exceptions

ArgumentNullException

graphicsCompositor or configure is null.

InvalidOperationException

The compositor has no post effects to configure.

EnsureSceneRenderer<TRenderer>(GraphicsCompositor, Func<TRenderer>)

Adds a scene renderer only if one of the same type is not already present.

public static GraphicsCompositor EnsureSceneRenderer<TRenderer>(this GraphicsCompositor graphicsCompositor, Func<TRenderer> create) where TRenderer : SceneRendererBase

Parameters

graphicsCompositor GraphicsCompositor

The GraphicsCompositor to add to.

create Func<TRenderer>

Creates the renderer, called only when one is actually needed.

Returns

GraphicsCompositor

Returns the GraphicsCompositor instance, allowing for method chaining.

Type Parameters

TRenderer

Type of renderer to ensure.

Remarks

Meant for renderers that draw everything of a given kind in the scene, where a second instance would draw everything twice rather than add anything. It lets a helper guarantee the rendering its own output depends on, without having to know whether the caller already arranged it.

GetPostEffects(GraphicsCompositor)

The compositor's post effects, or null when it has none.

public static PostProcessingEffects? GetPostEffects(this GraphicsCompositor graphicsCompositor)

Parameters

graphicsCompositor GraphicsCompositor

The compositor to look in.

Returns

PostProcessingEffects

The PostProcessingEffects on the compositor's forward renderer, or null when the single view is not a ForwardRenderer, has no post effects, or has post effects of some other type.

Remarks

The 2D compositor from Add2DGraphicsCompositor has no post effects, so it returns null.

TryGetRenderStage(GraphicsCompositor, string, out RenderStage?)

Attempts to retrieve a render stage from the specified GraphicsCompositor based on the provided effect name.

public static bool TryGetRenderStage(this GraphicsCompositor graphicsCompositor, string effectName, out RenderStage? renderStage)

Parameters

graphicsCompositor GraphicsCompositor

The GraphicsCompositor containing the render stages.

effectName string

The name of the render stage to search for.

renderStage RenderStage

When this method returns, contains the RenderStage if the render stage was found; otherwise, null. This parameter is passed uninitialized.

Returns

bool

true if the render stage is found; otherwise, false.