Effect Metatags

In evergine the effect are written in HLSL languages, but to automatize some tasks evergine includes additional tags that you can add to the HLSL code.

Block Metatags

Effect codes are organized into two important kinds of blocks:

Block	Tags	Description
Resource Layout	[Begin_ResourceLayout] [End_ResourceLayout]	This block of code defines all resources (Constant Buffers, Structured Buffers, Textures and Samplers) using all effect passes.
Pass	[Begin_Pass:PassName] [End_Pass]	This block of code defines a RenderPipeline pass. The DefaultRenderPipeline defines 3 passes that any effect can define: ZPrePass, Distortion, Default

Directives Metatags

Inside of resource layout block you can define the directive set that your custom effect will have. The directives are useful to enable different features of your effect.

A directive can be defined as two values On/Off feature or can define a feature with multiple values:
[Directive:Name A_OFF A]
[Directive:Name A_OFF B C D ...]

Example:
[Directive:NormalMapping Normal_OFF, Normal]
[Directive:ShadowFilter Shadow_OFF, ShadowFilter3 ShadowFilter5 ShadowFilter7]

An effect is a set of the shader (known as Uber-shader) and the directive help you to define this set of the shader. The directives generate automatically multiple shaders with the effects is compiled.

Example:
[Directive:Name A_OFF A] will generate a shader with A enabled and another shader with A disabled.
[Directive:Name A_OFF B C D ...] will generate an A, B, C, D ... shaders.

Additionally, if you define several directives, it will multiply the combinations. In that case, if you define two directives:
[Directive:FeatureA A_OFF A]
[Directive:FeatureB B_OFF C D]
It will generate the following shader combinations: A_OFF-B_OFF, A-B_OFF, A_OFF-C, A-C , A_OFF-D, A-D

The number of combination are multiplied by the number of effect passes so a complex effect would have hundreds or thousands of combinations.

The effects can compile his combination on-demand in runtime or pre-compiled combination before and use it later in runtime without compile. So you generate a bundle with compiled shader combinations. To know more details go to this section

You can shape your effect code with the #if #else and #endif preprocessor directives:

#if TEX
    // This code is compiled only if TEX directive is used...
    finalColor = ColorTexture.Sample(ColorSampler, input.Tex); 
#else
    // If TEX directive is not present, reach this code...
    finalColor = ColorAttribute; 
#endif

Or use any directive combinations:

#if TEX || NORMAL
    // This code is compiled only if TEX and NORMAL directives are used...
    output.texCoord = input.TexCoord; 
#endif

Default Values Metatag

Evergine allows to inject default values in constant buffer attributes automatically using tags.

Default values can be injected directly using the [Default(value)] tag:

cbuffer Parameters : register(b0)
{
    float SpeedFactor : packoffset(c0.x); [Default(1.5)]
    float3 Position   : packoffset(c0.y); [Default(2.3, 3.3, 5.6)]
}

Default value tag supports the following types: int, float, bool, float, float2, float3, float4.

Inject Engine parameters

Evergine allows injecting engine data to resource layout resources (Constant Buffers attributes and Textures) automatically using tags.

For example, in the following code, the [WorldViewProjection] metatag is used to inject the object world view projection matrix:

cbuffer PerDrawCall : register(b0)
{
    float4x4 WorldViewProj    : packoffset(c0);    [WorldViewProjection]
};

List of Parameter Tag

Here you can find a complete list of available parameter tag that you can use into your effects:

