UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Migration
Migrating to UNIGINE 2.0
C++ API Migration
Migrating from UNIGINE 2.0 to UNIGINE 2.1

UUSL Textures

The Unified UNIGINE shader language (UUSL) unifies the way of using textures in shaders. You need to define the texture slot in the material, initialize the texture in the shader's code and then use it.

Here is an example of using texture in the vertex shader's code:

UUSL
// Include the UUSL header file
#include <core/shaders/common/common.h>

// Initialize a texture from the first texture slot.
// It's better to use "define" command
// to avoid whole code correction if you
// change the texture slot in the material
#define TEX_HEIGHT 1
INIT_TEXTURE(TEX_HEIGHT)

/* Input and output structures */

MAIN_BEGIN(VERTEX_OUT,VERTEX_IN)

	/* some code */

	// Set the texture
	float4 height = TEXTURE_BIAS_ZERO(TEX_HEIGHT,texcoord.xy);

	/* some code */
MAIN_END
Warning
You should add a new line (press Enter) after closing the instruction.

Texture Initialization Functions

Notice

The implementation of the SAMPLER(NUM) function in Direct3D is the following:

Direct3D
SamplerState s_sampler_ ## NUM : register(s ## NUM);
SamplerComparisonState s_sampler_compare_ ## NUM : register(s ## NUM);

INIT_TEXTURE (NUM)

Initialize a sampler with the 2D texture.

Equivalents

OpenGL
uniform sampler2D s_texture_ ## NUM;
Direct3D
Texture2D s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_TEXTURE_CUBE (NUM)

Initialize a sampler with the cubemap texture.

Equivalents

OpenGL
uniform samplerCube s_texture_ ## NUM;
Direct3D
TextureCube s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_TEXTURE_3D (NUM)

Initialize a sampler with the texture3D.

Equivalents

OpenGL
uniform sampler3D s_texture_ ## NUM;
Direct3D
Texture3D s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_TEXTURE_ARRAY (NUM)

Initialize a sampler with the array of 2D textures.

Equivalents

OpenGL
uniform sampler2DArray s_texture_ ## NUM;
Direct3D
Texture2DArray s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_TEXTURE_SHADOW (NUM)

Initialize a sampler with the 2D shadow texture.

Equivalents

OpenGL
uniform sampler2DShadow s_texture_ ## NUM;
Direct3D
Texture2DArray s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_TEXTURE_ARRAY_SHADOW (NUM)

Initialize a sampler with the array of 2D shadow textures.

Equivalents

OpenGL
uniform sampler2DArrayShadow s_texture_ ## NUM;
Direct3D
Texture2DArray s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_TEXTURE_CUBE_SHADOW (NUM)

Initialize a sampler with the shadow cubemap textures.

Equivalents

OpenGL
uniform samplerCubeShadow s_texture_ ## NUM;
Direct3D
TextureCube s_texture_ ## NUM : register(t ## NUM); SAMPLER(NUM)

Arguments

  • NUM - A number of the texture slot.

INIT_RW_TEXTURE (NUM, SIZE)

Initialize a 2D RWTexture. Works only with enabled USE_ARB_SHADER_IMAGE_LOAD_STORE and USE_RW_TEXTURES for OpenGL and USE_RW_TEXTURES only for Direct3D
Notice
If USE_ARB_SHADER_IMAGE_LOAD_STORE and USE_RW_TEXTURES are disabled, the function doesn't initialize anything.

Equivalents

OpenGL
coherent uniform layout(SIZE) image2D s_rw_texture_ ## NUM;
Direct3D
RWTexture2D<uint> s_rw_texture_ ## NUM : register(u ## NUM);

Arguments

  • NUM - A number of the texture slot.
  • SIZE - Texture size.

Texture Functions

TEXTURE (NUM, COORD)

Samples a texture.

Equivalents

