< GeeXLab Reference Guide />

> Back to Reference Guide Index


gh_texture library

Description

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


Number of functions: 42

  1. gh_texture.bind ()
  2. gh_texture.copy_sub_texture ()
  3. gh_texture.create_1d ()
  4. gh_texture.create_2d ()
  5. gh_texture.create_cube_from_file ()
  6. gh_texture.create_from_buffer ()
  7. gh_texture.create_from_file ()
  8. gh_texture.create_from_file_v2 ()
  9. gh_texture.create_from_file_v3 ()
  10. gh_texture.create_from_file_v5 ()
  11. gh_texture.create_from_file_v6 ()
  12. gh_texture.create_from_file_v8 ()
  13. gh_texture.create_from_file_v9 ()
  14. gh_texture.create_from_sqlite3_blob ()
  15. gh_texture.create_from_sub_texture ()
  16. gh_texture.create_from_zip_file ()
  17. gh_texture.flip_horizontal ()
  18. gh_texture.get_gpu_memory_size ()
  19. gh_texture.get_size ()
  20. gh_texture.get_texel_1d ()
  21. gh_texture.get_texel_2d ()
  22. gh_texture.gpu_mem_to_cpu_mem ()
  23. gh_texture.gpu_memory_unload ()
  24. gh_texture.gpu_memory_upload ()
  25. gh_texture.update_gpu_memory_from_numpy_img ()
  26. gh_texture.image_bind ()
  27. gh_texture.inject_opacity_map ()
  28. gh_texture.renderer_update ()
  29. gh_texture.renderer_update2d ()
  30. gh_texture.reset_texture_unit ()
  31. gh_texture.rt_color_bind_v2 ()
  32. gh_texture.rt_color_cubemap_bind ()
  33. gh_texture.rt_depth_bind ()
  34. gh_texture.rt_depth_cubemap_bind ()
  35. gh_texture.set_current_image_codec ()
  36. gh_texture.set_texel_1d ()
  37. gh_texture.set_texel_2d ()
  38. gh_texture.share_texture_data ()
  39. gh_texture.update_gpu_memory_from_buffer ()
  40. gh_texture.update_gpu_memory_from_file ()
  41. gh_texture.write_to_file_v4 ()
  42. gh_texture.get_num_mipmaps ()



bind

Description

Bind the texture to the renderer.


Syntax

