Class Gorgon2DGaussBlurEffect

A gaussian blur effect.

Inheritance
object
GorgonNamedObject
Gorgon2DEffect
Gorgon2DGaussBlurEffect
Implements
Inherited Members
Namespace: Gorgon.Renderers
Assembly: Gorgon.Renderers.Gorgon2D.dll
Syntax
public class Gorgon2DGaussBlurEffect : Gorgon2DEffect, IGorgonNamedObject, IDisposable, IGorgonGraphicsObject, IGorgon2DCompositorEffect

Constructors

| Edit this page View Source

Gorgon2DGaussBlurEffect(Gorgon2D, int)

Initializes a new instance of the Gorgon2DGaussBlurEffect class.

Declaration
public Gorgon2DGaussBlurEffect(Gorgon2D renderer, int kernelSize = 7)
Parameters
Type Name Description
Gorgon2D renderer

The renderer.
int kernelSize

[Optional] The size of the convolution kernel.
Remarks

If the kernelSize is specified, it will define the number of texels sampled (including the center) during a pass. The number of kernel taps should be an odd number for best results. For example: 

* = Sample
T = Center texel

3 tap: T


7 tap: T


9 tap: T
Keep in mind that the more taps requested, the more texel reads that are required and will have a negative performance impact.
Exceptions
Type Condition
ArgumentNullException

Thrown when the renderer parameter is null.
ArgumentOutOfRangeException

Thrown when the kernelSize is less than 3 or greater than 81.

Properties

| Edit this page View Source

BlurRadius

Property to set or return the radius of the number of pixels to sample when blurring.

Declaration
public int BlurRadius { get; set; }
Property Value
Type Description
int
Remarks

This property will adjust the amount of data for the blur kernel. Setting this value has the effect of increasing or lowering the amount of blur applied to the image. This value indicates how many texels will be sampled on either side of the center texel that is being blurred.

For example, setting the blur radius to 2 with a KernelSize of 7 will result in 2 texels being sampled on either side of the of the center texel, giving a maximum of a 5 tap sampling: 

T = Center texel
* = Samples

Max Kernel Size = 7, Max radius size = 3.


Radius = 3 -> T (7 taps)
Radius = 2 -> T (5 taps)
Radius = 1 -> T (3 taps)
Radius = 0 -> Blur disabled.

The valid range of values are within the range of 0 (no blurring) to MaximumBlurRadius.

The default value is 1.

warning

Higher values will increase the quality of the blur, but will cause the shader to run slower because more samples will need to be taken.

For optimal performance, it is not recommended to adjust this value in a real time scenario as it will recalculate the weights and offsets and upload them to the shader.

See Also
| Edit this page View Source

BlurRenderTargetsSize

Property to set or return the size of the internal render targets used for blurring.

Declaration
public Size2 BlurRenderTargetsSize { get; set; }
Property Value
Type Description
Size2
Remarks

This is used to adjust the size of a render target for more accurate blurring (at the expense of performance and video memory).

This value is limited to 3x3 up to the maximum width and height specified by MaxTextureWidth and MaxTextureHeight.

The default size is 256x256.

warning

Increasing the render target size will have a performance impact due to the number of texels being processed. It is recommended to scale this size based on your target video adapter(s) capabilities.

| Edit this page View Source

BlurTargetFormat

Property to set or return the format of the internal render targets used for blurring.

Declaration
public BufferFormat BlurTargetFormat { get; set; }
Property Value
Type Description
BufferFormat
Remarks

This is the default texture surface format for the internal render targets used for blurring. This value may be any type of format supported by a render target (see FormatSupport for determining an acceptable format).

If this value is set to an unacceptable format, then the effect will throw an exception during rendering.

The default value is R8G8B8A8_UNorm

See Also
| Edit this page View Source

KernelSize

Property to return the size of the convolution kernel used to apply weighting against pixel samples when blurring.

Declaration
public int KernelSize { get; }
Property Value
Type Description
int
| Edit this page View Source

MaximumBlurRadius

Property to return the maximum size of the BlurRadius property.

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

This value is derived by using 1/2 of the KernelSize without the center texel. For example, if the KernelSize is 7, then this value will be: (7 - 1) / 2 = 3. We see here that the kernel size is decremented by 1, which is the equivalent of removing the center texel, and then divided by 2 giving a result of 3 texels on either side of the center texel that can be sampled.

See Also
| Edit this page View Source

PreserveAlpha

Property to set or return whether to blur the alpha channel or not.

Declaration
public bool PreserveAlpha { get; set; }
Property Value
Type Description
bool
Remarks

If this value is true, then the alpha channel will be excluded when performing the weighting when blurring. In this case, the alpha will be taken directly from the texture and applied as-is. If it is false, then the alpha values have weighting applied from the blur kernel and as a result, will be blurred along with the color information.

The default value is false.

Methods

| Edit this page View Source

BlurTexture(GorgonTexture2DView, int)

Function called to render a single effect pass.

Declaration
protected void BlurTexture(GorgonTexture2DView texture, int passIndex)
Parameters
Type Name Description
GorgonTexture2DView texture

The texture to blur.
int passIndex

The index of the pass being rendered.
Remarks

Applications must implement this in order to see any results from the effect.

| Edit this page View Source

Dispose(bool)

Releases unmanaged and - optionally - managed resources.

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

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

OnAfterRender(GorgonRenderTargetView)

Function called after rendering is complete.

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

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

Applications can use this to clean up and/or restore any states when rendering is finished. This is an ideal method to copy any rendering imagery to the final output render target.

| Edit this page View Source

OnBeforeRender(GorgonRenderTargetView, bool)

Function called prior to rendering.

Declaration
protected override 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.
Overrides
Remarks

Applications can use this to set up common states and other configuration settings prior to executing the render passes. This is an ideal method to initialize and resize your internal render targets (if applicable).

| Edit this page View Source

OnBeforeRenderPass(int, GorgonRenderTargetView, GorgonCameraCommon)

Function called prior to rendering a pass.

Declaration
protected override 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.
Overrides
Remarks

Applications can use this to set up per-pass states and other configuration settings prior to executing a single render pass.

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 override Gorgon2DBatchState OnGetBatchState(int passIndex, IGorgon2DEffectBuilders builders, bool statesChanged)
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 statesChanged

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

The 2D batch state.
Overrides
| Edit this page View Source

OnInitialize()

Function called when the effect is initialized for the first time.

Declaration
protected override void OnInitialize()
Overrides
| Edit this page View Source

Render(GorgonTexture2DView, GorgonRenderTargetView)

Function to render the effect.

Declaration
public void Render(GorgonTexture2DView texture, GorgonRenderTargetView output)
Parameters
Type Name Description
GorgonTexture2DView texture

The texture to blur and render to the output.
GorgonRenderTargetView output

The output render target.
Remarks

important

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

Exceptions
Type Condition
ArgumentNullException

Thrown when the texture, or the output parameter is null.

Implements

Extension Methods