
FEATURES	DOWNLOAD	GALLERY	BLOG	LEARN

ť Back to Reference Guide Index

gh_texture Library

Description

gh_texture is the module that manages textures: creation, destruction, parameters setting.

Number of functions: 22

gh_texture.set_current_image_codec (Lua - Python)
gh_texture.create_1d (Lua - Python)
gh_texture.create_2d (Lua - Python)
gh_texture.create_from_file (Lua - Python)
gh_texture.create_from_file_v2 (Lua - Python)
gh_texture.create_from_file_v3 (Lua - Python)
gh_texture.create_cube_from_file (Lua - Python)
gh_texture.get_gpu_memory_size (Lua - Python)
gh_texture.bind (Lua - Python)
gh_texture.activate_rt_color (Lua - Python)
gh_texture.activate_rt_depth (Lua - Python)
gh_texture.reset_texture_unit (Lua - Python)
gh_texture.image_bind (Lua - Python)
gh_texture.flip_horizontal (Lua - Python)
gh_texture.get_size (Lua - Python)
gh_texture.renderer_update (Lua - Python)
gh_texture.renderer_update2d (Lua - Python)
gh_texture.update_gpu_memory_from_file (Lua - Python)
gh_texture.update_gpu_memory_from_buffer (Lua - Python)
gh_texture.share_texture_data (Lua - Python)
gh_texture.set_texel_1d (Lua - Python)
gh_texture.set_texel_2d (Lua - Python)

gh_texture.set_current_image_codec

Description

Sets the current image codec to load and save images. Default is stb.

Languages

Lua - Python

Parameters

codec_name [STRING]: code name: 'FreeImage' or 'stb'

Return Values

This function has no return value(s).

Code sample

gh_texture.set_current_image_codec("FreeImage")

gh_texture.create_1d

Description

Creates an empty 1D texture.

Languages

Lua - Python

Parameters

width [INTEGER]: texture size.

pf [INTEGER]: pixel format. The following pixel formats are supported:

PF_U8_RGB = 1
PF_U8_BGR = 2
PF_U8_RGBA = 3
PF_U8_BGRA = 4
PF_F32_RGB = 5
PF_F32_RGBA = 6
PF_F32_R = 7
PF_U8_R = 11
PF_U8_RG = 12

Return Values

texture [INTEGER]: texture identifier

Code sample

local PF_U8_RGBA = 3
tex = gh_texture.create_1d(256, PF_U8_RGBA)

gh_texture.create_2d

Description

Creates an empty 2D texture.

Languages

Lua - Python

Parameters

width, height [INTEGER]: texture size.

pf [INTEGER]: pixel format. The following pixel formats are supported:

PF_U8_RGB = 1
PF_U8_BGR = 2
PF_U8_RGBA = 3
PF_U8_BGRA = 4
PF_F32_RGB = 5
PF_F32_RGBA = 6
PF_F32_R = 7
PF_U8_R = 11
PF_U8_RG = 12

Return Values

texture [INTEGER]: texture identifier

Code sample

local PF_U8_RGBA = 3
tex = gh_texture.create_2d(256, 256, PF_U8_RGBA)

gh_texture.create_from_file

Description

Loads an image from a file and creates the 2D texture without mipmaps

Languages

Lua - Python

Parameters

filename [STRING]: image filename.

pf [INTEGER]: pixel format. The following pixel formats are supported:

PF_U8_RGB = 1
PF_U8_BGR = 2
PF_U8_RGBA = 3
PF_U8_BGRA = 4
PF_F32_RGB = 5
PF_F32_RGBA = 6
PF_F32_R = 7
PF_U8_R = 11
PF_U8_RG = 12

absolute_path [INTEGER]: Absolute (1) or relative (0) path to the texture image.

Return Values

texture [INTEGER]: texture identifier

Code sample

local PF_U8_RGBA = 3
local abs_path = 0
tex = gh_texture.create_from_file("data/tex.jpg", PF_U8_RGBA, abs_path)

gh_texture.create_from_file_v2

Description

Loads an image from a file and creates the 2D texture with mipmaps generation.

Languages

Lua - Python

Parameters

filename [STRING]: image filename.

pf [INTEGER]: pixel format. The following pixel formats are supported:

PF_U8_RGB = 1
PF_U8_BGR = 2
PF_U8_RGBA = 3
PF_U8_BGRA = 4
PF_F32_RGB = 5
PF_F32_RGBA = 6
PF_F32_R = 7
PF_U8_R = 11
PF_U8_RG = 12