OpenGL
texture(s_texture_ ## NUM,COORD)
Direct3D
s_texture_ ## NUM.Sample(s_sampler_ ## NUM ,COORD)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.

TEXTURE_BIAS (NUM, COORD, BIAS)

Samples a texture using a mipmap-level offset (performs a texture lookup with explicit level-of-detail).

Equivalents

OpenGL
textureLod(s_texture_ ## NUM,COORD,BIAS)
Direct3D
s_texture_ ## NUM.SampleLevel(s_sampler_ ## NUM,COORD,BIAS)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • BIAS - Mipmap level.

TEXTURE_OFFSET_BIAS (NUM, COORD, OFFSET, BIAS)

Samples a texture using a mipmap-level offset.

Equivalents

OpenGL
textureOffset(s_texture_ ## NUM,COORD,OFFSET,BIAS)
Direct3D
s_texture_ ## NUM.SampleLevel(s_sampler_ ## NUM,COORD,BIAS,OFFSET)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • OFFSET - Offset.
  • BIAS - Mipmap level.

TEXTURE_OFFSET (NUM, COORD, OFFSET)

Samples a texture using a offset on mipmap level 0 only (performs a texture lookup with offset).

Equivalents

OpenGL
textureOffset(s_texture_ ## NUM,COORD,OFFSET,0)
Direct3D
s_texture_ ## NUM.SampleLevel(s_sampler_ ## NUM,COORD,0,OFFSET)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • OFFSET - Offset.

TEXTURE_GRAD (NUM, COORD, DDX, DDY)

Samples a texture using a gradient to influence the way the sample location is calculated.

Equivalents

OpenGL
textureGrad(s_texture_ ## NUM,COORD,DDX,DDY)
Direct3D
s_texture_ ## NUM.SampleGrad(s_sampler_ ## NUM,COORD,DDX,DDY)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • DDX - The rate of change of the surface geometry in the x direction.
  • DDY - The rate of change of the surface geometry in the y direction.

TEXTURE_LOAD_LOD (NUM, COORD, LOD)

Reads texel data without any filtering or sampling.

Equivalents

OpenGL
texelFetch(s_texture_ ## NUM,COORD,LOD)
Direct3D
s_texture_ ## NUM.Load(uint3(COORD,LOD))

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • LOD - Level-of-detail within the texture from which the texel will be fetched.

TEXTURE_LOAD (NUM, COORD)

Reads texel data without any filtering or sampling with zero offset.

Equivalents

OpenGL
texelFetch(s_texture_ ## NUM,COORD,0)
Direct3D
s_texture_ ## NUM.Load(uint3(COORD,0))

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.

TEXTURE_SHADOW (NUM, COORD)

Samples a shadow texture.

Equivalents

OpenGL
texture(s_texture_ ## NUM,COORD)
Direct3D
s_texture_ ## NUM.SampleCmpLevelZero(s_sampler_compare_ ## NUM,COORD.xy,COORD.z)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.

TEXTURE_SHADOW_PROJ (NUM, COORD)

Samples a shadow texture with projection.

Equivalents

OpenGL
textureProj(s_texture_ ## NUM,COORD)
Direct3D
s_texture_ ## NUM.SampleCmpLevelZero(s_sampler_compare_ ## NUM,COORD.xy,COORD.z)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.

TEXTURE_CUBE_SHADOW (NUM, COORD)

Samples a cubemap shadow texture.

Equivalents

OpenGL
texture(s_texture_ ## NUM,COORD)
Direct3D
s_texture_ ## NUM.SampleCmpLevelZero(s_sampler_compare_ ## NUM,COORD.xyz,COORD.w)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.

TEXTURE_2D_CUBIC (NUM, COORD, TEXSIZE)

Samples a texture with bicubic interpolation.

Equivalents

OpenGL
texture2DCubic(s_texture_ ## NUM,COORD,TEXSIZE)
Direct3D
texture2DCubic(s_texture_ ## NUM,s_sampler_ ## NUM,COORD,TEXSIZE)
Notice
texture2DCubic is the internal function that performs bicubic interpolation.

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • TEXSIZE - Texture size.

TEXTURE_BIAS_ZERO (NUM, COORDS)

Samples a texture using a mipmap-level offset on mipmap level 0 only.

Equivalents

OpenGL
textureLod(s_texture_ ## NUM,COORDS,0.0f)
Direct3D
s_texture_ ## NUM.SampleLevel(s_sampler_ ## NUM,COORDS,0.0f)

Arguments

  • NUM - A number of the texture slot.
  • COORDS - UV coordinates.

TEXTURE_RW_LOAD (NUM, COORD)

Loads RW texture. Works only with enabled USE_ARB_SHADER_IMAGE_LOAD_STORE and USE_RW_TEXTURES for OpenGL and USE_RW_TEXTURES only for Direct3D
Notice
If USE_ARB_SHADER_IMAGE_LOAD_STORE and USE_RW_TEXTURES are disabled, the function initializes the float4(0.0f,0.0f,0.0f,0.0f) empty vector.

Equivalents

OpenGL
imageLoad(s_rw_texture_ ## NUM,COORD)
Direct3D
unpack_uint32_to_rgba8(s_rw_texture_ ## NUM[uint2(COORD)])

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.

TEXTURE_RW_STORE (NUM, COORD, VALUE)

Stores RW texture. Works only with enabled USE_ARB_SHADER_IMAGE_LOAD_STORE and USE_RW_TEXTURES for OpenGL and USE_RW_TEXTURES only for Direct3D
Notice
If USE_ARB_SHADER_IMAGE_LOAD_STORE and USE_RW_TEXTURES are disabled, the function doesn't initialize anything.

Equivalents

OpenGL
imageStore(s_rw_texture_ ## NUM,COORD,VALUE)
Direct3D
s_rw_texture_ ## NUM[uint2(COORD)] = pack_rgba8_to_uint32(VALUE)

Arguments

  • NUM - A number of the texture slot.
  • COORD - UV coordinates.
  • VALUE - A value to store.

Passing Textures to Functions

UUSL allows you to pass textures to functions as arguments.

Here is a usage example:

UUSL
float4 func_name(float4 color,float2 uv,TEXTURE_IN_2(texture_0,texture_1)) {
	return TEXTURE(texture_0,uv) * TEXTURE_BIAS(texture_1,uv,5.0f) * color;
}

float4 new_color = func_name(color,uv,TEXTURE_OUT_2(TEX_COLOR_0,TEX_COLOR_1));

TEXTURE_OUT (NUM)

Allows to pass a texture to function.

Equivalents

OpenGL
s_texture_ ## NUM
Direct3D
s_texture_ ## NUM,s_sampler_ ## NUM

Arguments

  • NUM - A number of the texture slot.

TEXTURE_OUT_2 (NUM0, NUM1)

Allows to pass two textures to a function.

Equivalents

OpenGL
TEXTURE_OUT(NUM_0),TEXTURE_OUT(NUM_1)
Direct3D
TEXTURE_OUT(NUM_0),TEXTURE_OUT(NUM_1)

Arguments

  • NUM0 - A number of the texture slot (for the first texture).
  • NUM1 - A number of the texture slot (for the second texture).

TEXTURE_OUT_3 (NUM0, NUM1, NUM2)

Allows to pass three textures to a function.

Equivalents

OpenGL
TEXTURE_OUT_2(NUM_0,NUM_1),TEXTURE_OUT(NUM_2)
Direct3D
TEXTURE_OUT_2(NUM_0,NUM_1),TEXTURE_OUT(NUM_2)

Arguments

  • NUM0 - A number of the texture slot (for the first texture).
  • NUM1 - A number of the texture slot (for the second texture).
  • NUM2 - A number of the texture slot (for the third texture).

TEXTURE_OUT_4 (NUM0, NUM1, NUM2, NUM3)

Allows to pass four textures to a function.

Equivalents

OpenGL
TEXTURE_OUT_3(NUM_0,NUM_1,NUM_2),TEXTURE_OUT(NUM_3)
Direct3D
TEXTURE_OUT_3(NUM_0,NUM_1,NUM_2),TEXTURE_OUT(NUM_3)

Arguments

  • NUM0 - A number of the texture slot (for the first texture).
  • NUM1 - A number of the texture slot (for the second texture).
  • NUM2 - A number of the texture slot (for the third texture).
  • NUM3 - A number of the texture slot (for the fourth texture).

TEXTURE_IN (NAME)

Specifies the 2D texture for passing to function.

Equivalents

OpenGL
sampler2D s_texture_ ## NAME
Direct3D
Texture2D s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.

TEXTURE_IN_2 (NAME0, NAME1)

Specifies two 2D textures for passing to function.

Equivalents

OpenGL
TEXTURE_IN(NAME_0),TEXTURE_IN(NAME_1)
Direct3D
TEXTURE_IN(NAME_0),TEXTURE_IN(NAME_1)

Arguments

  • NAME0 - A name of the first texture.
  • NAME1 - A name of the second texture.

TEXTURE_IN_3 (NAME0, NAME1, NAME2)

Specifies three 2D textures for passing to function.

Equivalents

OpenGL
TEXTURE_IN_2(NAME_0,NAME_1),TEXTURE_IN(NAME_2)
Direct3D
TEXTURE_IN_2(NAME_0,NAME_1),TEXTURE_IN(NAME_2)

Arguments

  • NAME0 - A name of the first texture.
  • NAME1 - A name of the second texture.
  • NAME2 - A name of the third texture.

TEXTURE_IN_4 (NAME0, NAME1, NAME2, NAME3)

Specifies four 2D textures for passing to function.

Equivalents

OpenGL
TEXTURE_IN_3(NAME_0,NAME_1,NAME_2),TEXTURE_IN(NAME_3)
Direct3D
TEXTURE_IN_3(NAME_0,NAME_1,NAME_2),TEXTURE_IN(NAME_3)

Arguments

  • NAME0 - A name of the first texture.
  • NAME1 - A name of the second texture.
  • NAME2 - A name of the third texture.
  • NAME3 - A name of the fourth texture.

TEXTURE_IN_CUBE (NAME)

Specifies the cube texture for passing to function.

Equivalents

OpenGL
samplerCube s_texture_ ## NAME
Direct3D
TextureCube s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.

TEXTURE_IN_3D (NAME)

Specifies the 3D texture for passing to function.

Equivalents

OpenGL
sampler3D s_texture_ ## NAME
Direct3D
Texture3D s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.

TEXTURE_IN_ARRAY (NAME)

Specifies the texture array for passing to function.

Equivalents

OpenGL
sampler2DArray s_texture_ ## NAME
Direct3D
Texture2DArray s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.

TEXTURE_IN_SHADOW (NAME)

Specifies the texture shadow for passing to function.

Equivalents

OpenGL
sampler2DShadow s_texture_ ## NAME
Direct3D
Texture2D s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.

TEXTURE_IN_ARRAY_SHADOW (NAME)

Specifies the texture shadow array for passing to function.

Equivalents

OpenGL
sampler2DArrayShadow s_texture_ ## NAME
Direct3D
Texture2DArray s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.

TEXTURE_IN_CUBE_SHADOW (NAME)

Specifies the texture shadow cube for passing to function.

Equivalents

OpenGL
samplerCubeShadow s_texture_ ## NAME
Direct3D
TextureCube s_texture_ ## NAME,SamplerState s_sampler_ ## NAME

Arguments

  • NAME - A name of the texture.
Last update: 2017-07-03