Class Gorgon2DEffect

A base class used to implement special effects for 2D rendering.

Inheritance
object
GorgonNamedObject
Gorgon2DEffect
Gorgon2D1BitEffect
Gorgon2DBloomEffect
Gorgon2DBurnDodgeEffect
Gorgon2DChromaticAberrationEffect
Gorgon2DDisplacementEffect
Gorgon2DGBuffer
Gorgon2DGaussBlurEffect
Gorgon2DGrayScaleEffect
Gorgon2DInvertEffect
Gorgon2DLightingEffect
Gorgon2DOldFilmEffect
Gorgon2DPosterizedEffect
Gorgon2DSharpenEmbossEffect
Gorgon2DSilhouetteEffect
Gorgon2DSobelEdgeDetectEffect
Gorgon2DWaveEffect
Implements
Inherited Members
Namespace: Gorgon.Renderers
Assembly: Gorgon.Renderers.Gorgon2D.dll
Syntax
public abstract class Gorgon2DEffect : GorgonNamedObject, IGorgonNamedObject, IDisposable, IGorgonGraphicsObject
Remarks

This class allows developers to build special effects utilizing shaders and various states by wrapping them in a custom object to simplify rendering with the aforementioned shaders and states.

Effects can operate in any way the developer deems appropriate as long as the internal code executes in the correct order. In Gorgon, the predefined effects such as Guassian Blur operate in one of 3 modes: Immediate, Render texture, or both. The immediate mode works in the same way as the Gorgon2D renderer, by calling a Begin and End method and rendering the various graphics types in between the Begin/End calls. The Render Texture mode will take a GorgonTexture2DView (often the output of a render target) and render it into a GorgonRenderTargetView. This mode would usually be used in post processing.

Rendering in an effect is usually done in 1 or more passes. With each pass usually building on the result of the previous pass. Developers are free to expose each pass to the end user for custom rendering at each stage, wrap up the passes into a single method, or whatever they may deem appropriate.

To create a custom effect, applications should inherit this class and override the appropriate methods to set up state, and perform rendering pass(es). Gorgon has multiple predefined effects that developers can examine for reference.

Constructors

| Edit this page View Source

Gorgon2DEffect(Gorgon2D, string, string, int)

Initializes a new instance of the Gorgon2DEffect class.

Declaration
protected Gorgon2DEffect(Gorgon2D renderer, string effectName, string effectDescription, int passCount)
Parameters
Type Name Description
Gorgon2D renderer

The 2D renderer used to render the effect.
string effectName

Name of the effect.
string effectDescription

The effect description.
int passCount

The number of passes required to render the effect.
Exceptions
Type Condition
ArgumentNullException

Thrown when the renderer, or the effectName parameter is null.
ArgumentEmptyException

Thrown when the effectName parameter is empty.
See Also

Properties

| Edit this page View Source

BatchStateAllocator

Property to return the allocator to use with batch states.

Declaration
protected Gorgon2DBatchStatePoolAllocator BatchStateAllocator { get; }
Property Value
Type Description
Gorgon2DBatchStatePoolAllocator
Remarks

Allocators are used to reuse objects to limit garbage collection pressure. These should be used in cases where there's states are being updated every frame, or even multiple times per frame.

See Also
| Edit this page View Source

Description

Property to return a friendly description of the effect.

Declaration
public string Description { get; }
Property Value
Type Description
string
See Also
| Edit this page View Source

Graphics

Property to return the graphics object used for rendering.

Declaration
public GorgonGraphics Graphics { get; }
Property Value
Type Description
GorgonGraphics
See Also
| Edit this page View Source

Macros

Property to return the macros to apply to the shader.

Declaration
protected List<GorgonShaderMacro> Macros { get; }
Property Value
Type Description
List<GorgonShaderMacro>
Remarks

A list of GorgonShaderMacro values to send to any pixel/vertex shaders used by the effect. These can be used to turn on/off pieces of the shader code when compiling.

See Also
| Edit this page View Source

PassCount

Property to return the number of passes required to render the effect.

Declaration
public virtual int PassCount { get; }
Property Value
Type Description
int
Remarks

This is merely for information, passes may or may not be exposed to the end user by the effect author.

See Also
| Edit this page View Source

