HC_Define_Shader_Sampler
-
Key
HC_Define_Shader_Sampler(char const *name, char const *options) - Key HC_Define_Shader_Sampler(char const name, char const options)
Defines a texture sampler to be used by a modern custom shader.
This function defines a sampler that can be used in conjunction with a shader texture in a custom shader to control the settings used when sampling the texture. The same sampler can be used with multiple textures and shaders, and should be referred to by the name specified to this function, prefixed with “user” and suffixed with “Sampler”. For example, if you give the sampler the name “Example”, in the custom shader source you should refer to it as “userExampleSampler”.
Samplers are immutable, and their state can only be set at definition time. All the options below have default values, and you only need to provide options if you want to override the default value for a particular option. Samplers can be destroyed by using HC_Delete_By_Key.
Limitation: When writing your shader source, the source text in
user_customFieldmust always be lowercase, or it won’t work.The options parameter to Define_Shader_Sampler is a comma-separated list of settings which can include the following:
min filter = [“nearest” | “linear”]
Specifies the type of filtering to use when textures need to be minified, i.e., when adjacent screen pixels span multiple texels. nearest will pick the closest texel, linear will linearly blend between the four closest texels. The default is linear.
mag filter = [“nearest” | “linear”]
Specifies the type of filtering to use when textures need to be magnified, i.e., when adjacent screen pixels span less than a single texel. nearest will pick the closest texel, linear will linearly blend between the four closest texels. The default is linear.
mip filter = [“nearest” | “linear”]
Specifies the type of filtering to use when mipmaps are present for a texture. nearest will pick the closest mipmap level and do the sampling there, linear will find the two closest mipmap levels, sample each and linearly interpolate between the two. The default is linear.
max anisotropy = [“1 - 16”]
Specifies the maximum number of anisotropy samples to use. 1 disables anisotropic filtering, larger values enable anisotropic filtering up to a maximum number of samples of 16. The default is 1.
min lod = [“0 - FLT_MAX”]
Specifies the lowest mipmap level to sample. 0 is the mip level of the original image, larger values correspond to smaller textures in the mip chain. The default is 0, and the value should be less than or equal to max lod.
max lod = [“0 - FLT_MAX”]
Specifies the maximum mipmap level to sample. 0 is the mip level of the original image, larger values correspond to smaller textures in the mip chain. The default is FLT_MAX, i.e., no upper limit, and the value should be greater than or equal to min lod.
width address = [“repeat” | “mirror repeat” | “clamp to edge” | “clamp to border” | “mirror clamp to edge”]
Specifies the behavior of the sampler when the texture coordinates used for sampling are outside the range [0, 1] in the horizontal texture coordinate direction.
repeat will repeat the texture horizontally indefinitely.
mirror repeat will mirror the texture horizontally indefinitely.
clamp to edge will clamp the horizontal coordinate to the range [0, 1].
clamp to border will clamp the horizontal coordinate to the range [0, 1] and return the specified border color for values of 0 and 1.
mirror clamp to edge will mirror the texture once horizontally and then clamp the horizontal coordinate to the range [0, 1].
Default is repeat.
height address = [“repeat” | “mirror repeat” | “clamp to edge” | “clamp to border” | “mirror clamp to edge”]
Specifies the behavior of the sampler when the texture coordinates used for sampling are outside the range [0, 1] in the vertical texture coordinate direction.
repeat will repeat the texture vertically indefinitely.
mirror repeat will mirror the texture vertically indefinitely.
clamp to edge will clamp the vertical coordinate to the range [0, 1].
clamp to border will clamp the vertical coordinate to the range [0, 1] and return the specified border color for values of 0 and 1.
mirror clamp to edge will mirror the texture once vertically and then clamp the vertical coordinate to the range [0, 1].
Default is repeat.
border color = [“transparent black” | “opaque black” | “opaque white”]
Specifies the border color to use when clamp to border is set for width address or height address.
transparent black will use the RGBA value (0, 0, 0, 0).
opaque black will use the RGBA value (0, 0, 0, 1).
opaque white will use the RGBA value (1, 1, 1, 1).
Default is transparent black. Note that even though transparent black can be returned, it does not mean that the resulting object will be treated as transparent - merely that the sampler will return values with an alpha of 0 if it ends up needing to return the border color.
HC_Define_Shader, HC_Define_Shader_Texture, HC_Delete_By_Key, HC_Set_Shader_TexturesParameters
name: The name to use when referring to the sampler in the custom shader source.
options: A quoted string or a string variable containing a list of the desired option settings.
Returns
The key to the defined sampler.