absolute_path [INTEGER]: Absolute (1) or relative (0) path to the texture image.

gen_mipmaps [INTEGER]: Generates (1) or not (0) the mipmaps.

Return Values

texture [INTEGER]: texture identifier

Code sample

local PF_U8_RGBA = 3
local abs_path = 0
local gen_mipmaps = 1
tex = gh_texture.create_from_file_v2("data/tex.jpg", PF_U8_RGBA, abs_path, gen_mipmaps)

gh_texture.create_from_file_v3

Description

Loads an image from a file and creates the 2D texture with mipmaps generation and texture compression.

Languages

Lua - Python

Parameters

filename [STRING]: image filename.

pf [INTEGER]: pixel format. The following pixel formats are supported:

PF_U8_RGB = 1
PF_U8_BGR = 2
PF_U8_RGBA = 3
PF_U8_BGRA = 4
PF_F32_RGB = 5
PF_F32_RGBA = 6
PF_F32_R = 7
PF_U8_R = 11
PF_U8_RG = 12

absolute_path [INTEGER]: Absolute (1) or relative (0) path to the texture image.

gen_mipmaps [INTEGER]: Generates (1) or not (0) the mipmaps.

compression [INTEGER]: Enables hardware compression (1) or not (0).

free_cpu_memory [INTEGER]: Frees the pixamp in CPU memory.

Return Values

texture [INTEGER]: texture identifier

Code sample

local PF_U8_RGBA = 3
local abs_path = 0
local gen_mipmaps = 1
local compression = 1
local free_cpu_memory = 1
tex = gh_texture.create_from_file_v3("data/tex.jpg", PF_U8_RGBA, abs_path, gen_mipmaps, compression, free_cpu_memory)

gh_texture.create_cube_from_file

Description

Loads an cubemap from 6 files images and creates the CUBE texture.

Languages

Lua - Python

Parameters

posx_img_filename [STRING]: POS X image filename.

negx_img_filename [STRING]: NEG X image filename.

posy_img_filename [STRING]: POS Y image filename.

negy_img_filename [STRING]: NEG Y image filename.

posz_img_filename [STRING]: POS Z image filename.

negz_img_filename [STRING]: NEG Z image filename.

pf [INTEGER]: pixel format. The following pixel formats are supported:

PF_U8_RGB = 1
PF_U8_BGR = 2
PF_U8_RGBA = 3
PF_U8_BGRA = 4
PF_F32_RGB = 5
PF_F32_RGBA = 6
PF_F32_R = 7
PF_U8_R = 11
PF_U8_RG = 12

absolute_path [INTEGER]: Absolute (1) or relative (0) path to the texture images.

gen_mipmaps [INTEGER]: Generates (1) or not (0) the mipmaps.

Return Values

texture [INTEGER]: texture identifier

Code sample

local PF_U8_RGBA = 3
local abs_path = 0
local gen_mipmaps = 1
tex = gh_texture.create_cube_from_file("posx.jpg", "negx.jpg", "posy.jpg", "negy.jpg", "posz.jpg", "negz.jpg", abs_path, PF_U8_RGBA, gen_mipmaps)

gh_texture.get_gpu_memory_size

Description

Gets the texture GPU memory size.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

Return Values

mem_size, compressed_mem_size [INTEGER]: texture size

Code sample

local gpu_mem_size, gpu_compressed_mem_size = gh_texture.get_gpu_memory_size(texture)

gh_texture.bind

Description

Bind the texture to the renderer.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

texture_unit [INTEGER]: Texture unit on which the texture is bound.

Return Values

This function has no return value(s).

Code sample

gh_texture.bind(texture, 0)

gh_texture.activate_rt_color

Description

Activates (or binds) a color texture of a render target.

Languages

Lua - Python

Parameters

rt_id [INTEGER]: render target identifier.

texture_unit [INTEGER]: Texture unit on which the texture is bound.

Return Values

This function has no return value(s).

Code sample

texture_unit = 0
gh_texture.activate_rt_color(rt_id, texture_unit)

gh_texture.activate_rt_depth

Description

Activates (or binds) a depth texture of a render target.

Languages

Lua - Python

Parameters

rt_id [INTEGER]: render target identifier.

texture_unit [INTEGER]: Texture unit on which the texture is bound.

Return Values

This function has no return value(s).

Code sample

texture_unit = 1
gh_texture.activate_rt_depth(rt_id, texture_unit)

