Texture Class
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.
Interface for handling textures.
Textures are stored on GPU.
Unigine provides different filtering modes of texture samples:
- Point filtering
- Linear filtering
- Bilinear filtering
- Trilinear filtering
- Anisotropic filtering
They are ordered from the worst visual quality to the best, thus from the least expensive performance cost to the most.
Texture has two sets of flags: sampler and format flags.
Sampler Flags#
Sampler flags can be changed dynamically at runtime for the user materials.
- WRAP_CLAMP_X
- WRAP_CLAMP_Y
- WRAP_CLAMP_Z
- WRAP_BORDER_X
- WRAP_BORDER_Y
- WRAP_BORDER_Z
- WRAP_BORDER_ONE
- WRAP_BORDER
- WRAP_MASK
- FILTER_POINT
- FILTER_LINEAR
- FILTER_BILINEAR
- FILTER_TRILINEAR
- FILTER_MASK
- ANISOTROPY_1
- ANISOTROPY_2
- ANISOTROPY_4
- ANISOTROPY_8
- ANISOTROPY_16
- ANISOTROPY_MASK
- SHADOW_COMPARE
- SHADOW_MASK
- DEFAULT_FLAGS
- SAMPLER_FLAGS
Format Flags#
Format flags changes require texture reinitialization to take effect. The format flags are read-only (editable only for the base materials).
- FORMAT_SRGB
- FORMAT_SIGNED
- FORMAT_INTEGER
- FORMAT_MASK
- MULTISAMPLE_2
- MULTISAMPLE_4
- MULTISAMPLE_8
- MULTISAMPLE_16
- MULTISAMPLE_MASK
- USAGE_READWRITE
- USAGE_RENDER
- USAGE_IMMUTABLE
- USAGE_DYNAMIC
- USAGE_STAGING
- USAGE_MASK
- FORMAT_FLAGS
Texture Class
Members
int is2DType ( ) #
Returns a value indicating if the texture is 2D texture.Return value
1 if the texture is 2D; otherwise, 0.int is3DType ( ) #
Returns a value indicating if the texture is 3D texture.Return value
1 if the texture is 3D; otherwise, 0.int isAnisotropy ( ) #
Checks texture anisotropy.Return value
1 if the texture filter is anisotropy, otherwise, 0.int isArrayType ( ) #
Returns a value indicating if the texture is Array texture.Return value
1 if the texture type is an array; otherwise, 0.int isBilinear ( ) #
Checks texture filter.Return value
1 if the texture filter is bilinear or trilinear.int isColorFormat ( ) #
Returns a value indicating if the texture is color texture.Return value
1 if the texture is color texture; otherwise, 0.int isCombinedFormat ( ) #
Returns a value indicating if the texture is stored in a combined format (RGB565, RGBA4, RGB5A1, R24B8, or RGB10A2).Return value
1 if the texture is in combined format; otherwise, 0.int isCompressedFormat ( ) #
Returns a value indicating if the texture is stored in a compressed format (DXT1, DXT3, DXT5, ATI1, ATI2, ZLC1 or ZLC2).Return value
1 if the texture is in a compressed format; otherwise, 0.int isCubeType ( ) #
Returns a value indicating if the texture is Cube texture.Return value
1 if the texture type is cube; otherwise, 0.int isValid ( ) #
Returns a value indicating if the texture is valid (null-pointer check).Return value
1 if the texture is valid; otherwise, 0.void * getD3D11DepthStencilView ( ) #
Returns Direct3D11 depth stencil view.void * getD3D11DepthStencilView ( int index ) #
Returns Direct3D11 depth stencil view.Arguments
- int index - Index.
void * getD3D11RenderTargetView ( int index ) #
Returns Direct3D11 render target view.Arguments
- int index - Index.
void * getD3D11RenderTargetView ( ) #
Returns Direct3D11 render target view.void * getD3D11ShaderResourceView ( ) #
Returns Direct3D11 render target view.void * getD3D11Texture ( ) #
Returns Direct3D11 texture.void * getD3D11UnorderedAccessView ( int r32_typeless ) #
Returns Direct3D11 render target view.Arguments
- int r32_typeless
int getDepth ( int level = 0 ) #
Returns the depth for the given texture mipmap level.Arguments
- int level - Mipmap level number in the range from 0 to the total number of mipmaps.
Return value
Texture mipmap level depth.int isDepthFormat ( ) #
Returns a value indicating if the texture is depth texture.Return value
1 if the texture is depth texture; otherwise, 0.void setFlags ( int flags ) #
Sets texture flags.Arguments
- int flags - Texture flags.
int getFlags ( ) #
Returns texture flags.Return value
Texture flags.int isFloatFormat ( ) #
Returns a value indicating if the texture is stored in a float format (R32F, RG32F, RGB32F or RGBA32F).Return value
1 if the texture is in float format; otherwise, 0.int getFormat ( ) #
Gets the texture format.Return value
Texture format.string getFormatName ( ) #
Gets the texture format name.Return value
Texture format name.int getGLInternalFormat ( ) #
Returns OpenGL internal format.Return value
OpenGL internal format.int getGLPixelFormat ( ) #
Returns OpenGL pixel format.Return value
OpenGL pixel format.int getGLPixelType ( ) #
Returns OpenGL pixel type.Return value
OpenGL pixel type.int getGLTarget ( ) #
Returns OpenGL texture target.Return value
OpenGL texture target.int getGLTextureID ( ) #
Returns OpenGL texture identifier.Return value
OpenGL texture identifier.int isHalfFormat ( ) #
Returns a value indicating if the texture is stored in a half-float format (R16F, RG16F, RGB16F or RGBA16F).Return value
1 if the texture is in half-float format; otherwise, 0.int getHeight ( int level = 0 ) #
Returns the height for the specified texture mipmap level.Arguments
- int level - Mipmap level number in the range from 0 to the total number of mipmaps.
Return value
Texture mipmap level height.int setImage ( Image image ) #
Sets texture data using the data of the specified source image.In DX11, when setting the image, the source formats listed below are converted as follows:
- RGB565 -> RGBA8
- RGBA4 -> RGBA8
- RGB5A1 -> RGBA8
- RGB8 -> RGBA8
- RGB16 -> RGBA16
- RGB16U -> RGBA16U
- RGB16F -> RGBA16F
- RGB32F -> RGBA32F
Arguments
- Image image - Source image to be used for setting texture data.
Return value
1 if the data was set successfully; otherwise, 0.int getImage ( Image image ) #
Gets texture data and puts it to the specified target image.Arguments
- Image image - Target image, to which the texture data is to be put.
Return value
1 if the data was received; otherwise, 0.int setImage2D ( Image image, int offset_x, int offset_y, int texture_format = -1 ) #
Sets texture data using the data of the specified 2D or 2D array image.The following conditions must be satisfied:
- Both texture and image types must be either 2D or 2D_ARRAY.
- Texture resolution must be greater or equal to the image resolution.
- Image and texture mipmap counts must be equal (the same is for layer counts of 2D arrays).
Arguments
- Image image - Source image to be used for setting texture data.
- int offset_x - Offset along the X axis (in pixels) starting from which the data of the specified image is to be taken. The following condition must be satisfied: offset_x < texture_width - image_width.
- int offset_y - Offset along the Y axis (in pixels) starting from which the data of the specified image is to be taken. The following condition must be satisfied: offset_y < texture_height - image_height.
- int texture_format - Texture format identifier (see the TEXTURE_FORMAT_* variables), or -1 - auto-detect.
Return value
1 if the data was set successfully; otherwise, 0.int setImageLayer ( Image image, int layer, int texture_format = -1 ) #
Sets the data of the specified layer of the 2D texture array using the data of the specified 2D image.The following conditions must be satisfied:
- Texture and image must have the same resolution.
- Image and texture mipmap counts must be equal (the same is for layer counts of 2D arrays).
Arguments
- Image image - Source image to be used for setting the data of the 2D texture array layer.
- int layer - Number of the 2D texture array layer, for which the data is to be set.
- int texture_format - Texture format identifier (see the TEXTURE_FORMAT_* variables), or -1 - auto-detect.
Return value
1 if the data was set successfully; otherwise, 0.int getMultisample ( ) #
Returns the multisample count.Return value
Multisample count.int getNumChannels ( ) #
Returns the number of channels.Return value
Number of channels.int getNumFaces ( ) #
Returns a number of faces in the texture.Return value
Number of faces.int getNumLayers ( ) #
Returns a number of layers in the texture.Return value
Number of layers.int getNumMipmaps ( ) #
Returns the texture mipmap count.Return value
Texture mipmap count.int isRawFormat ( ) #
Returns a value indicating if the texture is uncompressed (stored in R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, RGB565, RGBA4, RGB5A1, RGB10A2, R24B8, D16, D24, D24S8, D32F, or D32FS8 format).Return value
1 if the texture is uncompressed; otherwise, 0.int getType ( ) #
Gets the texture type.Return value
Texture type.string getTypeName ( ) #
Gets the texture type name.Return value
Texture type name.int isUCharFormat ( ) #
Returns a value indicating if the texture is stored in an unsigned char format (R8, RG8, RGB8, RGBA8, DXT1, DXT3, DXT5, ATI1 or ATI2).Return value
1 if the texture is in unsigned char format; otherwise, 0.int isUShortFormat ( ) #
Returns a value indicating if the texture is stored in an unsigned short format (R16, RG16, RGB16 or RGBA16).Return value
1 if the texture is in unsigned short format; otherwise, 0.int getWidth ( int level = 0 ) #
Returns the width for the specified texture mipmap level.Arguments
- int level - Mipmap level number in the range from 0 to the total number of mipmaps.
Return value
Texture mipmap level width.void bindCompute ( int unit ) #
Binds compute texture.Arguments
- int unit - Texture unit.
void bindFragment ( int unit ) #
Binds fragment texture.Arguments
- int unit - Texture unit.
void bindVertex ( int unit ) #
Binds vertex texture.Arguments
- int unit - Texture unit.
void clear ( ) #
Clears texture.int copy2D ( int dest_x = 0, int dest_y = 0, int src_x = 0, int src_y = 0, int w = -1, int h = -1 ) #
Copies 2D texture.Arguments
- int dest_x - The offset of the source texture along the X-axis.
- int dest_y - The offset of the source texture along the Y-axis.
- int src_x - The offset of the destination texture along the X-axis.
- int src_y - The offset of the destination texture along the Y-axis.
- int w - The width of the destination texture.
- int h - The height of the destination texture.
Return value
1 if the texture was copied; otherwise, 0.int copyCube ( int face, int dest_x = 0, int dest_y = 0, int src_x = 0, int src_y = 0, int w = -1, int h = -1 ) #
Copies Cube texture.Arguments
- int face - The face of the cube.
- int dest_x - The offset of the source texture along the X-axis.
- int dest_y - The offset of the source texture along the Y-axis.
- int src_x - The offset of the destination texture along the X-axis.
- int src_y - The offset of the destination texture along the Y-axis.
- int w - The width of the destination texture.
- int h - The height of the destination texture.
Return value
1 if the texture was copied; otherwise, 0.static Texture Texture ( ) #
Texture constructor.Return value
Pointer to the created texture.int create ( Image image, int flags = DEFAULT_FLAGS ) #
Texture constructor.Arguments
- Image image - Image pointer.
- int flags - Texture flags.
Return value
1 if the texture was created successfully; otherwise, 0.int create2D ( int width, int height, int format, int flags = DEFAULT_FLAGS ) #
Creates 2D texture.Arguments
- int width - Texture width.
- int height - Texture height.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the texture was created successfully; otherwise, 0.int create2DArray ( int width, int height, int num_layers, int format, int flags = DEFAULT_FLAGS ) #
Creates 2D Array texture.Arguments
- int width - Texture width.
- int height - Texture height.
- int num_layers - Texture layers.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the 2D array texture was created; otherwise, 0.int create3D ( int width, int height, int depth, int format, int flags = DEFAULT_FLAGS ) #
Creates 3D texture.Arguments
- int width - Texture width.
- int height - Texture height.
- int depth - Texture depth.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the 3D texture was created; otherwise, 0.int createCube ( int width, int height, int format, int flags = DEFAULT_FLAGS ) #
Creates Cube texture.Arguments
- int width - Texture width.
- int height - Texture height.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the cubemap texture was created; otherwise, 0.int createCubeArray ( int width, int height, int num_layers, int format, int flags = DEFAULT_FLAGS ) #
Creates Cube Array texture.Arguments
- int width - Texture width.
- int height - Texture height.
- int num_layers - Texture layers.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the cubemap texture array was created; otherwise, 0.int createMipmaps ( ) #
Creates mipmaps stack.Return value
1 if the mipmaps stack was created; otherwise, 0.void destroy ( ) #
Destroys texture.int fromD3D11Texture2D ( int width, int height, int format, int internal_format, int flags ) #
Creates 2D texture from external D3D11Texture pointer.Arguments
- int width - Texture width.
- int height - Texture height.
- int format - Texture format.
- int internal_format - Internal texture format.
- int flags - Texture flags.
Return value
1 if the 2D texture from D3D11 was created; otherwise, 0.int fromD3D11Texture2D ( int width, int height, int format, int flags ) #
Creates 2D texture from external D3D11Texture pointer.Arguments
- int width - Texture width.
- int height - Texture height.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the 2D texture from D3D11 was created; otherwise, 0.int fromGLTexture2D ( int width, int height, int format, int flags ) #
Creates texture from external GL texture ID.Arguments
- int width - Texture width.
- int height - Texture height.
- int format - Texture format.
- int flags - Texture flags.
Return value
1 if the 2D texture from external GL texture ID was created; otherwise, 0.int fromGLTexture2D ( int width, int height, int format, int internal_format, int flags ) #
Creates texture from external GL texture IDArguments
- int width - Texture width.
- int height - Texture height.
- int format - Texture format.
- int internal_format - Internal texture format.
- int flags - Texture flags.
Return value
1 if the 2D texture from external GL texture ID was created; otherwise, 0.int load ( string name, int flags = DEFAULT_FLAGS ) #
Loads texture from file.Arguments
- string name - File name.
- int flags - Texture flags.
Return value
1 if the texture was loaded; otherwise, 0.void render2D ( float x0 = -1.0f, float y0 = -1.0f, float x1 = 1.0f, float y1 = 1.0f ) #
Renders 2D texture. This function creates 4 vertices (2 polygons) by using 2 X-coordinates and 2 Y-coordinates and sends it to be rendered.Arguments
- float x0 - The first X-coordinate.
- float y0 - The first Y-coordinate.
- float x1 - The second X-coordinate.
- float y1 - The second Y-coordinate.
void render2DArray ( int layer, float x0 = -1.0f, float y0 = -1.0f, float x1 = 1.0f, float y1 = 1.0f ) #
Renders 2D Array texture. This function creates 4 vertices (2 polygons) of the texture layer by using 2 X-coordinates and 2 Y-coordinates and sends it to be rendered.Arguments
- int layer - The number of layer.
- float x0 - The first X-coordinate.
- float y0 - The first Y-coordinate.
- float x1 - The second X-coordinate.
- float y1 - The second Y-coordinate.
void render2DScreen ( float x0 = -1.0f, float y0 = -1.0f, float x1 = 1.0f, float y1 = 1.0f ) #
Renders 2D Screen texture. This function creates 3 vertices (1 polygon) and and sends texture to be rendered inside the polygon to avoid artifacts on the edge of 2 polygons if the anti-aliasing is used.Arguments
- float x0 - The first X-coordinate.
- float y0 - The first Y-coordinate.
- float x1 - The second X-coordinate.
- float y1 - The second Y-coordinate.
void renderCube ( int face, float x0 = -1.0f, float y0 = -1.0f, float x1 = 1.0f, float y1 = 1.0f ) #
Renders Cube texture. This function creates 4 vertices (2 polygons) of the given face of the cube texture by using 2 X-coordinates and 2 Y-coordinates and sends it to be rendered.Arguments
- int face - The face of the cube.
- float x0 - The first X-coordinate.
- float y0 - The first Y-coordinate.
- float x1 - The second X-coordinate.
- float y1 - The second Y-coordinate.
void renderCubeArray ( int face, int layer, float x0 = -1.0f, float y0 = -1.0f, float x1 = 1.0f, float y1 = 1.0f ) #
Renders Cube Array texture. This function creates 4 vertices (2 polygons) of the given face of the cube texture layer by using 2 X-coordinates and 2 Y-coordinates and sends it to be rendered.Arguments
- int face - The face of the cube.
- int layer - The layer number.
- float x0 - The first X-coordinate.
- float y0 - The first Y-coordinate.
- float x1 - The second X-coordinate.
- float y1 - The second Y-coordinate.
void unbindCompute ( int unit ) #
Unbinds compute texture.Arguments
- int unit - Texture unit.
void unbindFragment ( int unit ) #
Unbinds fragment texture.Arguments
- int unit - Texture unit.
void unbindVertex ( int unit ) #
Unbinds vertex texture.Arguments
- int unit - Texture unit.
int formatImageToTexture ( int image_format, int flags ) #
Returns the texture format corresponding to the specified image format.Arguments
- int image_format - Image format identifier (see the IMAGE_FORMAT_* variables) or 0 if the specified texture format is unknown.
- int flags - Unsigned format flag. 1 to interpret integer image format as unsigned, 0 - as signed.
Return value
Texture format identifier (see the TEXTURE_FORMAT_* variables) or 0 if the specified image format is unknown.int formatTextureToImage ( int texture_format ) #
Returns the image format corresponding to the specified texture format.Arguments
- int texture_format - Texture format identifier (see the TEXTURE_FORMAT_* variables).
Return value
Image format identifier (see the IMAGE_FORMAT_* variables) or 0 if the specified texture format is unknown.int typeTextureToImage ( int texture_type ) #
Returns the image type corresponding to the specified texture type.Arguments
- int texture_type - Texture type identifier (see the TEXTURE_TEXTURE_* variables).
Return value
Image type identifier (see the IMAGE_* variables) or 0 if the specified texture type is unknown.int getImageFormat ( ) #
Returns the image format corresponding to the current texture format.Return value
Image format identifier (see the IMAGE_FORMAT_* variables) or 0 if the specified texture format is unknown.void clearBuffer ( ) #
Clears all levels of the texture image (fills all its elements with 0-values).void clearBuffer ( vec4 color ) #
Clears all levels of the texture image (fills all its elements with the clecified color values).Arguments
- vec4 color - Color to be used to fill the buffer.
void swap ( Texture texture ) #
Swaps the data of the current texture with the source texture.Arguments
- Texture texture - Source texture.
int copy ( Texture src ) #
Copies the data of the source texture to the texture.Arguments
- Texture src - Source texture.
Return value
1 if the data of the source texture is copied successfully; otherwise, 0.void setDebugName ( string name ) #
Sets a friendly name for GPU debugging (RenderDoc, NVIDIA Nsight). It can be used to help you determine if the corresponding object interface pointer caused the leak. Memory leaks are reported by the debug software layer by outputting a list of object interface pointers along with their friendly names.Arguments
- string name - Friendly debug name to be set.
string getDebugName ( ) #
Returns the currently used friendly name for GPU debugging (RenderDoc, NVIDIA Nsight). It can be used to help you determine if the corresponding object interface pointer caused the leak. Memory leaks are reported by the debug software layer by outputting a list of object interface pointers along with their friendly names.Return value
Friendly debug name.int getVideoMemoryUsage ( int width, int height, int format, int num_mipmaps, int flags, int num_faces, int num_layers, int depth ) #
Returns the amount of memory occupied by a texture with the specified parameters.Arguments
- int width - Texture width, in pixels.
- int height - Texture height, in pixels.
- int format - Texture format.
- int num_mipmaps - Number of mipmaps in the texture.
- int flags - Texture flags.
- int num_faces - Number of faces in the texture.
- int num_layers - Number of layers in the texture.
- int depth - Texture depth.
Return value
Texture size, in bytes.int copyRegion ( Texture src, ivec3 src_coords, int src_level, ivec3 dest_coords, int dest_level, int width, int height, int depth ) #
Copies the specified region from the source texture.Arguments
- Texture src - Source texture from which the data is to be copied.
- ivec3 src_coords - Coordinates in the source texture starting from which the region's data is to be taken.
- int src_level - Source texture mipmap level number in the range from 0 to the total number of mipmaps.
- ivec3 dest_coords - Coordinates in the texture starting from which the data from the source texture is to be pasted.
- int dest_level - Target mipmap level number in the range from 0 to the total number of mipmaps.
- int width - Width of the region to be copied, in pixels.
- int height - Height of the region to be copied, in pixels.
- int depth - Depth of the region to be copied, in pixels.
Return value
1 if the specified region was successfully copied from the source to the destination; otherwise, 0.int setBlob ( Blob blob ) #
Sets texture data from the specified source blob.Arguments
- Blob blob - Source blob containing texture data.
Return value
1 if the data was set successfully; otherwise, 0.void setOwnership ( int ownership ) #
Sets the engine ownership flag for the texture. If the flag is set the Engine takes care of the texture as if it was created by the Engine, otherwise the user should manage the texture manually.Arguments
- int ownership - 1 to enable the Engine to automatically manage the lifetime of the texture and memory used; 0 to manage the texture manually (destroy the object, do all necessary memory cleanup).
int isOwnership ( ) #
Returns the ownership flag that defines if the texture is to be automatically managed by the Engine. If the flag is set the Engine takes care of the texture as if it was created by the Engine, otherwise the user should manage the texture manually.Return value
1 if the Engine automatically manages the lifetime of the texture and memory used; otherwise, 0 - user should manage the texture manually (destroy the object, do all necessary memory cleanup).Last update:
2021-12-13
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)