PixelShaderAllocator

Property to return the allocator to use with pixel shader states.

Declaration
protected Gorgon2DShaderStatePoolAllocator<GorgonPixelShader> PixelShaderAllocator { get; }
Property Value
Type Description
Gorgon2DShaderStatePoolAllocator<GorgonPixelShader>
Remarks

Allocators are used to reuse objects to limit garbage collection pressure. These should be used in cases where there's states are being updated every frame, or even multiple times per frame.

See Also
| Edit this page View Source

Renderer

Property to return the renderer used to render the effect.

Declaration
public Gorgon2D Renderer { get; }
Property Value
Type Description
Gorgon2D
See Also
| Edit this page View Source

VertexShaderAllocator

Property to return the allocator to use with vertex shader states.

Declaration
protected Gorgon2DShaderStatePoolAllocator<GorgonVertexShader> VertexShaderAllocator { get; }
Property Value
Type Description
Gorgon2DShaderStatePoolAllocator<GorgonVertexShader>
Remarks

Allocators are used to reuse objects to limit garbage collection pressure. These should be used in cases where there's states are being updated every frame, or even multiple times per frame.

See Also

Methods

| Edit this page View Source

BeginPass(int, GorgonRenderTargetView, GorgonCameraCommon)

Function to render a single pass in the effect.

Declaration
protected PassContinuationState BeginPass(int index, GorgonRenderTargetView output, GorgonCameraCommon camera = null)
Parameters
Type Name Description
int index

The index of the pass.
GorgonRenderTargetView output

The render target that will receive the rendering.
GorgonCameraCommon camera

[Optional] The camera to use while rendering.
Returns
Type Description
PassContinuationState

A PassContinuationState value describing how to continue on to the next pass (if applicable).
Remarks

When the effect is ready to begin rendering a single pass, developers must call this method and ensure there's a matching call to EndPass(int, GorgonRenderTargetView). This method will begin by configuring the states via OnGetBatchState(int, IGorgon2DEffectBuilders, bool) for rendering the current effect pass, and by initializing batch rendering via the Begin(Gorgon2DBatchState, GorgonCameraCommon) method. It will also call the OnBeforeRenderPass(int, GorgonRenderTargetView, GorgonCameraCommon) method so effects can do per-pass configuration as needed.

The return value indicates whether the pass may continue on to the next pass, skip the next pass, or stop rendering altogether. These are usually in response to invalid input, or to flags turning off specific functionality. The exact operation is left up to the effect author.

warning

Nesting BeginPass calls is not supported.

important

For performance reasons, some exceptions thrown by this method will only be thrown when Gorgon is compiled as DEBUG.

Exceptions
Type Condition
ArgumentNullException

Thrown when the output parameter is null.
ArgumentOutOfRangeException

Thrown when the index parameter is less than 0, or not less than PassCount.
GorgonException

Thrown if this method is has been called once before and called again without calling EndPass(int, GorgonRenderTargetView).

-or-

Thrown if BeginRender(GorgonRenderTargetView, GorgonBlendState, GorgonDepthStencilState, GorgonRasterState) was not called prior to calling this method.
See Also
| Edit this page View Source

BeginRender(GorgonRenderTargetView, GorgonBlendState, GorgonDepthStencilState, GorgonRasterState)

Function to begin the rendering for the effect.

Declaration
protected void BeginRender(GorgonRenderTargetView output, GorgonBlendState blendState = null, GorgonDepthStencilState depthStencilState = null, GorgonRasterState rasterState = null)
Parameters
Type Name Description
GorgonRenderTargetView output

The render target that will receive the rendering.
GorgonBlendState blendState

[Optional] The blend state to apply.
GorgonDepthStencilState depthStencilState

[Optional] The depth stencil state to apply.
GorgonRasterState rasterState

[Optional] The raster state to apply.
Remarks

When the effect is ready to begin rendering, developers must call this method first and ensure there's a matching call to EndRender(GorgonRenderTargetView). This informs the effect that its default states need to be initialized (if not done so prior to calling), handle any render target output size changes, and call any required setup from the effect via the OnBeforeRender(GorgonRenderTargetView, bool) method.