Parameters Tag	Type	Update Policy	Description
[FrameID]	long	PerFrame	Gets Frame ID.
[DrawContextID]	int	PerView	Gets drawcontext ID.
[DrawContextViewIndex]	int	PerView	Gets the view index of this draw context. A draw context can contains several views (cascade shadow, point light shadows, reflection probe, etc...).
[World]	Matrix4x4	PerDrawCall	Gets the world value of the current render mesh.
[View]	Matrix4x4	PerView	Gets the view value of the current camera.
[ViewInverse]	Matrix4x4	PerView	Gets the view inverse value of the current camera.
[Projection]	Matrix4x4	PerView	Gets the projection value of the current camera.
[UnjitteredProjection]	Matrix4x4	PerView	Gets the unjittered projection value of the current camera.
[ProjectionInverse]	Matrix4x4	PerView	Gets the projection inverse value of the current camera.
[ViewProjection]	Matrix4x4	PerView	Gets the view projection value of the current camera.
[UnjitteredViewProjection]	Matrix4x4	PerView	Gets the unjittered view projection value of the current camera.
[PreviousViewProjection]	Matrix4x4	PerView	Gets the view projection value of the current camera in the previous frame.
[WorldViewProjection]	Matrix4x4	PerDrawCall	Gets the world view projection value of the current camera and mesh.
[UnjitteredWorldViewProjection]	Matrix4x4	PerDrawCall	Gets the unjittered (TAA) world view projection value of the current camera and mesh.
[WorldInverse]	Matrix4x4	PerDrawCall	Gets the inverse world value of the current render mesh.
[WorldInverseTranspose]	Matrix4x4	PerDrawCall	Gets the world inverse transpose of the current mesh.
[Time]	float	PerFrame	Gets the time value since the game has started.
[CameraPosition]	Vector3	PerView	Gets the position value of the current camera.
[CameraJitter]	Vector2	PerView	Gets the current frame camera jittering.
[CameraPreviousJitter]	Vector2	PerView	Gets the previous frame camera jittering.
[CameraRight]	Vector3	PerView	Gets the right component of the camera orientation.
[CameraUp]	Vector3	PerView	Gets the up component of the camera orientation.
[CameraForward]	Vector3	PerView	Gets the forward component of the camera orientation.
[CameraFocalDistance]	float	PerView	Gets the camera focal distance (used with DoF).
[CameraFocalLength]	float	PerView	Gets the camera focal length.
[CameraAperture]	float	PerView	Gets the camera aperture.
[CameraExposure]	float	PerView	Gets the camera exposure.
[CameraFarPlane]	float	PerView	Gets the far plane of the camera.
[CameraNearPlane]	float	PerView	Gets the near plane of the camera.
[ViewProjectionInverse]	Matrix4x4	PerView	Gets the inverse of the view projection value of the current camera.
[MultiviewCount]	int	PerView	Gets the number of eyes to be rendered.
[MultiviewProjection]	Matrix4x4	PerView	Gets the stereo camera projection.
[MultiviewView]	Matrix4x4	PerView	Gets the stereo camera view.
[MultiviewViewProjection]	Matrix4x4	PerView	Gets the stereo camera view projection.
[MultiviewViewProjectionInverse]	Matrix4x4	PerView	Gets the stereo camera inverse view projection.
[MultiviewPosition]	Vector4	PerView	Gets the stereo camera view.
[ForwardLightMask]	ulong	PerDrawCall	Gets the lighting mask, used in Forward passes.
[LightCount]	uint	PerView	Gets the number of lights.
[LightBuffer]	IntPtr	PerView	Gets the light buffer ptr.
[LightBufferSize]	uint	PerView	Gets the light buffer size.
[ShadowViewProjectionBuffer]	IntPtr	PerView	Gets the shadow view projection buffer pointer.
[ShadowViewProjectionBufferSize]	uint	PerView	Gets the shadow view projection buffer size.
[IBLMipMapLevel]	uint	PerFrame	Gets the IBL texture mipmap level.
[IBLLuminance]	float	PerFrame	Gets the IBL luminance.
[IrradianceSH]	IntPtr	PerFrame	Gets the irradiance spherical harmonics buffer ptr.
[IrradianceSHBufferSize]	uint	PerFrame	Gets the irradiance spherical harmonics buffer size.
[EV100]	float	PerView	Gets the Exposition Value at ISO 100.
[Exposure]	float	PerView	Gets the camera exposure.
[SunDirection]	Vector3	PerFrame	Gets the sun direction.
[SunColor]	Vector3	PerFrame	Gets the sun color.
[SunIntensity]	float	PerFrame	Gets the sun intensity.
[SkyboxTransform]	Matrix4x4	PerFrame	Gets the skybox transform.

