< 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: 40

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



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

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.set_current_image_codec("FreeImage")
            


create_1d

Description

Creates an empty 1D texture.


Syntax

texture = gh_texture.create_1d(
 width,
 pf
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


create_2d

Description

Creates an empty 2D texture.


Syntax

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

Languages

Lua - Python


Parameters


Return Values


Code sample


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


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

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

Languages

Lua - Python


Parameters


Return Values


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)
            


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

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

Languages

Lua - Python


Parameters


Return Values


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)
            


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

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

Languages

Lua - Python


Parameters


Return Values


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)
            


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

texture = gh_texture.create_from_file_v5(
 full_filename,
 pf
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local demo_dir = gh_utils.get_demo_dir()
tex = 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

texture = gh_texture.create_from_file_v6(
 full_filename,
 pf,
 gen_mipmaps,
 compressed_format
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()
tex = 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

texture = gh_texture.create_from_file_v8(
 full_filename,
 pf,
 texture_unit,
 gen_mipmaps,
 compressed_format
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local texture_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()
tex = gh_texture.create_from_file_v8(demo_dir .. "./data/tex.jpg", PF_U8_RGBA, texture_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

texture = gh_texture.create_from_file_v9(
 full_filename,
 upload_to_gpu,
 pf,
 texture_unit,
 gen_mipmaps,
 compressed_format
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local upload_to_gpu = 1
local texture_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()
tex = gh_texture.create_from_file_v9(demo_dir .. "./data/tex.jpg", upload_to_gpu, PF_U8_RGBA, texture_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

texture = gh_texture.create_from_sqlite3_blob(
 dbid,
 column,
 upload_to_gpu,
 pf,
 texture_unit,
 gen_mipmaps,
 compressed_format
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local upload_to_gpu = 1
local texture_unit = 0
local gen_mipmaps = 1
local compression_format = ""
local demo_dir = gh_utils.get_demo_dir()
tex = gh_texture.create_from_sqlite3_blob_v1(dbid, column, upload_to_gpu, PF_U8_RGBA, texture_unit, gen_mipmaps, compression_format)
            


create_from_zip_file

Description

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


Syntax

texture = gh_texture.create_from_zip_file(
 zip_filename,
 filename,
 upload_to_gpu,
 pf,
 texture_unit,
 gen_mipmaps,
 compressed_format
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local upload_to_gpu = 1
local texture_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 = gh_texture.create_from_zip_file(zip_filename, filename, upload_to_gpu, PF_U8_RGBA, texture_unit, gen_mipmaps, compression_format)
            


create_from_buffer

Description

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


Syntax

texture = gh_texture.create_from_buffer(
 buffer_ptr,
 buffer_size,
 upload_to_gpu,
 pf,
 texture_unit,
 gen_mipmaps,
 compressed_format
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local PF_U8_RGBA = 3
local upload_to_gpu = 1
local texture_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 = gh_texture.create_from_buffer(buffer, buffer_size, upload_to_gpu, PF_U8_RGBA, texture_unit, gen_mipmaps, compression_format)
gh_utils.file_buffer_kill(buffer)
            


create_cube_from_file

Description

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


Syntax

texture = 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

Lua - Python


Parameters


Return Values


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)
            


create_from_sub_texture

Description

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


Syntax

texture_dst = gh_texture.create_from_sub_texture(
 texture_src,
 x, y, width, height
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


copy_sub_texture

Description

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


Syntax

texture_dst = gh_texture.copy_sub_texture(
 texture_src,
 texture_dst,
 x, y, width, height
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


get_gpu_memory_size

Description

Gets the texture GPU memory size.


Syntax

mem_size, compressed_mem_size = gh_texture.get_gpu_memory_size(
 texture
)

Languages

Lua - Python


Parameters


Return Values


Code sample


local gpu_mem_size, gpu_compressed_mem_size  = gh_texture.get_gpu_memory_size(texture)
            


gpu_memory_upload

Description

Uploads the texture data to GPU memory.


Syntax

ret = gh_texture.gpu_memory_upload(
 texture,
 texture_unit,
 create_srv,
 free_cpu_memory
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


gpu_memory_unload

Description

Unloads the texture data from GPU memory.


Syntax

ret = gh_texture.gpu_memory_unload(
 texture
)

Languages

Lua - Python


Parameters


Return Values


Code sample


gh_texture.gpu_memory_unload(texture)
            


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(
 texture
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.gpu_mem_to_cpu_mem(texture)
            


bind

Description

Bind the texture to the renderer.


Syntax

gh_texture.bind(
 texture,
 texture_unit
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.bind(texture, 0)
            


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(
 texture_unit
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


texture_unit = 1
gh_texture.reset_texture_unit(texture_unit)
            


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_texture_id,
 src_texture_id
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.inject_opacity_map(tex0, opacitymap)
            


image_bind

Description

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


Syntax

gh_texture.image_bind(
 texture,
 texture_unit,
 access_type
)

Languages

Lua - Python


Parameters


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)
            


flip_horizontal

Description

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


Syntax

gh_texture.flip_horizontal(
 texture
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.flip_horizontal(texture)
            


get_size

Description

Gets the texture size.


Syntax

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

Languages

Lua - Python


Parameters


Return Values


Code sample


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


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,
 texture_unit
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


texture_unit = 0
color_target_index = 0
gh_texture.rt_color_bind_v2(rt_id, color_target_index, texture_unit)
            


rt_depth_bind

Description

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


Syntax

gh_texture.rt_depth_bind(
 rt_id,
 texture_unit
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


texture_unit = 1
gh_texture.rt_depth_bind(rt_id, texture_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,
 texture_unit
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


texture_unit = 0
gh_texture.rt_color_cubemap_bind(rt_id, texture_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,
 texture_unit
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


texture_unit = 0
gh_texture.rt_depth_cubemap_bind(rt_id, texture_unit)
            


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(
 texture
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


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


renderer_update2d

Description

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


Syntax

gh_texture.renderer_update2d(
 texture,
 x_offset, x_offset,
 width, height
)

Languages

Lua - Python


Parameters


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)
            


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

texture = gh_texture.update_gpu_memory_from_file(
 filename,
 absolute_path
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


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

texture = gh_texture.update_gpu_memory_from_buffer(
 buffer,
 buffer_size
)

Languages

Lua - Python


Parameters


Return Values


Code sample


gh_texture.update_gpu_memory_from_buffer(texture, buffer, buffer_size)
            


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(
 texture_id,
 shared_texture_id
)

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


gh_texture.share_texture_data(texture_id, shared_texture_id)
            


set_texel_1d

Description

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


Syntax

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

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


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


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(
 texture,
 x_offset
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


set_texel_2d

Description

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


Syntax

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

Languages

Lua - Python


Parameters


Return Values

This function has no return value(s).


Code sample


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


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(
 texture,
 x_offset, y_offset
)

Languages

Lua - Python


Parameters


Return Values


Code sample


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


write_to_file_v4

Description

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


Syntax

r, g, b, a = gh_texture.write_to_file_v4(
 texture,
 filename,
 vertical_flip,
 image_format,
 saving_options
)

Languages

Lua - Python


Parameters


Return Values


Code sample


gh_texture.set_current_image_codec("FreeImage")
gh_texture.write_to_file_v4(texture, filename, vertical_flip, format)
            






GeeXLab Rootard Guide | Downloads | Contact | Newsletter