gh_texture.reset_texture_unit

Description

Reset a texture unit: disables all texturing states and unbinds the texture that is currently bound to this texture unit.

Languages

Lua - Python

Parameters

texture_unit [INTEGER]: Texture unit on which a texture is bound.

Return Values

This function has no return value(s).

Code sample

texture_unit = 1
gh_texture.reset_texture_unit(R_ptr, texture_unit)

gh_texture.image_bind

Description

Binds a texture as an image to the renderer. image_bind() is useful with compute shaders.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

texture_unit [INTEGER]: Texture unit on which the image is bound.

access_type [INTEGER]: Specifies the red/write mode of the image:

DATA_ACCESS_READ_WRITE = 0
DATA_ACCESS_WRITE_ONLY = 1
DATA_ACCESS_READ_ONLY = 2

Return Values

This function has no return value(s).

Code sample

local texture_unit = 1
local DATA_ACCESS_WRITE_ONLY = 1
gh_texture.image_bind(texture, texture_unit, DATA_ACCESS_WRITE_ONLY)

gh_texture.flip_horizontal

Description

Flips the texture data (the pixamp) around the horizontal axe.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

Return Values

This function has no return value(s).

Code sample

gh_texture.flip_horizontal(texture)

gh_texture.get_size

Description

Gets the texture size.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

Return Values

width, height, depth [INTEGER]: texture size

Code sample

width, height, depth = gh_texture.get_size(texture)

gh_texture.renderer_update

Description

Uploads the entire pixmap to the renderer. Useful after a modification of the pixmap (flip_horizontal() for example). Works with any kind of texture (1D, 2D, CUBE, etc.)

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

Return Values

This function has no return value(s).

Code sample

gh_texture.flip_horizontal(texture)
gh_texture.renderer_update(texture)

gh_texture.renderer_update2d

Description

Uploads the pixmap to the renderer. Useful after calling flip_horizontal().

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

x_offset, x_offset [INTEGER]: offsets inside the texture pixmap.

width, height [INTEGER]: size of the texture pixmap that will be uploaded.

Return Values

This function has no return value(s).

Code sample

gh_texture.flip_horizontal(texture)
width, height, depth = gh_texture.get_size(texture)
gh_texture.renderer_update2d(texture, 0, 0, width/2, height/2)

gh_texture.update_gpu_memory_from_file

Description

Update the GPU memory of an existing texture with an image from file. The texture and the file image must have the same size.

Languages

Lua - Python

Parameters

filename [STRING]: image filename.

absolute_path [INTEGER]: Absolute (1) or relative (0) path to the texture image.

Return Values

texture [INTEGER]: texture identifier

Code sample

local abs_path = 0
gh_texture.update_gpu_memory_from_file(texture, "data/tex.jpg", abs_path)

gh_texture.update_gpu_memory_from_buffer

Description

Update the GPU memory of a memory buffer. The texture and the image in the buffer content must have the same size.

Languages

Lua - Python

Parameters

buffer [POINTER]: image buffer

buffer_size [INTEGER]: Size in bytes of the buffer.

Return Values

texture [INTEGER]: texture identifier

Code sample

gh_texture.update_gpu_memory_from_buffer(texture, buffer, buffer_size)

gh_texture.share_texture_data

Description

Shares texture data between two textures. Useful to load once a texture and use it in several windows...

Languages

Lua - Python

Parameters

texture_id [INTEGER]: texture identifier.

shared_texture_id [INTEGER]: shared texture identifier.

Return Values

This function has no return value(s).

Code sample

gh_texture.share_texture_data(texture_id, shared_texture_id)

gh_texture.set_texel_1d

Description

Sets the value of a particular texel of a 1D texture.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

x_offset [INTEGER]: offset inside the texture pixmap.

r, g, b, a [REAL]: RGBA value.

Return Values

This function has no return value(s).

Code sample

gh_texture.set_texel_1d(texture, 0, 1, 0, 0, 1)

gh_texture.set_texel_2d

Description

Sets the value of a particular texel of a 2D texture.

Languages

Lua - Python

Parameters

texture [INTEGER]: texture identifier.

x_offset, y_offset [INTEGER]: offsets inside the texture pixmap.

r, g, b, a [REAL]: RGBA value.

Return Values

This function has no return value(s).

Code sample

gh_texture.set_texel_2d(texture, 0, 0, 1, 0, 0, 1)

.:- G3D Network -:.