Texture Tag	Description
[Framebuffer]	Framebuffer texture.
[DepthBuffer]	Depthbuffer texture.
[GBuffer]	GBuffer texture.
[Lighting]	Lighting texture.
[DFGLut]	Lookup table for DFG precalculated texture.
[IBLRadiance]	IBL Prefiltered Mipmapped radiance environment texture.
[ZPrePass]	ZPrePass in forward rendering (Normal + Roughness).
[DistortionPass]	Distortion pass in forward rendering.
[IBLIrradiance]	IBL diffuse irradiance map.
[TemporalHistory]	Temporal AA history texture.
[DirectionalShadowMap]	Shadow map array texture.
[SpotShadowMap]	Shadow map array texture.
[PunctualShadowMap]	Shadow map array cube texture.
[Custom`0..N`]	Custom renderpipeline texture.

Pass Settings Metatags

These tags are used inside of a pass block code and are useful to configure which settings do you want to compile this pass.

Tag	Description
[Profile `API_Level`]	Defines HLSL language version and capabilities. The API level values could be: 9_1: DirectX9.1 HLSL 3.0. 9_2: DirectX 9.2 HLSL 3.0 9_3: DirectX 9.3 HLSL 3.0 10_0: DirectX 10 HLSL 4.0 10_1: DirectX 10.1 HLSL 4.1 11_0: DirectX 11 HLSL 5.0 11_1: DirectX 11 HLSL 5.0 12_0: DirectX 12 HLSL 6.0 12_1: DirectX 12 HLSL 6.1 12_3: DirectX 12 HLSL 6.3 (Raytracing)
[Entirypoints `Stage=MethodName`]	Defines the entrypoint stage methods of the pass. The valid stages values are: VS: Vertex Shader. HS: Hull Shader. DS: Domain Shader. GS: Geometry Shader. PS: Pixel Shader. CS: Compute Shader.
[Mode `value`]	Defines the compilation mode of the pass. Available mode list: None: Default compilation mode. Debug: Debug mode includes depuration symbols to analyze with shader tools like RenderDoc, PIX or NVidia Nsight Graphics. See Profile with Renderdoc for more useful information. Release: Optimize compilation mode.
[RequiredWidth `Directive`]	Defines the directive list required by the pass. Example: [RequiredWith VCOLOR] the renderpipeline run this pass only when VCOLOR directive is enabled.

Override Render Layer Metatags

These tags allow the pass to modify the render layer properties when the render pipeline runs this pass. To know more details about the RenderLayer properties read this section:

Rasterization Process Tag	Description
[FillMode `Value`]	Determines the fill mode to use when rendering. Available values: WireFrame or Solid
[CullMode `Value`]	Indicates triangles facing the specified direction are not drawn. Available values: None, Front or Back
[FrontCounterClockwise `bool`]	Determines if a triangle is front- or back-facing. If this parameter is true, a triangle will be considered front-facing if its vertices are counter-clockwise on the render target and considered back-facing if they are clockwise. Available values: True or false
[DepthBias `int`]	Depth value added to a given pixel. The value is an integer.
[DepthBiasClamp `float`]	Maximum depth bias of a pixel. The value is a float [0-1].
[SlopeScaledDepthBias `float`]	Scalar on a given pixel's slope. The value is a float.
[DepthClipEnable `bool`]	Enable clipping based on distance. Available values: True or False
[ScissorEnable `bool`]	Enable scissor-rectangle culling. All pixels outside an active scissor rectangle are culled. Available values: True or False
[AntialiasedLineEnable `bool`]	Specifies whether to enable line antialiasing; only applies if doing line drawing and MultisampleEnable is false. Available values: True or _False.

