Class GorgonShaderFactory

A factory used to create various GorgonShader based types.

Inheritance

object

GorgonShaderFactory

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.Graphics.Core

Assembly: Gorgon.Graphics.Core.dll

Syntax

public static class GorgonShaderFactory

Remarks

This factory is used to compile from source code or load shaders from a stream or file. Shaders such as the GorgonPixelShader cannot be created by using the new keyword and must be instantiated via this factory.

Fields

BinaryShaderByteCode

The chunk ID for the chunk that contains the binary shader bytecode.

Declaration

public const string BinaryShaderByteCode = "BYTECODE"

Field Value

Type	Description
string

BinaryShaderFileHeader

The header chunk for a Gorgon binary shader file.

Declaration

public const string BinaryShaderFileHeader = "GORSHD20"

Field Value

Type	Description
string

BinaryShaderMetaData

The chunk ID for the chunk that contains metadata for the shader.

Declaration

public const string BinaryShaderMetaData = "METADATA"

Field Value

Type	Description
string

Properties

Includes

Property to return the list of GorgonShaderInclude definitions to include with compiled shaders.

Declaration

public static IDictionary<string, GorgonShaderInclude> Includes { get; }

Property Value

Type	Description
IDictionary<string, GorgonShaderInclude>

Remarks

Gorgon uses a special keyword in shaders to allow shader files to include other files as part of the source. This keyword is named #GorgonInclude and is similar to the HLSL #include keyword. The difference is that this keyword allows users to include shader source from memory instead of a separate source file. This is done by assigning a name to the included source code in the #GorgonInclude keyword, and adding the string containing the source to this property. When the include is loaded from a file, then it will automatically be added to this property.

See Also

GorgonShaderInclude

Methods

Compile<T>(GorgonGraphics, string, string, bool, IList<GorgonShaderMacro>, string)

Function to compile a shader from source code.

Declaration

public static T Compile<T>(GorgonGraphics graphics, string sourceCode, string entryPoint, bool debug = false, IList<GorgonShaderMacro> macros = null, string sourceFileName = "(in memory)") where T : GorgonShader

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface to use.
string	sourceCode	A string containing the source code to compile.
string	entryPoint	The entry point function for the shader.
bool	debug	[Optional] true to indicate whether the shader should be compiled with debug information; otherwise, false to strip out debug information.
IList<GorgonShaderMacro>	macros	[Optional] A list of macros for conditional compilation.
string	sourceFileName	[Optional] The name of the file where the source code came from.

Returns

Type	Description
T	A byte array containing the compiled shader.

Type Parameters

Name	Description
T	The type of shader to return.

Remarks

This will compile a shader from a string containing the source code for requested the shader. Applications can load a string from a text file, use an internal string or use a string resource and pass it to this method to produce shader byte code that can then be used with the shader interfaces.

When the debug flag is set to true, optimizations are turned off for the shader, and debugging information is injected into the shader to allow for debugging with Visual Studio's graphics debugging tools, or a tool like RenderDoc (highly recommended). When compiling the shader with debugging information, it is prudent to pass the full path to the file that contains the shader source in the sourceFileName. If the shader resides in memory (as a string or resource), then the parameter may be omitted if the user wishes.

For some shaders, conditional compilation allows users to create many variations of shaders from the same source code. This is not unlike the #define conditional code in C#. To pass a list of these macros, just pass a list of GorgonShaderMacro objects to the macros parameter to define which parts of the code will be compiled.

Finally, Gorgon uses a special keyword in shaders to allow shader files to include other files as part of the source. This keyword is named #GorgonInclude and is similar to the HLSL #include keyword. The difference is that this keyword allows users to include shader source from memory instead of a separate source file. This is done by assigning a name to the included source code in the #GorgonInclude keyword, and adding the GorgonShaderInclude containing the source to the Includes property on this class. When the include is loaded from a file, then it will automatically be added to the Includes property.