gh_texture.bind(
 tex_id,
 tex_unit
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.bind(tex_id, 0)
			


copy_sub_texture

Description

Copies a sub part of a source texture to a destination texture.


Syntax

new_dst_tex_id = gh_texture.copy_sub_texture(
 src_tex_id,
 dst_tex_id,
 x, y, width, height
)

Languages


Parameters


Return Values


Code sample


new_dst_tex_id = gh_texture.copy_sub_texture(tex_src, tex_dst, 10, 10, 200, 200)
			


create_1d

Description

Creates an empty 1D texture.


Syntax

tex_id = gh_texture.create_1d(
 width,
 pf
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

tex_id = gh_texture.create_1d(256, PF_U8_RGBA)
			


create_2d

Description

Creates an empty 2D texture.


Syntax

tex_id = gh_texture.create_2d(
 width, height,
 pf
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

tex_id = gh_texture.create_2d(256, 256, PF_U8_RGBA)
			


create_cube_from_file

Description

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


Syntax

tex_id = gh_texture.create_cube_from_file(
 posx_img_filename,
 negx_img_filename,
 posy_img_filename,
 negy_img_filename,
 posz_img_filename,
 negz_img_filename,
 pf,
 absolute_path,
 gen_mipmaps
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local abs_path = 0
local gen_mipmaps = 1

tex_id = 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)
			


create_from_buffer

Description

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


Syntax

tex_id = gh_texture.create_from_buffer(
 buff_ptr,
 buff_size,
 upload_to_gpu,
 pf,
 tex_unit,
 gen_mipmaps,
 compressed_format
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local upload_to_gpu = 1
local tex_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()
filename = demo_dir .. "assets/image.jpg"

buffer, buffer_size = gh_utils.file_buffer_create(filename)
tex_id = gh_texture.create_from_buffer(buffer, buffer_size, upload_to_gpu, PF_U8_RGBA, tex_unit, gen_mipmaps, compression_format)
gh_utils.file_buffer_kill(buffer)
			


create_from_file

Description

Loads an image from a file and creates a 2D texture with mipmaps (mipmap generation is only supported in OpenGL - mipmap generation will be added in Vulkan later).


Syntax

tex_id = gh_texture.create_from_file(
 filename,
 pf,
 absolute_path
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local abs_path = 0

tex_id = gh_texture.create_from_file("data/tex.jpg", PF_U8_RGBA, abs_path)
			


create_from_file_v2

Description

Loads an image from a file and creates a 2D texture with mipmaps generation (mipmap generation is only supported in OpenGL - mipmap generation will be added in Vulkan later).


Syntax

tex_id = gh_texture.create_from_file_v2(
 filename,
 pf,
 absolute_path,
 gen_mipmaps
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local abs_path = 0
local gen_mipmaps = 1

tex_id = gh_texture.create_from_file_v2("data/tex.jpg", PF_U8_RGBA, abs_path, gen_mipmaps)
			


create_from_file_v3

Description

Loads an image from a file and creates a 2D texture with mipmaps generation and texture compression (mipmap generation is only supported in OpenGL - mipmap generation will be added in Vulkan later).


Syntax

tex_id = gh_texture.create_from_file_v3(
 filename,
 pf,
 absolute_path,
 gen_mipmaps,
 compression,
 free_cpu_memory
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local abs_path = 0
local gen_mipmaps = 1
local compression = 1
local free_cpu_memory = 1

tex_id = gh_texture.create_from_file_v3("data/tex.jpg", PF_U8_RGBA, abs_path, gen_mipmaps, compression, free_cpu_memory)
			


create_from_file_v5

Description

Loads an image from a file and creates a 2D texture with mipmaps generation (mipmap generation is only supported in OpenGL - mipmap generation will be added in Vulkan later).


Syntax

tex_id = gh_texture.create_from_file_v5(
 filename,
 pf
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local demo_dir = gh_utils.get_demo_dir()

tex_id = gh_texture.create_from_file_v5(demo_dir .. "./data/tex.jpg", PF_U8_RGBA)
			


create_from_file_v6

Description

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


Syntax

tex_id = gh_texture.create_from_file_v6(
 filename,
 pf,
 gen_mipmaps,
 compressed_format
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()

tex_id = gh_texture.create_from_file_v6(demo_dir .. "./data/tex.jpg", PF_U8_RGBA, gen_mipmaps, compression_format)
			


create_from_file_v8

Description

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


Syntax

tex_id = gh_texture.create_from_file_v8(
 filename,
 pf,
 tex_unit,
 gen_mipmaps,
 compressed_format
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local tex_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()

tex_id = gh_texture.create_from_file_v8(demo_dir .. "./data/tex.jpg", PF_U8_RGBA, tex_unit, gen_mipmaps, compression_format)
			


create_from_file_v9

Description

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


Syntax

tex_id = gh_texture.create_from_file_v9(
 filename,
 upload_to_gpu,
 pf,
 tex_unit,
 gen_mipmaps,
 compressed_format
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local upload_to_gpu = 1
local tex_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()

tex_id = gh_texture.create_from_file_v9(demo_dir .. "./data/tex.jpg", upload_to_gpu, PF_U8_RGBA, tex_unit, gen_mipmaps, compression_format)
			


create_from_sqlite3_blob

Description

Loads an image from raw data stored in a SQLIte3 blob and creates the 2D texture with mipmaps generation and texture compression.


Syntax

tex_id = gh_texture.create_from_sqlite3_blob(
 db_id,
 column,
 upload_to_gpu,
 pf,
 tex_unit,
 gen_mipmaps,
 compressed_format
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local upload_to_gpu = 1
local tex_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()

tex_id = gh_texture.create_from_sqlite3_blob_v1(db_id, column, upload_to_gpu, PF_U8_RGBA, tex_unit, gen_mipmaps, compression_format)
			


create_from_sub_texture

Description

Creates a texture from an existing texture. Useful to create a cropped version of a texture.


Syntax

new_dst_tex_id = gh_texture.create_from_sub_texture(
 src_tex_id,
 x, y, width, height
)

Languages


Parameters


Return Values


Code sample


tex_dst = gh_texture.create_from_sub_texture(tex_src, 10, 10, 200, 200)
			


create_from_zip_file

Description

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


Syntax

tex_id = gh_texture.create_from_zip_file(
 zip_filename,
 filename,
 upload_to_gpu,
 pf,
 tex_unit,
 gen_mipmaps,
 compressed_format
)

Languages


Parameters


Return Values


Code sample


# Pixel formats:
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

local upload_to_gpu = 1
local tex_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()
zip_filename = demo_dir .. "demo.zip"
filename = "assets/image.jpg"

tex_id = gh_texture.create_from_zip_file(zip_filename, filename, upload_to_gpu, PF_U8_RGBA, tex_unit, gen_mipmaps, compression_format)
			


flip_horizontal

Description

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


Syntax

gh_texture.flip_horizontal(
 tex_id
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.flip_horizontal(tex_id)
			


get_gpu_memory_size

Description

Gets the texture GPU memory size.


Syntax

mem_size, compressed_mem_size = gh_texture.get_gpu_memory_size(
 tex_id
)

Languages


Parameters


Return Values


Code sample


local gpu_mem_size, gpu_compressed_mem_size = gh_texture.get_gpu_memory_size(tex_id)
			


get_size

Description

Gets the texture size.


Syntax

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

Languages


Parameters


Return Values


Code sample


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


get_texel_1d

Description

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


Syntax

r, g, b, a = gh_texture.get_texel_1d(
 tex_id,
 x_offset
)

Languages


Parameters


Return Values


Code sample


r, g, b, a = gh_texture.get_texel_1d(tex_id, 0)
			


get_texel_2d

Description

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


Syntax

r, g, b, a = gh_texture.get_texel_2d(
 tex_id,
 x_offset, y_offset
)

Languages


Parameters


Return Values


Code sample


r, g, b, a = gh_texture.get_texel_2d(tex_id, 0, 0)
			


gpu_mem_to_cpu_mem

Description

Updates the texture pixmap in CPU memory with data from GPU memory. After this function, you can call functions such as get_texel_2d().


Syntax

gh_texture.gpu_mem_to_cpu_mem(
 tex_id
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.gpu_mem_to_cpu_mem(tex_id)
			


gpu_memory_unload

Description

Unloads the texture data from GPU memory.


Syntax

ret = gh_texture.gpu_memory_unload(
 tex_id
)

Languages


Parameters


Return Values


Code sample


gh_texture.gpu_memory_unload(tex_id)
			


gpu_memory_upload

Description

Uploads the texture data to GPU memory.


Syntax

ret = gh_texture.gpu_memory_upload(
 tex_id,
 tex_unit,
 create_srv,
 free_cpu_memory
)

Languages


Parameters


Return Values


Code sample


ret = gh_texture.gpu_memory_upload(tex_id, 0, 0, 1)
			


update_gpu_memory_from_numpy_img

Description

Updates the texture pixmap in GPU memory with data from a NumPy array.


Syntax

gh_texture.update_gpu_memory_from_numpy_img(
 tex_id,
 np_array
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.update_gpu_memory_from_numpy_img(tex_id, np_array)
			


image_bind

Description

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


Syntax

gh_texture.image_bind(
 tex_id,
 tex_unit,
 access_type
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


DATA_ACCESS_READ_WRITE = 0
DATA_ACCESS_WRITE_ONLY = 1
DATA_ACCESS_READ_ONLY = 2

local tex_unit = 1

gh_texture.image_bind(tex_id, tex_unit, DATA_ACCESS_WRITE_ONLY)
			


inject_opacity_map

Description

Copy the red channel of an opacity texture (the source texture) to the alpha channel of a destination texture.


Syntax

gh_texture.inject_opacity_map(
 dst_tex_id,
 opa_tex_id
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.inject_opacity_map(dst_tex_id, opa_tex_id)
			


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.).


Syntax

gh_texture.renderer_update(
 tex_id
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.flip_horizontal(tex_id)

gh_texture.renderer_update(tex_id)
			


renderer_update2d

Description

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


Syntax

gh_texture.renderer_update2d(
 tex_id,
 x_offset, y_offset,
 width, height
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.flip_horizontal(tex_id)

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

gh_texture.renderer_update2d(tex_id, 0, 0, width/2, height/2)
			


reset_texture_unit

Description

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


Syntax

gh_texture.reset_texture_unit(
 tex_unit
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


tex_unit = 1
gh_texture.reset_texture_unit(tex_unit)
			


rt_color_bind_v2

Description

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


Syntax

gh_texture.rt_color_bind_v2(
 rt_id,
 color_target_index,
 tex_unit
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


tex_unit = 0
color_target_index = 0

gh_texture.rt_color_bind_v2(rt_id, color_target_index, tex_unit)
			


rt_color_cubemap_bind

Description

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


Syntax

gh_texture.rt_color_cubemap_bind(
 rt_id,
 tex_unit
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


tex_unit = 0
gh_texture.rt_color_cubemap_bind(rt_id, tex_unit)
			


rt_depth_bind

Description

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


Syntax

gh_texture.rt_depth_bind(
 rt_id,
 tex_unit
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


tex_unit = 1
gh_texture.rt_depth_bind(rt_id, tex_unit)
			


rt_depth_cubemap_bind

Description

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


Syntax

gh_texture.rt_depth_cubemap_bind(
 rt_id,
 tex_unit
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


tex_unit = 0
gh_texture.rt_depth_cubemap_bind(rt_id, tex_unit)
			


set_current_image_codec

Description

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


Syntax

gh_texture.set_current_image_codec(
 codec_name
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.set_current_image_codec("FreeImage")
			


set_texel_1d

Description

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


Syntax

gh_texture.set_texel_1d(
 tex_id,
 x_offset,
 r, g, b, a
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.set_texel_1d(tex_id, 0, r, g, b, a)
			


set_texel_2d

Description

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


Syntax

gh_texture.set_texel_2d(
 tex_id,
 x_offset, y_offset,
 r, g, b, a
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.set_texel_2d(tex_id, 0, 0, r, g, b, a)
			


share_texture_data

Description

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


Syntax

gh_texture.share_texture_data(
 tex_id,
 shared_tex_id
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.share_texture_data(tex_id, shared_tex_id)
			


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.


Syntax

gh_texture.update_gpu_memory_from_buffer(
 tex_id,
 buff_ptr,
 buff_size
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.update_gpu_memory_from_buffer(tex_id, buffer, buffer_size)
			


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.


Syntax

gh_texture.update_gpu_memory_from_file(
 tex_id,
 filename,
 absolute_path
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


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


write_to_file_v4

Description

Write an texture to a file. Default image coded writes only jpg images. FreeImage codec writes more formats.


Syntax

gh_texture.write_to_file_v4(
 tex_id,
 filename,
 flip_image,
 image_format,
 saving_options
)

Languages


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.set_current_image_codec("FreeImage")

gh_texture.write_to_file_v4(tex_id, filename, vertical_flip, format)
			


get_num_mipmaps

Description

Returns the number of mipmap level for a texture.


Syntax

n = gh_texture.get_num_mipmaps(
 tex_id
)

Languages


Parameters


Return Values


Code sample


n = gh_texture.get_num_mipmaps(tex_id)
			






GeeXLab Rootard Guide | Downloads | Contact | Newsletter