The optional parameters allow effect authors to pass in user defined states from outside of the effect so that end users may customize rendering. In Gorgon's predefined effects, the immediate mode (Begin/End) effects take these parameters, while render target rendering does not.

warning

Nesting BeginRender calls is not supported.

important

For performance reasons, some exceptions thrown by this method will only be thrown when Gorgon is compiled as DEBUG.

Exceptions
Type Condition
ArgumentNullException

Thrown when the output parameter is null.
GorgonException

Thrown if this method is has been called once before and called again without calling EndRender(GorgonRenderTargetView).
See Also
| Edit this page View Source

CompileShader<T>(string, string)

Function to create a shader for use with the effect.

Declaration
protected T CompileShader<T>(string shaderSource, string entryPoint) where T : GorgonShader
Parameters
Type Name Description
string shaderSource

The source code for the shader.
string entryPoint

The entry point function in the shader to execute.
Returns
Type Description
T

A new shader of type T.
Type Parameters
Name Description
T

The type of shader. Must inherit from GorgonShader.
Remarks

This is convenience method used to compile a shader from source code. Users may wish to use the GorgonShaderFactory class for more robust functionality.

Exceptions
Type Condition
ArgumentNullException

Thrown when the shaderSource, or the entryPoint parameter is null.
ArgumentEmptyException

Thrown when the shaderSource, or the entryPoint parameter is empty.
GorgonException

Thrown if the shader fails to compile.
See Also
| Edit this page View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()
See Also
| Edit this page View Source

Dispose(bool)

Releases unmanaged and - optionally - managed resources.

Declaration
protected abstract void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.
See Also
| Edit this page View Source

EndPass(int, GorgonRenderTargetView)

Function to end the render pass.

Declaration
protected void EndPass(int index, GorgonRenderTargetView output)
Parameters
Type Name Description
int index

The index of the pass.
GorgonRenderTargetView output

The final output target.
Remarks

This is called to notify the effect that the pass is now finished rendering and that we can move on to a new pass (or finish rendering completely if that's what's required). This method is responsible for calling the End() method to finish 2D rendering, and will call the OnAfterRender(GorgonRenderTargetView) to perform any last minute clean up, or last minute rendering for the pass.

important

For performance reasons, any exceptions thrown by this method will only be thrown when Gorgon is compiled as DEBUG.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when the index parameter is less than 0, or not less than PassCount.
See Also
| Edit this page View Source

EndRender(GorgonRenderTargetView)

Function to end rendering for the effect.

Declaration
protected void EndRender(GorgonRenderTargetView output)
Parameters
Type Name Description
GorgonRenderTargetView output

The final output target.
Remarks

This informs the effect that rendering is done. It will trigger the OnAfterRender(GorgonRenderTargetView) method so that effect authors can perform any last minute rendering, or clean up. The method must be called whenever BeginRender(GorgonRenderTargetView, GorgonBlendState, GorgonDepthStencilState, GorgonRasterState) is called or else an exception will be thrown.

Null can be passed to the output method to indicate that the OnAfterRender(GorgonRenderTargetView) method should not be called, this is usually done when a pass is stopped prematurely via one of the PassContinuationState values.

important

For performance reasons, any exceptions thrown by this method will only be thrown when Gorgon is compiled as DEBUG.

See Also
| Edit this page View Source

OnAfterRender(GorgonRenderTargetView)

Function called after rendering is complete.

Declaration
protected virtual void OnAfterRender(GorgonRenderTargetView output)
Parameters
Type Name Description
GorgonRenderTargetView output

The final render target that will receive the rendering from the effect.
Remarks

This method is called after all passes are finished and the effect is ready to complete its rendering. Developers should override this method to finalize any custom rendering. For example an effect author can use this method to render the final output of an effect to the final render target.

See Also
| Edit this page View Source

OnAfterRenderPass(int, GorgonRenderTargetView)

Function called after a pass is finished rendering.

Declaration
protected virtual void OnAfterRenderPass(int passIndex, GorgonRenderTargetView output)
Parameters
Type Name Description
int passIndex

The index of the pass that was rendered.
GorgonRenderTargetView output

The final render target that will receive the rendering from the effect.
Remarks

This method is called after rendering a single pass. Developers may use this to perform any clean up required, or any last minute rendering at the end of a pass.

