Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

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 fragment shader's code:

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

// Initialize a textures.
// You don't need to define texture slot
// by using define directive
INIT_TEXTURE(0,TEX_DEPTH)
INIT_TEXTURE(1,TEX_NORMAL)
INIT_TEXTURE(2,TEX_ALBEDO)
INIT_TEXTURE(3,TEX_SHADING)

/* Input and output structures */

MAIN_BEGIN(FRAGMENT_OUT,FRAGMENT_IN)

	/* some code */

	GBuffer gbuffer = GBufferDefault();
	
	loadGBufferAlbedo(gbuffer, TEXTURE_OUT(TEX_ALBEDO),uv);
	loadGBufferShading(gbuffer, TEXTURE_OUT(TEX_SHADING),uv);
	loadGBufferNormal(gbuffer, TEXTURE_OUT(TEX_NORMAL),uv);

	/* 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_ ## NAME : register(s ## NUM);
SamplerComparisonState s_sampler_compare_ ## NAME : register(s ## NUM);

INIT_TEXTURE(value NUM, value NAME)

Initialize a sampler with the 2D texture.

Equivalents

OpenGL
layout(binding=NUM) uniform sampler2D s_texture_ ## NAME;
Direct3D
Texture2D s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_TEXTURE_CUBE(value NUM, value NAME)

Initialize a sampler with the cubemap texture.

Equivalents

OpenGL
layout(binding=NUM) uniform samplerCube s_texture_ ## NAME;
Direct3D
TextureCube s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_TEXTURE_3D(value NUM, value NAME)

Initialize a sampler with the texture3D.

Equivalents

OpenGL
layout(binding=NUM) uniform sampler3D s_texture_ ## NAME;
Direct3D
Texture3D s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_TEXTURE_ARRAY(value NUM, value NAME)

Initialize a sampler with the array of 2D textures.

Equivalents

OpenGL
layout(binding=NUM) uniform sampler2DArray s_texture_ ## NAME;
Direct3D
Texture2DArray s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_TEXTURE_SHADOW(value NUM, value NAME)

Initialize a sampler with the 2D shadow texture.

Equivalents

OpenGL
layout(binding=NUM) uniform sampler2DShadow s_texture_ ## NAME;
Direct3D
Texture2D s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_TEXTURE_ARRAY_SHADOW(value NUM, value NAME)

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

Equivalents

OpenGL
layout(binding=NUM) uniform sampler2DArrayShadow s_texture_ ## NAME;
Direct3D
Texture2DArray s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_TEXTURE_CUBE_SHADOW(value NUM, value NAME)

Initialize a sampler with the shadow cubemap textures.

Equivalents

OpenGL
layout(binding=NUM) uniform samplerCubeShadow s_texture_ ## NAME;
Direct3D
TextureCube s_texture_ ## NAME : register(t ## NUM); SAMPLER(NUM,NAME)

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

INIT_RW_TEXTURE(value NUM, value NAME)

Initialize a 2D RWTexture. Works only with USE_RW_TEXTURES enabled.
Notice
If USE_RW_TEXTURES is not defined, the function doesn't initialize anything.

Equivalents

OpenGL
layout(binding=NUM) coherent uniform layout(rgba8) image2D s_rw_texture_ ## NAME;
Direct3D
RWTexture2D<uint> s_rw_texture_ ## NAME : register(u ## NUM);

Arguments

  • value NUM - A number of the texture slot.
  • value NAME - A name of the texture slot.

Texture Functions

TEXTURE(value NAME, value COORD)

Samples a texture.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.

TEXTURE_BIAS(value NAME, value COORD, value BIAS)

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

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.
  • value BIAS - Mipmap level.

TEXTURE_OFFSET_BIAS(value NAME, value COORD, value OFFSET, value BIAS)

Samples a texture using a mipmap-level offset.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.
  • value OFFSET - Offset.
  • value BIAS - Mipmap level.

TEXTURE_OFFSET(value NAME, value COORD, value OFFSET)

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

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.
  • value OFFSET - Offset.

TEXTURE_GRAD(value NAME, value COORD, value DDX, value DDY)

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

Equivalents

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

Arguments

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

TEXTURE_LOAD_LOD(value NAME, value COORD, value LOD)

Reads texel data without any filtering or sampling.

Equivalents

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

Arguments

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

TEXTURE_LOAD(value NAME, value COORD)

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

Equivalents

OpenGL
ttexelFetch(s_texture_ ## NAME,COORD,0)
Direct3D
s_texture_ ## NAME.Load(uint3(COORD,0))

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.

TEXTURE_SHADOW(value NAME, value COORD)

Samples a shadow texture.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.

TEXTURE_SHADOW_PROJ(value NAME, value COORD)

Samples a shadow texture with projection.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.

TEXTURE_CUBE_SHADOW(value NAME, value DIRECTION, value DEPTH)

Samples a cubemap shadow texture.

Equivalents

OpenGL
texture(s_texture_ ## NAME,float4(DIRECTION,DEPTH)))
Direct3D
s_texture_ ## NAME.SampleCmpLevelZero(s_sampler_compare_ ## NAME,DIRECTION,DEPTH)

Arguments

  • value NAME - A name of the texture slot.
  • value DIRECTION - Direction value.
  • value DEPTH - Depth value.

TEXTURE_2D_CUBIC(value NAME, value COORD, value TEXSIZE)

Samples a texture with bicubic interpolation.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.
  • value TEXSIZE - Texture size.

TEXTURE_RW_LOAD(value NAME, value COORD)

Loads RW texture. Works only with USE_RW_TEXTURES enabled.
Notice
If USE_RW_TEXTURES is not defined, the function initializes the float4(0.0f,0.0f,0.0f,0.0f) empty vector.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.

TEXTURE_RW_STORE(value NAME, value COORD, value VALUE)

Stores RW texture. Works only with USE_RW_TEXTURES enabled.
Notice
If USE_RW_TEXTURES is not defined, the function doesn't initialize anything.

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORD - UV coordinates.
  • value VALUE - A value to store.

TEXTURE_BIAS_ZERO(value NAME, value COORDS)

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

Equivalents

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

Arguments

  • value NAME - A name of the texture slot.
  • value COORDS - UV coordinates.

TEXTURE_ARRAY(value NAME, value COORDS, value LAYER, value LOD)

Samples a texture array using a mipmap-level.

Equivalents

OpenGL
textureLod(s_texture_ ## NAME,float3(COORDS,LAYER),LOD)
Direct3D
s_texture_ ## NAME.SampleLevel(s_sampler_ ## NAME,float3(COORDS,LAYER),LOD)

Arguments

  • value NAME - A name of the texture slot.
  • value COORDS - UV coordinates.
  • value LAYER - Layer value.
  • value LOD - Level-of-detail within the texture from which the texel will be fetched.

TEXTURE_TRIPLANAR(value TEXTURE_ID, value TEXCOORD, value WEIGHT)

Samples a texture for triplanar mapping.

Implementation

UUSL
(TEXTURE(TEXTURE_ID,TEXCOORD.zw) * WEIGHT.x + 
 TEXTURE(TEXTURE_ID,TEXCOORD.xw) * WEIGHT.y + 
 TEXTURE(TEXTURE_ID,TEXCOORD.xy) * WEIGHT.z )

Arguments

  • value TEXTURE_ID - Texture ID.
  • value TEXCOORD - UV coordinates.
  • value WEIGHT - Texture's weight in triplanar mapping.

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(value NAME)

Allows to pass a texture to function.

Equivalents

OpenGL
s_texture_ ## NAME
Direct3D
s_texture_ ## NAME,s_sampler_ ## NAME

Arguments

  • value NAME - A name of the texture slot.

TEXTURE_OUT_2(value NAME0, value NAME1)

Allows to pass two textures to a function.

Equivalents

OpenGL
TEXTURE_OUT(NAME0),TEXTURE_OUT(NAME1)
Direct3D
TEXTURE_OUT(NAME0),TEXTURE_OUT(NAME1)

Arguments

  • value NAME0 - A name of the texture slot (for the first texture).
  • value NAME1 - A name of the texture slot (for the second texture).

TEXTURE_OUT_3(value NAME0, value NAME1, value NAME2)

Allows to pass three textures to a function.

Equivalents

OpenGL
TEXTURE_OUT_2(NAME0,NAME1),TEXTURE_OUT(NAME2)
Direct3D
TEXTURE_OUT_2(NAME0,NAME1),TEXTURE_OUT(NAME2)

Arguments

  • value NAME0 - A name of the texture slot (for the first texture).
  • value NAME1 - A name of the texture slot (for the second texture).
  • value NAME2 - A name of the texture slot (for the third texture).

TEXTURE_OUT_4(value NAME0, value NAME1, value NAME2, value NAME3)

Allows to pass four textures to a function.

Equivalents

OpenGL
TEXTURE_OUT_3(NAME0,NAME1,NAME2),TEXTURE_OUT(NAME3)
Direct3D
TEXTURE_OUT_3(NAME0,NAME1,NAME2),TEXTURE_OUT(NAME3)

Arguments

  • value NAME0 - A name of the texture slot (for the first texture).
  • value NAME1 - A name of the texture slot (for the second texture).
  • value NAME2 - A name of the texture slot (for the third texture).
  • value NAME3 - A name of the texture slot (for the fourth texture).

TEXTURE_IN(value 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

  • value NAME - A name of the texture.

TEXTURE_IN_2(value NAME0, value NAME1)

Specifies two 2D textures for passing to function.

Equivalents

OpenGL
TEXTURE_IN(NAME0),TEXTURE_IN(NAME1)
Direct3D
TEXTURE_IN(NAME0),TEXTURE_IN(NAME1)

Arguments

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

TEXTURE_IN_3(value NAME0, value NAME1, value NAME2)

Specifies three 2D textures for passing to function.

Equivalents

OpenGL
TEXTURE_IN_2(NAME0,NAME1),TEXTURE_IN(NAME2)
Direct3D
TEXTURE_IN_2(NAME0,NAME1),TEXTURE_IN(NAME2)

Arguments

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

TEXTURE_IN_4(value NAME0, value NAME1, value NAME2, value NAME3)

Specifies four 2D textures for passing to function.

Equivalents

OpenGL
TEXTURE_IN_3(NAME0,NAME1,NAME2),TEXTURE_IN(NAME3)
Direct3D
TEXTURE_IN_3(NAME0,NAME1,NAME2),TEXTURE_IN(NAME3)

Arguments

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

TEXTURE_IN_CUBE(value 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

  • value NAME - A name of the texture.

TEXTURE_IN_3D(value 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

  • value NAME - A name of the texture.

TEXTURE_IN_ARRAY(value 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

  • value NAME - A name of the texture.

TEXTURE_IN_SHADOW(value 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

  • value NAME - A name of the texture.

TEXTURE_IN_ARRAY_SHADOW(value 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

  • value NAME - A name of the texture.

TEXTURE_IN_CUBE_SHADOW(value 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

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