Blend State Tag	Description
[AlphaToCoverageEnable `bool`]	Specifies whether to use alpha-to-coverage as a multisampling technique when setting a pixel to a render target. Available values: True or _False.
[IndependentBlendEnable `bool`]	Specifies whether to enable independent blending in simultaneous render targets. Set to true to enable independent blending. If set to false, only the RenderTarget[0] members are used; RenderTarget[1..7] are ignored. Available values: True or _False.
[RT0BlendEnable `bool`]	Enable (or disable) blending for RenderTarget 0. Available values: True or _False.
[RT0SourceBlendColor `Value`]	This blend option specifies the operation to perform on the RGB value that the pixel shader outputs. The BlendOp member defines how to combine the SrcBlend and DestBlend operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha_ or InverseSecondarySourceAlpha.
[RT0DestinationBlendColor `Value`]	This blend option specifies the operation to perform on the current RGB value in the render target. The BlendOp member defines how to combine the SrcBlend and DestBlend operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha_ or InverseSecondarySourceAlpha.
[RT0BlendOperationColor `Value`]	This blend operation defines how to combine the SrcBlend and DestBlend operations. Available values: Add, Substract, ReverseSubstract, Min or Max.
[RT0SourceBlendAlpha `Value`]	This blend option specifies the operation to perform on the alpha value that the pixel shader outputs. Blend options that end in COLOR are not allowed. The BlendOpAlpha member defines how to combine the SrcBlendAlpha and DestBlendAlpha operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha or InverseSecondarySourceAlpha.
[RT0DestinationBlendAlpha `Value`]	This blend option specifies the operation to perform on the current alpha value in the render target. Blend options that end in COLOR are not allowed. The BlendOpAlpha member defines how to combine the SrcBlendAlpha and DestBlendAlpha operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha or InverseSecondarySourceAlpha.
[RT0BlendOperationAlpha `Value`]	This blend operation defines how to combine the SrcBlendAlpha and DestBlendAlpha operations for RenderTarget 0. Available values: Add, Substract, ReverseSubstract, Min or Max.
[RT0ColorWriteChannels `Value`]	A write mask for Render target 0. Availables values: None, Red, Green, Blue, Alpha or All.

Depth Stencil Tag	Description
[DepthEnable `bool`]	Enable depth testing. Availables values: True or False.
[DepthWriteMask `bool`]	Identify a portion of the depth-stencil buffer that can be modified by depth data. Available values: True or False.
[DepthFunction `Value`]	A function that compares depth data against existing depth data. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[StencilEnable `bool`]	Enable stencil testing. Availables values: True or False.
[StencilReadMask `byte`]	Identify a portion of the depth-stencil buffer for reading stencil data. The value is a byte.
[StencilWriteMask `byte`]	Identify a portion of the depth-stencil buffer for writing stencil data. The value is a byte.
[FrontFaceStencilFailOperation `Value`]	The stencil operation to perform when stencil testing fails in FrontFace Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[FrontFaceStencilDepthFailOperation `Value`]	The stencil operation to perform when stencil testing passes and depth testing fails in FrontFace. Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[FrontFaceStencilPassOperation `Value`]	The stencil operation to perform when stencil testing and depth testing both pass in FrontFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[FrontFaceStencilFunction `Value`]	A function that compares stencil data against existing stencil data in FrontFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[BackFaceStencilFailOperation `Value`]	The stencil operation to perform when stencil testing fails in BackFace Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[BackFaceStencilDepthFailOperation `Value`]	The stencil operation to perform when stencil testing passes and depth testing fails in BackFace. Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[BackFaceStencilPassOperation `Value`]	The stencil operation to perform when stencil testing and depth testing both pass in BackFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[BackFaceStencilFunction `Value`]	A function that compares stencil data against existing stencil data in BackFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[StencilReference `int`]	The reference value to use when doing a stencil test. The value is a integer.