The parameters for the #GorgonIncludekeyword are:

• NameThe path name of the included source. This must be unique, and assigned to the Includes property.
• (Optional) PathThe path to the shader source file to include. This may be omitted if the include is assigned from memory in the Includes property.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the sourceCode, entryPoint or the graphics parameter is null.
ArgumentEmptyException	Thrown when the sourceCode, entryPoint parameter is empty.
GorgonException	Thrown when the type specified by T is not a valid shader type. -or- Thrown when there was an error during compilation of the shader.

FromFile<T>(GorgonGraphics, string)

Function to load a shader from a file containing a Gorgon binary shader in chunked format.

Declaration

public static T FromFile<T>(GorgonGraphics graphics, string path) where T : GorgonShader

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface used to create the shader.
string	path	The path to the file containing the Gorgon binary shader data.

Returns

Type	Description
T	A new GorgonShader. The type of shader depends on the data that was written to the file and the T type parameter.

Type Parameters

Name	Description
T	The type of shader to return. Must inherit from GorgonShader.

Remarks

Use this to load precompiled shaders from a file. This has the advantage of not needing a lengthy recompile of the shader when initializing.

This makes use of the Gorgon GorgonChunkFile<T> format to allow flexible storage of data. The Gorgon shader format is broken into 2 chunks, both of which are available in the BinaryShaderMetaData, and BinaryShaderByteCode constants. The file header for the format is stored in the BinaryShaderFileHeader constant.

The file format is as follows:

• BinaryShaderFileHeaderThis describes the type of file, and the version.
• BinaryShaderMetaDataShader metadata, such as the ShaderType (int), debug flag (bool), and the entry point name (string) is stored here.
• BinaryShaderByteCodeThe compiled shader byte code is stored here and is loaded as a byte array.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the graphics, or the path parameter is null.
ArgumentEmptyException	Thrown when the path parameter is empty.
InvalidCastException	Thrown if the application tries to load a specific shader type as T, but it is stored as another type.

See Also

GorgonChunkFile<T>

GorgonChunkFileReader

GorgonChunkFileWriter

FromStream<T>(GorgonGraphics, Stream, int)

Function to load a shader from a Stream containing a Gorgon binary shader in chunked format.

Declaration

public static T FromStream<T>(GorgonGraphics graphics, Stream stream, int size) where T : GorgonShader

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface used to create the shader.
Stream	stream	The stream containing the binary shader data.
int	size	The size, in bytes, of the binary shader within the stream.

Returns

Type	Description
T	A new GorgonShader. The type of shader depends on the data that was written to the stream and the T type parameter.

Type Parameters

Name	Description
T	The type of shader to return. Must inherit from GorgonShader.

Remarks

Use this to load precompiled shaders from a stream. This has the advantage of not needing a lengthy recompile of the shader when initializing.

This makes use of the Gorgon GorgonChunkFile<T> format to allow flexible storage of data. The Gorgon shader format is broken into 2 chunks, both of which are available in the BinaryShaderMetaData, and BinaryShaderByteCode constants. The file header for the format is stored in the BinaryShaderFileHeader constant.

The file format is as follows:

• BinaryShaderFileHeaderThis describes the type of file, and the version.
• BinaryShaderMetaDataShader metadata, such as the ShaderType (int), debug flag (bool), and the entry point name (string) is stored here.
• BinaryShaderByteCodeThe compiled shader byte code is stored here and is loaded as a byte array.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the graphics, or the stream parameter is null.
IOException	Thrown if the stream is write only.
EndOfStreamException	Thrown if an attempt to read beyond the end of the stream is made.
ArgumentOutOfRangeException	Thrown when the size parameter is less than 1 byte.
InvalidCastException	Thrown if the application tries to load a specific shader type as T, but it is stored as another type.

See Also

GorgonChunkFile<T>

GorgonChunkFileReader

GorgonChunkFileWriter