important

The Gorgon2D.End() method is already called prior to this method. Developers are free to use Begin(Gorgon2DBatchState, GorgonCameraCommon) and End() to perform any last minute rendering (e.g. blending multiple targets together into the output).

See Also
| Edit this page View Source

OnBeforeRender(GorgonRenderTargetView, bool)

Function called prior to rendering.

Declaration
protected virtual void OnBeforeRender(GorgonRenderTargetView output, bool sizeChanged)
Parameters
Type Name Description
GorgonRenderTargetView output

The final render target that will receive the rendering from the effect.
bool sizeChanged

true if the output size changed since the last render, or false if it's the same.
Remarks

This method is called prior to rendering the effect (before any passes). It allows an effect to do any required effect set up that's not specific to a pass. For example, this method could be used to send a view matrix to a shader via a constant buffer since the view matrix will unlikely change between passes.

Developers should override this method to perform any required setup prior to rendering a pass.

See Also
| Edit this page View Source

OnBeforeRenderPass(int, GorgonRenderTargetView, GorgonCameraCommon)

Function called prior to rendering a pass.

Declaration
protected virtual PassContinuationState OnBeforeRenderPass(int passIndex, GorgonRenderTargetView output, GorgonCameraCommon camera)
Parameters
Type Name Description
int passIndex

The index of the pass to render.
GorgonRenderTargetView output

The final render target that will receive the rendering from the effect.
GorgonCameraCommon camera

The currently active camera.
Returns
Type Description
PassContinuationState

A PassContinuationState to instruct the effect on how to proceed.
Remarks

This method is called prior to rendering a single pass. It allows per-pass configuration to be done prior to the actual rendering. Developers should override this method if shader data needs to be updated on every pass.

The return value is a PassContinuationState which allows developers to skip specific passes if criteria isn't met, or stop rendering altogether.

important

The Gorgon2D.Begin(Gorgon2DBatchState, GorgonCameraCommon) method is already called prior to this method. Developers must not call Begin(Gorgon2DBatchState, GorgonCameraCommon) while rendering a pass, or else an exception will be thrown.

See Also
| Edit this page View Source

OnGetBatchState(int, IGorgon2DEffectBuilders, bool)

Function called to build a new (or return an existing) 2D batch state.

Declaration
protected abstract Gorgon2DBatchState OnGetBatchState(int passIndex, IGorgon2DEffectBuilders builders, bool defaultStatesChanged)
Parameters
Type Name Description
int passIndex

The index of the current rendering pass.
IGorgon2DEffectBuilders builders

The builder types that will manage the state of the effect.
bool defaultStatesChanged

true if the blend, raster, or depth/stencil state was changed. false if not.
Returns
Type Description
Gorgon2DBatchState

The 2D batch state.
Remarks

This method is responsible for initializing and setting up a rendering state for a pass. State changes (e.g. blend states change, additonal textures needed, etc...) are also handled by this method. Note that the defaultStatesChanged parameter indicates that the user has changed the default effect states when initially rendering (i.e. not per pass).

Developers must take care with this method when creating state objects. Constant discarding and creating of states can get expensive as the garbage collector needs to kick in and release the memory occupied by the states. To help alleviate constant state changes between passes, of the allocator properties in this class may be used to reuse state objects. The rule of thumb however is to create a state once, and then just return that state and only recreate when absolutely necessary. Sometimes that's never, other times it's when the swap chain resizes, and other times it may be on every pass. These conditions depend on the requirements of the effect.

See Also
| Edit this page View Source

OnInitialize()

Function called to initialize the effect.

Declaration
protected abstract void OnInitialize()
Remarks

This method is called to allow the effect to initialize. Developers must override this method to compile shaders, constant buffers, etc... and set up any initial values for the effect.

See Also
| Edit this page View Source

Precache()

Function to precache resources and initlaize the effect prior to renderering.

Declaration
public void Precache()
Remarks

For most effects, there's not a lot to set up or initialize when the rendering starts. But, in some cases, some effects have a considerable amount of work to do prior to rendering. This method allows an application to pre cache any initialization data after the effect is created, instead of on the 1st render frame (where it may introduce a stutter).

See Also

Implements

Extension Methods

See Also