HC_Define_Shader_Texture

Key HC_Define_Shader_Texture(char const *name, int width, int height, int depth, int array_size, int mipmap_levels, char const *format, char const *options, void const **data)
Key HC_Define_Shader_Texture(char const name, int width, int height, int depth, int array_size, int mipmap_levels, char const format, char const options, void const data)

Defines a texture to be used by a modern custom shader.

This function defines a texture that can be used in conjunction with a shader sampler in a custom shader to for sampling operations. The same texture can be used with multiple shaders, and should be referred to by the name specified to this function, prefixed with “user” and suffixed with “Texture”. For example, if you give the texture the name “Example”, in the custom shader source you should refer to it as “userExampleTexture”.

Textures are immutable. Their state can only be set at definition time, and they can be destroyed by using HC_Delete_By_Key.

width = X, height = Y

X and Y need to be within the limits of the graphics API used for rendering and the GPU hardware. Typically this will mean a limit of 16384 pixels for width or height, though it can vary when using OpenGL.

depth = 1, array_size = 1

depth and array_size must always be 1 presently. It is not currently supported to have 3D textures or texture arrays. The inclusion of these arguments in the signature is meant for future-proofing.

mipmap_levels = 0 - N

0 means generate all possible mipmaps. 1 means no mipmaps will be generated. N > 1 means generate N mipmap levels.

format = [rgba8unorm | rgba8uint | rgba16uint | rgba32uint | rgba32float | r8unorm | r8uint | r16uint | r32uint | r32float | rg8unorm | rg8uint | rg16uint | rg32uint | rg32float]

rgba8unorm indicates the data is an 8-bit unsigned integer for each R, G, B, and A channel, and will be returned as a normalized float in the range [0, 1] when sampled.

rgba8uint indicates the data is an 8-bit unsigned integer for each R, G, B, and A channel, and will be returned as an unsigned integer in the range [0, 2^8-1] when sampled.

rgba16uint indicates the data is a 16-bit unsigned integer for each R, G, B, and A channel, and will be returned as an unsigned integer in the range [0, 2^16-1] when sampled.

rgba32uint indicates the data is a 32-bit unsigned integer for each R, G, B, and A channel, and will be returned as an unsigned integer in the range [0, 2^32-1] when sampled.

rgba32float indicates the data is a 32-bit float for each R, G, B, and A channel, and will be returned as a 32-bit float when sampled.

r8unorm indicates the data is an 8-bit unsigned integer for the R channel, and will be returned as a normalized float in the range [0, 1] when sampled.

r8uint indicates the data is an 8-bit unsigned integer for the R channel, and will be returned as an unsigned integer in the range [0, 2^8-1] when sampled.

r16uint indicates the data is a 16-bit unsigned integer for the R channel, and will be returned as an unsigned integer in the range [0, 2^16-1] when sampled.

r32uint indicates the data is a 32-bit unsigned integer for the R channel, and will be returned as an unsigned integer in the range [0, 2^32-1] when sampled.

r32float indicates the data is a 32-bit float for the R channel, and will be returned as a 32-bit float when sampled.

rg8unorm indicates the data is an 8-bit unsigned integer for each R and G channel, and will be returned as a normalized float in the range [0, 1] when sampled.

rg8uint indicates the data is an 8-bit unsigned integer for each R and G channel, and will be returned as an unsigned integer in the range [0, 2^8-1] when sampled.

rg16uint indicates the data is a 16-bit unsigned integer for each R and G channel, and will be returned as an unsigned integer in the range [0, 2^16-1] when sampled.

rg32uint indicates the data is a 32-bit unsigned integer for each R and G channel, and will be returned as an unsigned integer in the range [0, 2^32-1] when sampled.

rg32float indicates the data is a 32-bit float for each R and G channel, and will be returned as a 32-bit float when sampled.

options = nullptr

Presently this argument is not referenced when definining a texture. The inclusion of this argument in the signature is meant for future-proofing.

data = data for texture initialization

In general this should be a two-dimensional array with array_size entries, each of which contains arrays with width * height * depth * format_byte_size bytes of data.

Since presently depth and array_size must always be 1, this means the data should be a two-dimensional array with one entry that contains an array with width * height * format_byte_size bytes of data.

HC_Define_Shader, HC_Delete_By_Key, HC_Set_Shader_Textures

Parameters

name: The name to use when referring to the texture in the custom shader source.

width: The width of the texture in pixels.

height: The height of the texture in pixels.

depth: The depth of the texture in pixels. This argument is for future-proofing - presently this must always be 1.

array_size: The number of textures in the texture array. This argument is for future-proofing - presently this must always be 1.

mipmap_levels: The number of mipmap levels.

format: The format of the texture.

options: A quoted string or a string variable containing a list of the desired option settings. This argument is for future-proofing - presently this is not used.

data: The data to use to initialize the texture.

Returns

The key to the defined texture.