SoftArt Shader Interfaces Enums Enum cbuffer_type shader_variable_class shader_variable_type system_value_name register_component_type shader_input_type shader_input_flags resource_return_type srv_dimension cbuffer_type Indicates a constant buffer's type. enum cbuffer_type{ ct_cbuffer, ct_tbuffer, ct_resource_bind_info }; Constants ct_cbuffer A buffer containing scalar constants. ct_tbuffer A buffer containing texture data. ct_resource_bind_info A buffer containing binding information. Description Indicates a constant buffer's type. These flags identify the shader-variable class. These flags identify the shader-variable type. These flags identify shader parameters that use system-value semantics. The register component types, usually used in shader_param_desc. These flags identify a shader-resource type. These flags identify shader-input options. Indicates return value type. These flags identify the type of resource that will be viewed. shader_variable_class These flags identify the shader-variable class. enum shader_variable_class{ svc_scalar, svc_vector, svc_matrix_rows, svc_matrix_columns, svc_object, svc_struct }; Constants svc_scalar The shader variable is a scalar. svc_vector The shader variable is a vector. svc_matrix_rows The shader variable is a row-major matrix. svc_matrix_columns The shader variable is a column-major matrix. svc_object The shader variable is an object. svc_struct The shader variable is a structure. Remarks These flags describe the class of a shader variable. This is not a programming class; the class identifies whether the variable class such as scalar, vector, object, etc. The shader-variable class is used in a shader-input-signature description (see shader_input_bind_desc). shader_variable_type These flags identify the shader-variable type. enum shader_variable_type{ svt_void, svt_bool, svt_int, svt_float, svt_string, svt_texture, svt_texture_1d, svt_texture_2d, svt_texture_3d, svt_texture_cube, svt_sampler, svt_vertex_shader, svt_pixel_shader, svt_blend_shader, svt_uint, svt_uint8, svt_geometry_shader, svt_rasterizer, svt_depth_stencil, svt_blend, svt_buffer, svt_cbuffer, svt_tbuffer, svt_texture_1d_array, svt_texture_2d_array, svt_render_target_view, svt_depth_stencil_view, svt_texture_2d_ms, svt_texture_2d_ms_array, svt_texture_cube_array, svt_double, }; Constants svt_void The variable is a void pointer. svt_bool The variable is a boolean. svt_int The variable is a integer. svt_float The variable is a floating-point number. svt_string The variable is a string. svt_texture The variable is a texture. svt_texture_1d The variable is a 1D texture. svt_texture_2d The variable is a 2D texture. svt_texture_3d The variable is a 3D texture. svt_texture_cube The variable is a texture cube. svt_sampler The variable is a sampler. svt_vertex_shader The variable is a vertex shader. svt_pixel_shader The variable is a pixel shader. svt_blend_shader The variable is a blend shader. svt_uint The variable is an unsigned integer. svt_uint8 The variable is an 8-bit unsigned integer. svt_geometry_shader The variable is a geometry shader. svt_rasterizer The variable is a rasterizer-state object. svt_depth_stencil The variable is a depth-stencil-state object. svt_blend The variable is a blend-state object. svt_buffer The variable is a buffer. svt_cbuffer The variable is a constant buffer. svt_tbuffer The variable is a texture buffer. svt_texture_1d_array The variable is a 1D-texture array. svt_texture_2d_array The variable is a 2D-texture array. svt_render_target_view The variable is a render-target view. svt_depth_stencil_view The variable is a depth-stencil view. svt_texture_2d_ms The variable is a 2D-multisampled texture. svt_texture_2d_ms_array The variable is a 2D-multisampled-texture array. svt_texture_cube_array The variable is a texture-cube array. svt_double The variable is a double. Remarks These flags are used by a shader-type description (see shader_type_desc). system_value_name These flags identify shader parameters that use system-value semantics. enum system_value_name { svn_undefined, svn_position, svn_clip_distance, svn_cull_distance, svn_vertex_id, svn_primitive_id, svn_instance_id, svn_is_front_face, svn_sample_index, svn_target, svn_depth, svn_coverage }; Constants svn_undefined This parameter does not use a predefined system-value semantic. svn_position This parameter contains position data. svn_clip_distance This parameter contains clip-distance data. svn_cull_distance This parameter contains cull distance data. svn_vertex_id This parameter contains a vertex ID. svn_primitive_id This parameter contains a primitive ID. svn_instance_id This parameter contains a instance ID. svn_is_front_face This parameter contains data that identifies whether or not the primitive faces the camera. svn_sample_index This parameter a sampler-array index. svn_target This parameter contains render-target data. svn_depth This parameter contains depth data. svn_coverage This parameter contains alpha-coverage data. Remarks These flags identify shader parameters that have predefined system-value semantics. These flags are used in a shader-signature description (see shader_param_desc). register_component_type The register component types, usually used in shader_param_desc. enum register_component_type { rct_unknown = 0, rct_uint32 = 1, rct_sint32 = 2, rct_float32 = 3, }; Constants rct_unknown Reserved. rct_uint32 32-bit unsigned integer. rct_sint32 32-bit signed integer. rct_float32 32-bit floating-point number. shader_input_type These flags identify a shader-resource type. enum shader_input_type { sit_cbuffer, sit_tbuffer, sit_texture, sit_sampler, }; Constants sit_cbuffer The shader resource is a constant buffer. sit_tbuffer The shader resource is a texture buffer. sit_texture The shader resource is a texture. sit_sampler The shader resource is a sampler. Remarks These flags describe a shader resource that is used as an input in a shader-input-signature description (see shader_input_bind_desc). shader_input_flags These flags identify shader-input options. enum shader_input_flags { sif_user_packed = 1 << 0, sif_comparison_sampler = 1 << 1, sif_texture_component_0 = 1 << 2, sif_texture_component_1 = 1 << 3, sif_texture_components = sif_texture_component_0 | sif_texture_component_1 }; Constants sif_user_packed Assign a shader input to a register based on the register assignment in the SASL code (instead of letting the compiler choose the register). sif_comparison_sampler Use a comparison sampler, which uses the SampleCmp and SampleCmpLevelZero sampling functions. sif_texture_component_0 A 2-bit value for encoding texture components. sif_texture_component_1 A 2-bit value for encoding texture components. sif_texture_components A 2-bit value for encoding texture components. Remarks These flags are used in a shader-input-signature description (see shader_input_bind_desc). resource_return_type Indicates return value type. enum resource_return_type { rt_unorm = 1, rt_snorm = 2, rt_sint = 3, rt_uint = 4, rt_float = 5, rt_mixed = 6, rt_double = 7, rt_continued = 8, }; Constants rt_unorm Return type is UNORM. rt_snorm Return type is SNORM. rt_sint Return type is SINT. rt_uint Return type is UINT. rt_float Return type is FLOAT. rt_mixed Return type is unknown. rt_double Return type is DOUBLE. rt_continued Return type is a multiple-dword type, such as a double or uint64, and the component is continued from the previous component that was declared. The first component represents the lower bits. srv_dimension These flags identify the type of resource that will be viewed. enum srv_dimension { srv_dimension_unknown = 0, srv_dimension_buffer = 1, srv_dimension_texture_1d = 2, srv_dimension_texture_1d_array = 3, srv_dimension_texture_2d = 4, srv_dimension_texture_2d_array = 5, srv_dimension_texture_2d_ms = 6, srv_dimension_texture_2d_ms_array = 7, srv_dimension_texture_3d = 8, srv_dimension_texture_cube = 9, }; Constants srv_dimension_unknown The type is unknown. srv_dimension_buffer The resource is a buffer. srv_dimension_texture_1d The resource is a 1D texture. srv_dimension_texture_1d_array The resource is an array of 1D textures. srv_dimension_texture_2d The resource is a 2D texture. srv_dimension_texture_2d_array The resource is an array of 2D textures. srv_dimension_texture_2d_ms The resource is a multisampling 2D texture. srv_dimension_texture_2d_ms_array The resource is an array of multisampling 2D textures. srv_dimension_texture_3d The resource is a 3D texture. srv_dimension_texture_cube The resource is a cube texture. Remarks These flags are used by a shader-resource-view description (see shader_resource_view_desc), or a shader-input-signature description (see shader_input_bind_desc). Structs Struct shader_buffer_desc shader_variable_desc shader_type_desc shader_desc shader_param_desc shader_input_bind_desc shader_buffer_desc Describes a shader constant-buffer. struct shader_buffer_desc { std::string name; cbuffer_type type; uint32_t variables; uint32_t size; uint32_t flags; }; Members name The name of the buffer. type The intended use of the constant data. variables The number of unique variables. size Buffer size (in bytes). flags Shader buffer properties. Description Describes a shader constant-buffer. Describes a shader variable. Describes a shader-variable type. Describes a shader. Describes a shader signature. Describes how a shader resource is bound to a shader input. Remarks Constants are supplied to shaders in a shader-constant buffer. Get the description of a shaderconstant-buffer by calling shader_reflection_constant_buffer::get_desc. shader_variable_desc Describes a shader variable. struct shader_variable_desc { std::string name; uint32_t start_offset; uint32_t size; uint32_t flags; void* default_value; }; Members name The variable name. start_offset Offset from the start of the parent structure, to the beginning of the variable. size Size of the variable (in bytes). flags Flags, which identify shader-variable properties default_value The default value for initializing the variable. Remarks Get a shader-variable description using reflection, by calling shader_reflection_variable::get_desc. shader_type_desc Describes a shader-variable type. struct shader_type_desc { shader_variable_class class; shader_variable_type type; uint32_t rows; uint32_t columns; uint32_t elements; uint32_t members; uint32_t offset; }; Members class Identifies the variable class as one of scalar, vector, matrix or object. See shader_variable_class. type The variable type. See shader_variable_type. rows Number of rows in a matrix. Otherwise a numeric type returns 1, any other type returns 0. columns Number of columns in a matrix. Otherwise a numeric type returns 1, any other type returns 0. elements Number of elements in an array; otherwise 0. members Number of members in the structure; otherwise 0. offset Offset, in bytes, between the start of the parent structure and this variable. Remarks Get a shader-variable-type description by calling shader_reflection_type::get_desc. shader_desc Describes a shader. struct shader_desc { uint32_t version; uint32_t flags; uint32_t constant_buffers; uint32_t bound_resources; uint32_t input_params; uint32_t output_params; }; Members version Shader version. flags Shader compilation/parse flags. constant_buffers The number of shader-constant buffers. bound_resources The number of resource (textures and buffers) bound to a shader. input_params The number of parameters in the input signature. output_params The number of parameters in the output signature. Remarks A shader is written in SASL and compiled into an intermediate language by the SASL compiler. The shader description returns information about the compiled shader. Get a shader description by calling shader::get_desc. shader_param_desc Describes a shader signature. struct shader_param_desc { std::string semantic_name; uint32_t semantic_index; uint32_t register; system_value_name system_value_type; register_component_type component_type; uint8_t mask; uint8_t read_write_mask; uint32_t stream; }; Members semantic_name A per-parameter string that identifies how the data will be used. semantic_index Semantic index that modifies the semantic. Used to differentiate different parameters that use the same semantic. register The register that will contain this variable's data. system_value_type A predefined string that determines the functionality of certain pipeline stages. See system_value_name. component_type The per-component-data type that is stored in a register. See register_component_type. Each register can store up to four-components of data. Remarks A shader can take n inputs and can produce m outputs. The order of the input (or output) parameters, their associated types, and any attached semantics make up the shader signature. Each shader has an input and an output signature. When compiling a shader or an effect, some API calls validate shader signatures That is, they compare the output signature of one shader (like a vertex shader) with the input signature of another shader (like a pixel shader). This ensures that a shader outputs data that is compatible with a downstream shader that is consuming that data. Compatible means that a shader signature is a exact-match subset of the preceeding shader stage. Exact match means parameter types and semantics must exactly match. Subset means that a parameter that is not required by a downstream stage, does not need to include that parameter in its shader signature. Get a shader-signature from a shader or an effect by calling APIs such as shader::get_input_param_desc. shader_input_bind_desc Describes how a shader resource is bound to a shader input. struct shader_input_bind_desc { std::string name; shader_input_type type; uint32_t bind_point; uint32_t bind_count; uint32_t flags; resource_return_type return_type; srv_dimension dimension; uint32_t num_samples; }; Members name Name of the shader resource. type Identifies the type of data in the resource. See shader_input_type. bind_point Starting bind point. bind_count Number of contiguous bind points for arrays. flags Shader input-parameter options. See shader_input_flags return_type If the input is a texture, the return type. See resource_return_type. dimension Identifies the amount of data in the resource. See srv_dimension. num_samples The number of samples for a multisampled texture; otherwise 0. Remarks Get a shader-input-signature description by calling shader::get_resource_binding_desc. Classes shader_reflection_constant_buffer class This shader-reflection interface provides access to a constant buffer. This interface does not inherit from anything, but does declare the following methods: Method Description shader_reflection_constant_buffer::get_desc Get a constant-buffer description. shader_reflection_constant_buffer::get_variable Get a shader-reflection variable To create a constant-buffer interface, call shader::get_constant_buffer. shader_reflection_constant_buffer::get_desc Get a constant-buffer description. const shader_buffer_desc& get_desc(); Parameters None. Return Values A constant reference to a shader_buffer_desc, which represents a shader-buffer description. shader_reflection_constant_buffer::get_variable Get a shader-reflection variable by index or name. shader_reflection_variable* get_variable(uint32_t index); shader_reflection_variable* get_variable(const std::string& name); Parameters index [in] Zero-based index. name [in] Variable name. Return Values A pointer to a shader-reflection variable interface (see shader_reflection_variable). shader_reflection_variable class This shader-reflection interface provides access to a variable. This interface does not inherit from anything, but does declare the following methods: Method Description shader_reflection_variable::get_desc Get a shader-variable description. shader_reflection_ variable::get_type Get a shader-variable type. To get a shader-reflection-variable interface, call a method like shader::get_variable. shader_reflection_variable::get_desc Get a shader-variable description. const shader_variable_desc& get_desc(); Parameters None. Return Values A constant reference to a shader-variable description (see shader_variable_desc). shader_reflection_variable::get_type Get a shader-variable type. shader_reflection_type* get_type(); Parameters None. Return Values A pointer to a shader_reflection_type. shader_reflection_type class This shader-reflection interface provides access to variable type. This interface does not inherit from anything, but does declare the following methods: Method shader_reflection_type::get_base_class shader_reflection_type::get_desc shader_reflection_type::get_member_type shader_reflection_type::get_member_type_name shader_reflection_type::get_sub_type shader_reflection_type::operator== Description Gets a variable base class type. Gets a shader-type description. Gets a variable type by index. Gets a variable type. Gets the base class of a class. Indicates whether two Shader_reflection_type Interface pointers have the same underlying type. shader_reflection_type::is_of_type Indicates if a variable is of the specified type. The get a shader-reflection-type interface, call shader_reflection_variable::get_type. shader_reflection_type::get_base_class Gets an Shader_reflection_type object containing the variable base class type. shader_reflection_type* get_base_class(); Parameters None. Return Values A pointer to a shader_reflection_type object. shader_reflection_type::get_desc Get the description of a shader-reflection-variable type. const shader_type_desc& get_desc(); Parameters None. Return Values A constant reference to a shader-type description (see shader_type_desc). shader_reflection_type::get_member_type Get a shader-reflection-variable type by index or name. shader_reflection_type* get_member_type(uint32_t index); shader_reflection_type* get_member_type(const std::string& name); Parameters Index [in] Zero-based index. name [in] Member name. Return Values A pointer to a shader_reflection_type object. shader_reflection_type::get_member_type_name Get a shader-reflection-variable type. const std::string& get_member_type_name(uint32_t Index); Parameters index [in] Zero-based index. Return Values The variable type. shader_reflection_type::get_sub_type Gets the base class of a class. shader_reflection_type* get_sub_type(); Parameters None. Return Values Returns a pointer to a shader_reflection_type Interface containing the base class type. Returns NULL if the class does not have a base class. shader_reflection_type::operator== Indicates whether two shader_reflection_type Interface pointers have the same underlying type. friend bool operator==(const shader_reflection_type& lhs , const shader_reflection_type& rhs); Parameters lhs, rhs [in] A constant reference to a shader_reflection_type object. Return Values Returns true if the objects have the same underlying type; otherwise returns false. Remarks operator== indicates whether the sources of the shader_reflection_type objects have the same underlying type. For example, if two shader_reflection_type Interface pointers were retrieved from variables, operator== can be used to see if the variables have the same type. shader_reflection_type::is_of_type Indicates whether a variable is of the specified type. bool is_of_type(const shader_reflection_type& type); Parameters type [in] A constant reference to a shader_reflection_type Interface. Return Values Returns true if object being queried is equal to or inherits from the type in the type parameter; otherwise returns false. shader class Method shader::get_constant_buffer shader::get_desc Description Gets a constant buffer. Gets a shader description. shader::get_input_param_desc shader::get_output_param_desc shader::get_resource_binding_desc shader::get_variable Gets an input-parameter description for a shader. Gets an output-parameter description for a shader. Gets a description of the resources bound to a shader. Gets a variable. shader::get_constant_buffer Get a constant buffer by index or name. shader_reflection_constant_buffer* get_constant_buffer (uint32_t index); shader_reflection_constant_buffer* get_constant_buffer (const std::string& name); Parameters index [in] Zero-based index. name [in] The constant-buffer name. Return Values A pointer to a constant buffer (see shader_reflection_constant_buffer). Remarks A constant buffer supplies either scalar constants or texture constants to a shader. A shader can use one or more constant buffers. For best performance, separate constants into buffers based on the frequency they are updated. shader::get_desc Get a shader description. const shader_desc& get_desc() const; Return Values A constant reference to a shader description. See shader_desc. shader::get_input_param_desc Get an input-parameter description for a shader. const shader_param_desc& get_input_param_desc (uint32_t index) const; Parameters index [in] A zero-based parameter index. Return Values A constant reference to a shader input description. See shader_param_desc. Remarks An input-parameter description is also called a shader signature. The shader signature contains information about the input parameters such as the order or parameters, their data type, and a parameter semantic. shader::get_output_param_desc Get an output-parameter description for a shader. const shader_param_desc& get_output_param_desc (uint32_t index) const; Parameters index [in] A zero-based parameter index. Return Values A constant reference to a shader output description. See shader_param_desc. Remarks An output-parameter description is also called a shader signature. The shader signature contains information about the output parameters such as the order or parameters, their data type, and a parameter semantic. shader::get_resource_binding_desc Get a description of the resources bound to a shader. const shader_input_bind_desc& get_resource_binding_desc(uint32_t index); const shader_input_bind_desc& get_resource_binding_desc(const std::string& name); Parameters index [in] A zero-based resource index. name [in] The constant-buffer name. Return Values A constant reference to an input-binding description. See shader_input_bind_desc. Remarks A shader consists of executable code (the compiled SASL functions) and a set of resources that supply the shader with input data. This API gets a list of the resources that are bound as inputs to the shader. shader::get_variable Gets a variable by name. shader_reflection_variable* get_variable(const std::string& name); Parameters name [in] A string containing the variable name. Return Values A pointer to shader_reflection_variable object (see shader_reflection_variable). Compiler Interfaces Structs shader_macro Defines a shader macro. struct shader_macro { std::string name; std::string definition; }; Members name The macro name. definition The macro definition. Remarks You may use macros in your shaders. This enables the application to #define tokens at runtime, before the file is parsed. This structure defines a single macro. For example: shader_macro Shader_Macros[1] = { "zero", "0" }; The shader creation methods compile_shader take an array of macros as an input parameter. Classes shader_include A shader_include base class allows an application to create user-overridable methods for opening and closing files when loading an effect from memory. This interface does not inherit from anything, but does declare the following methods: Method shader_include::close shader_include::open Description A user-implemented method for closing a shader #include file. A user-implemented method for opening and reading the contents of a shader #include file. To use this class, create a class that inherits from shader_include, and implement custom behavior for the methods. shader_include::close A user-implemented method for closing a shader #include file. void close( std::istream& stream ); Parameters stream [in] A stream that contains the include directives. This is the input stream that was returned by the corresponding shader_include::open call. Remarks If shader_include::open was successful, shader_include::close is guaranteed to be called before the API using this interface returns. shader_include::open A user-implemented method for opening and reading the contents of a shader #include file. void open( const std::string& file_name, const void* parent_data, std::istream& stream ); Parameters file_name [in] Name of the #include file. parent_data [in] Pointer to the container that includes the #include file. stream [out] The returned stream that contains the include directives. This stream remains valid until shader_include::close is called. Functions compile_shader Compile a shader from a stream. shader* compile_shader( std::istream& stream, const shader_macro*defines, shader_include* include_handler, const std::string& func_name, uint32_t flags, std::string* error_msgs, ); Parameters stream [in] The stream that contains the shader code. defines [in] Optional. Pointer to an array of macro definitions (see shader_macro). The last structure in the array serves as a terminator and must have all members set to 0. If not used, set defines to NULL. include_handler [in] Optional. Pointer to a class for handling include files. Setting this to NULL will cause a compile error if a shader contains a #include. function_name [in] Name of the shader-entrypoint function where shader execution begins. flags [in] Shader compile flags. Reserved. error_msgs [out] A pointer to string which contains a listing of errors and warnings that occurred during compilation. Return Values A pointer to a shader object which contains the compiled shader, as well as any embedded debug and symbol-table information. Host Interfaces Method renderer::set_vertex_shader renderer::set_pixel_shader renderer::set_blend_shader renderer::get_vertex_shader renderer::get_pixel_shader renderer::get_blend_shader Description Set a vertex shader to the renderer. Set a pixel shader to the renderer. Set a blend shader to the renderer. Get the vertex shader currently set on the renderer. Get the pixel shader currently set on the renderer. Get the blend shader currently set on the renderer. renderer::set_vertex_shader Set a vertex shader to the renderer. void set_vertex_shader( shader*vs ); Parameters vs [in] Pointer to a vertex shader (see shader). Passing in NULL disables the shader for this pipeline stage. renderer::set_pixel_shader Set a pixel shader to the renderer. void set_pixel_shader( shader*ps ); Parameters ps [in] Pointer to a pixel shader (see shader). Passing in NULL disables the shader for this pipeline stage. renderer::set_blend_shader Set a blend shader to the renderer. void set_blend_shader( shader*bs ); Parameters bs [in] Pointer to a blend shader (see shader). Passing in NULL disables the shader for this pipeline stage. renderer::get_vertex_shader Get the vertex shader currently set on the renderer. shader* get_vertex_shader(); Parameters None. Return Values Address of a pointer to a vertex shader (see shader) to be returned by the method. renderer::get_pixel_shader Get the pixel shader currently set on the renderer. shader* get_pixel_shader(); Parameters None. Return Values Address of a pointer to a pixel shader (see shader) to be returned by the method. renderer::get_blend_shader Get the blend shader currently set on the renderer. shader* get_blend_shader(); Parameters None. Return Values Address of a pointer to a blend shader (see shader) to be returned by the method.