Scripting API for GeeXLab 0.51.0.0

updated on 2023.03.27

gh_asus_aura windows

ASUS Aura LED illumination module

gh_asus_aura is ASUS Aura LED illumination module.
It provides functions to manage the illumination on various ASUS products: motherboards, graphics cards, RAM, keyboards and mice (RAM, keyboards and mice are not yet supported by gh_asus_aura).
Only for Windows 32-bit.

get_gpu_light_ctrl_num_leds

Returns the number of LEDs for a particular graphics card light controller.

syntax

num_leds = gh_asus_aura.get_gpu_light_ctrl_num_leds (
light_ctrl_index
)

parameters

light_ctrl_index INTEGER light controller index in the range (0 … num_light_ctrl - 1)

return values

num_leds INTEGER number of LEDs

code sample

light_ctrl_index = 0
num_leds = gh_asus_aura.get_gpu_light_ctrl_num_leds(light_ctrl_index)

get_mb_light_ctrl_num_leds

Returns the number of LEDs for a particular motherboard light controller.

syntax

num_leds = gh_asus_aura.get_mb_light_ctrl_num_leds (
light_ctrl_index
)

parameters

light_ctrl_index INTEGER light controller index in the range (0 … num_light_ctrl - 1)

return values

num_leds INTEGER number of LEDs

code sample

light_ctrl_index = 0
num_leds = gh_asus_aura.get_mb_light_ctrl_num_leds(light_ctrl_index)

get_num_gpu_light_ctrl

Returns the number of light controllers of the graphics card.

syntax

num_light_ctrl = gh_asus_aura.get_num_gpu_light_ctrl()

parameters

none

return values

num_light_ctrl INTEGER number of light controllers

code sample

num_light_ctrl = gh_asus_aura.get_num_gpu_light_ctrl()

get_num_mb_light_ctrl

Returns the number of light controllers of the motherboard.

syntax

num_light_ctrl = gh_asus_aura.get_num_mb_light_ctrl()

parameters

none

return values

num_light_ctrl INTEGER number of light controllers

code sample

num_light_ctrl = gh_asus_aura.get_num_mb_light_ctrl()

set_gpu_led_color

Sets the RGB color of a particular LED of the graphics card.

syntax

gh_asus_aura.set_gpu_led_color (
light_ctrl_index,
led_index,
r, g, b
)

parameters

light_ctrl_index INTEGER light controller index in the range (0 … num_light_ctrl - 1)
led_index INTEGER LED index in the range (0 … num_leds - 1)
r, g, b INTEGER RGB color in the range (0 … 255) per channel

return values

none

code sample

light_ctrl_index = 0
led_index = 0
r = 255
g = 0
b = 0
gh_asus_aura.set_gpu_led_color(light_ctrl_index, led_index, r, g, b)

set_gpu_mode

Sets the mode of a particular graphics card light controller.
To program the LEDs, the software programming mode (mode=1) must be used.

syntax

gh_asus_aura.set_gpu_mode (
light_ctrl_index,
mode
)

parameters

light_ctrl_index INTEGER light controller index in the range (0 … num_light_ctrl - 1)
mode BOOLEAN 1 (software programming) or 0 (default)

return values

none

code sample

light_ctrl_index = 0
mode = 1
gh_asus_aura.set_gpu_mode(light_ctrl_index, mode)

set_mb_led_color

Sets the RGB color of a particular LED of the motherboard.

syntax

gh_asus_aura.set_mb_led_color (
light_ctrl_index,
led_index,
r, g, b
)

parameters

light_ctrl_index INTEGER light controller index in the range (0 … num_light_ctrl - 1)
led_index INTEGER LED index in the range (0 … num_leds - 1)
r, g, b INTEGER RGB color in the range (0 … 255) per channel

return values

none

code sample

light_ctrl_index = 0
led_index = 0
r = 255
g = 0
b = 0
gh_asus_aura.set_mb_led_color(light_ctrl_index, led_index, r, g, b)

set_mb_mode

Sets the mode of a particular motherboard light controller.
To program the LEDs, the software programming mode (mode=1) must be used.

syntax

gh_asus_aura.set_mb_mode (
light_ctrl_index,
mode
)

parameters

light_ctrl_index INTEGER light controller index in the range (0 … num_light_ctrl - 1)
mode BOOLEAN 1 (software programming) or 0 (default)

return values

none

code sample

light_ctrl_index = 0
mode = 1
gh_asus_aura.set_mb_mode(light_ctrl_index, mode)

gh_audio raspberry tinkerboard

Audio / sound system module

gh_audio is the module that manages sounds: creation, destruction, playing.
The audio module is based on FMOD and is available for the Windows, Linux and macOS platforms.
For the Raspberry Pi platform, look at the gh_av library.

sound_create

Creates a sound.

syntax

sound_id = gh_audio.sound_create (
filename,
absolute_path,
streaming
)

parameters

filename STRING audio filename
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)
streaming BOOLEAN streaming: 1 (enabled) or 0 (disabled)

return values

sound_id ID sound identifier

code sample

filename = demo_dir .. "audio/sound01.mp3"
local is_absolute_path = 0
sound_id = gh_audio.sound_create(filename, is_absolute_path, 1)

sound_create_from_buffer

Creates a sound from a memory buffer.

syntax

sound_id = gh_audio.sound_create_from_buffer (
buff_ptr,
buff_size,
streaming
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
streaming BOOLEAN streaming: 1 (enabled) or 0 (disabled)

return values

sound_id ID sound identifier

code sample

buffer, buffer_size = gh_utils.file_buffer_create(audio_filename)
sound_id = gh_audio.sound_create_from_buffer(buffer, buffer_size, 0)
gh_utils.file_buffer_kill(buffer)

sound_create_from_sqlite3_blob

Creates a sound from raw data stored a in a SQLite3 blob.

syntax

sound_id = gh_audio.sound_create_from_sqlite3_blob (
db_id,
column,
streaming
)

parameters

db_id ID database identifier
column INTEGER index of the column
streaming BOOLEAN streaming: 1 (enabled) or 0 (disabled)

return values

sound_id ID sound identifier

code sample

sound_id = gh_audio.sound_create_from_sqlite3_blob_v1(db_id, column, 0)

sound_create_from_zip

Creates a sound from a filename stored a in zip archive.

syntax

sound_id = gh_audio.sound_create_from_zip (
zip_filename,
filename,
streaming
)

parameters

zip_filename STRING absolute path of the zip file
filename STRING sound file in the zip archive
streaming BOOLEAN streaming: 1 (enabled) or 0 (disabled)

return values

sound_id ID sound identifier

code sample

zip_filename = demo_dir .. "data.zip"
sound_id = gh_audio.sound_create_from_zip(zip_filename, "audio/sound01.wav", 0)

sound_create_v2

wip

Creates a sound - Not well tested / experimental

syntax

sound_id = gh_audio.sound_create_v2 (
sampling_rate,
num_channels,
duration_sec,
bits_per_sample,
frequency,
generator_type,
volume,
time
)

parameters

sampling_rate INTEGER sampling rate
num_channels INTEGER number of channels
duration_sec INTEGER duration in seconds
bits_per_sample INTEGER bits per sample
frequency INTEGER frequency in Hz
generator_type ENUM( audio_fmod_generator_type ) type of sound generator (1 to 4)
volume REAL sound volume
time REAL time

return values

sound_id ID sound identifier

code sample

FMOD_GENERATOR_SINE_WAVE = 1
FMOD_GENERATOR_SAWTOOTH = 2
FMOD_GENERATOR_SQUARE = 3
FMOD_GENERATOR_WHITE_NOISE = 4

generator_type = FMOD_GENERATOR_SINE_WAVE

sound_id = gh_audio.sound_create_v2(sampling_rate, num_channels, duration_sec, bits_per_sample, frequency, generator_type, volume, time)

sound_create_v3

Creates a sound from a absolute path filename.

syntax

sound_id = gh_audio.sound_create_v3 (
filename,
streaming
)

parameters

filename STRING audio filename
streaming BOOLEAN streaming: 1 (enabled) or 0 (disabled)

return values

sound_id ID sound identifier

code sample

filename = demo_dir .. "audio/sound01.mp3"
streaming = 1
sound_id = gh_audio.sound_create_v3(filename, streaming)

sound_get_duration_ms

Gets the duration of a sound in milliseconds.

syntax

duration = gh_audio.sound_get_duration_ms (
sound_id
)

parameters

sound_id ID sound identifier

return values

duration INTEGER duration in milliseconds

code sample

duration = gh_audio.sound_get_duration_ms(sound_id)

sound_get_open_state

Gets the open status of a sound.

syntax

open_state, percent_buffered = gh_audio.sound_get_open_state (
sound_id
)

parameters

sound_id ID sound identifier

return values

open_state ENUM( audio_fmod_openstate ) state (0 to 7)
percent_buffered INTEGER percent buffered

code sample

-- Possible states
FMOD_OPENSTATE_READY = 0 -- Opened and ready to play.
FMOD_OPENSTATE_LOADING = 1 -- Initial load in progress.
FMOD_OPENSTATE_ERROR = 2 -- Failed to open - file not found, out of memory etc.
FMOD_OPENSTATE_CONNECTING = 3 -- Connecting to remote host (internet sounds only).
FMOD_OPENSTATE_BUFFERING = 4 -- Buffering data.
FMOD_OPENSTATE_SEEKING = 5 -- Seeking to subsound and re-flushing stream buffer.
FMOD_OPENSTATE_PLAYING = 6 -- Ready and playing, but not possible to release at this time without stalling the main thread.
FMOD_OPENSTATE_SETPOSITION = 7 -- Seeking within a stream to a different position.

open_state, percentbuffered = gh_audio.sound_get_open_state(sound_id)

sound_get_position_ms

Gets the current position in a sound instance in milliseconds.

syntax

position = gh_audio.sound_get_position_ms (
sound_id,
channel
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance

return values

position INTEGER current position in milliseconds

code sample

position = gh_audio.sound_get_position_ms(sound_id, channel)

sound_get_volume

Gets the volume level of a particular sound instance.

syntax

volume = gh_audio.sound_get_volume (
sound_id,
channel
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance

return values

volume REAL volume from 0.0 to 1.0

code sample

volume = gh_audio.sound_get_volume(sound_id, channel)

sound_is_playing

Checks if a sound is currently playing.

syntax

is_playing = gh_audio.sound_is_playing (
sound_id,
channel
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance

return values

is_playing BOOLEAN playing state: 1 (true) or 0 (false)

code sample

is_playing = gh_audio.sound_is_playing(sound_id, channel)

sound_kill

Destroys a sound.

syntax

gh_audio.sound_kill (
sound_id
)

parameters

sound_id ID sound identifier

return values

none

code sample

gh_audio.sound_kill(sound_id)

sound_play

Plays a sound.

syntax

channel = gh_audio.sound_play (
sound_id
)

parameters

sound_id ID sound identifier

return values

channel INTEGER sound instance

code sample

channel = gh_audio.sound_play(sound_id)

sound_set_loop_state

Sets the loop state.

syntax

gh_audio.sound_set_loop_state (
sound_id,
state
)

parameters

sound_id ID sound identifier
state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_audio.sound_set_loop_state(sound_id, 1)

sound_set_paused

Sets the paused state of a particular sound instance.

syntax

gh_audio.sound_set_paused (
sound_id,
channel,
state
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance
state BOOLEAN paused: 1 (true) or 0 (false)

return values

none

code sample

gh_audio.sound_set_paused(sound_id, channel, 1)

sound_set_volume

Sets the volume level of a particular sound instance.

syntax

gh_audio.sound_set_volume (
sound_id,
channel,
volume
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance
volume REAL volume from 0.0 to 1.0

return values

none

code sample

gh_audio.sound_set_volume(sound_id, channel, 0.5)

sound_spectrum_get_num_values

Gets the number of entries in the audio buffer.

syntax

num_entries = gh_audio.sound_spectrum_get_num_values (
sound_id,
channel
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance

return values

num_entries INTEGER number of entries

code sample

num_values = gh_audio.sound_spectrum_get_num_values(sound_id, channel)

sound_spectrum_get_value

Gets a particular value from the audio buffer.

syntax

value = gh_audio.sound_spectrum_get_value (
sound_id,
channel,
value_index
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance
value_index INTEGER entry index (from 0 to num_values-1)

return values

value REAL value

code sample

local value = gh_audio.sound_spectrum_get_value(sound_id, channel, value_index)

sound_spectrum_read

Reads the audio buffer.

syntax

gh_audio.sound_spectrum_read (
sound_id,
channel
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance

return values

none

code sample

gh_audio.sound_spectrum_read(sound_id, channel)

sound_spectrum_read_v2

Reads the audio buffer.

syntax

gh_audio.sound_spectrum_read_v2 (
sound_id,
channel,
fft_window_type
)

parameters

sound_id ID sound identifier
channel INTEGER sound instance
fft_window_type ENUM( audio_fft_window_type ) FFT window type - Default value: window_hamming

return values

none

code sample

-- Possible window types:
"window_rect"
"window_triangle"
"window_hamming" -- Default value
"window_hanning"
"window_blackman"
"window_blackmanharris"

fft_window_type =  "window_hamming"
gh_audio.sound_spectrum_read_v2(sound_id, channel, fft_window_type)

sound_update_audio_data_params

wip

Updates parameters of a sound that has been created with sound_create_v2().

syntax

gh_audio.sound_update_audio_data_params (
sound_id,
sampling_rate,
num_channels,
duration_sec,
bits_per_sample,
frequency,
generator_type,
volume,
time
)

parameters

sound_id ID sound identifier
sampling_rate INTEGER sampling rate
num_channels INTEGER number of channels
duration_sec INTEGER duration in seconds
bits_per_sample INTEGER bits per sample
frequency INTEGER frequency in Hz
generator_type ENUM( audio_fmod_generator_type ) type of sound generator (1 to 4)
volume REAL sound volume
time REAL time

return values

none

code sample

FMOD_GENERATOR_SINE_WAVE = 1
FMOD_GENERATOR_SAWTOOTH = 2
FMOD_GENERATOR_SQUARE = 3
FMOD_GENERATOR_WHITE_NOISE = 4

generator_type = FMOD_GENERATOR_SINE_WAVE

gh_audio.sound_update_audio_data_params(sound_id, sampling_rate, num_channels, duration_sec, bits_per_sample, frequency, generator_type, volume, time)

update

Updates the sound system.
Must be called once per frame.

syntax

gh_audio.update()

parameters

none

return values

none

code sample

gh_audio.update()

gh_av

Audio / video module

gh_av is the module that manages audio/video playback.
This module is based on FFmpeg and is available for all platforms: Windows, Linux, macOS, Raspberry Pi and Tinker Board.

decoder_close

Cleans up and closes an audio-video object.

syntax

gh_av.decoder_close (
av_id
)

parameters

av_id ID audio-video object identifier

return values

none

code sample

gh_av.decoder_close(av_id)

decoder_open

Opens an audio/video file.

syntax

av_id = gh_av.decoder_open (
filename,
loop_mode
)

parameters

filename STRING audio filename
loop_mode BOOLEAN looping: 1 (true) or 0 (false)

return values

av_id ID audio-video object identifier

code sample

av_id = gh_av.decoder_open(filename, 1)

get_codec_name

Returns the codec names of video and audio streams.

syntax

video_codec, audio_codec = gh_av.get_codec_name (
av_id
)

parameters

av_id ID audio-video object identifier

return values

video_codec, audio_codec STRING codec names

code sample

video_codec, audio_codec = gh_av.get_codec_name(av_id)

get_duration

Duration of the audio-video file.

syntax

duration = gh_av.get_duration (
av_id
)

parameters

av_id ID audio-video object identifier

return values

duration REAL duration in seconds

code sample

duration = gh_av.get_duration(av_id)

get_elapsed_time

Returns the elapsed time since the start of playing.

syntax

elapsed_time = gh_av.get_elapsed_time (
av_id
)

parameters

av_id ID audio-video object identifier

return values

elapsed_time REAL elapsed time in seconds since the start of playing

code sample

elapsed_time = gh_av.get_elapsed_time(av_id)

get_num_frames

Returns the numbers of frames of video and audio streams.

syntax

video_frames, audio_frames = gh_av.get_num_frames (
av_id
)

parameters

av_id ID audio-video object identifier

return values

video_frames, audio_frames INTEGER number of frames

code sample

video_frames, audio_frames = gh_av.get_num_frames(av_id)

get_streams_index

Returns the audio and video stream indices.
Useful to know if an audio video file has an audio or a video stream.

syntax

video_index, audio_index = gh_av.get_streams_index (
av_id
)

parameters

av_id ID audio-video object identifier

return values

video_index, audio_index INTEGER video and audio streams indices: -1 if the stream is not present and >= 0 if the stream is present

code sample

audio, video = gh_av.get_streams_index(av_id)

pause

Pauses an audio-video playback.

syntax

gh_av.pause (
av_id,
state
)

parameters

av_id ID audio-video object identifier
state BOOLEAN pause: 1 (true) or 0 (false)

return values

none

code sample

gh_av.pause(av_id, 1)

process_frame

Process/fetch the current audio-video frame.
You can call this function in a FRAME script if you don't use start_audio_video_processing() / stop_audio_video_processing().

syntax

gh_av.process_frame (
av_id,
process_video,
process_audio
)

parameters

av_id ID audio-video object identifier
process_video BOOLEAN video stream processing: 1 (enabled) or 0 (disabled)
process_audio BOOLEAN audio stream processing: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_av.process_frame(av_id, 1, 1)

reset_streams

Resets the audio-video streams.

syntax

gh_av.reset_streams (
av_id
)

parameters

av_id ID audio-video object identifier

return values

none

code sample

gh_av.reset_streams(av_id)

seek_frame_time

Allow to seek frames in seconds.

syntax

ret = gh_av.seek_frame_time (
av_id,
frame_time_sec
)

parameters

av_id ID audio-video object identifier
frame_time_sec INTEGER frame time in seconds

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

"Seek the frame 20 sec before the end of the video"
frame_time_sec = video_duration_sec - 20
ret = gh_av.seek_frame_time(av_id, frame_time_sec)

set_option_1i

Sets an option.

syntax

gh_av.set_option_1i (
name,
x
)

parameters

name STRING name of the option
x INTEGER value

return values

none

code sample

# Possible options:
# "num_video_threads"
# "num_audio_threads"

gh_av.set_option_1i("num_video_threads", 4)

set_option_str

Sets an option.

syntax

gh_av.set_option_str (
name,
x
)

parameters

name STRING name of the option
x STRING value

return values

none

code sample

# Possible options:
# "hw_device" 
#  - possible values: "cuda"

# "video_pixel_fmt"
#  - possible values: "yuv420p" and "rgb24"

gh_av.set_option_str("hw_device", "cuda")

set_volume

Sets the volume of the audio stream.

syntax

gh_av.set_volume (
av_id,
volume
)

parameters

av_id ID audio-video object identifier
volume REAL volume from 0.0 to 1.0

return values

none

code sample

gh_av.set_volume(av_id, 0.7)

start_audio_video_processing

Starts the audio-video processing thread.

syntax

gh_av.start_audio_video_processing (
av_id,
process_video,
process_audio
)

parameters

av_id ID audio-video object identifier
process_video BOOLEAN video stream processing: 1 (enabled) or 0 (disabled)
process_audio BOOLEAN audio stream processing: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_av.start_audio_video_processing(av_id, 1, 1)

stop_audio_video_processing

Stops the audio-video processing thread.

syntax

gh_av.stop_audio_video_processing (
av_id
)

parameters

av_id ID audio-video object identifier

return values

none

code sample

gh_av.stop_audio_video_processing(av_id)

video_get_resolution

Returns the resolution in pixels of video frames.

syntax

width, height = gh_av.video_get_resolution (
av_id
)

parameters

av_id ID audio-video object identifier

return values

width, height INTEGER resolution

code sample

duration = gh_av.video_get_resolution(av_id)

video_init_texture

(DEPRECATED) Creates a texture based on video parameters.
This texture can be used with all gh_texture functions.

syntax

tex_id = gh_av.video_init_texture (
av_id,
pf
)

parameters

av_id ID audio-video object identifier
pf INTEGER pixel format

return values

tex_id ID texture identifier

code sample

tex_id = gh_av.video_init_texture(av_id, pf) -- DEPRECATED

video_init_texture_rgb24

Creates a texture based on video parameters.
This texture can be used with all gh_texture functions.
The texture has the RGB24 pixel format (same than PF_U8_RGB): 3 bytes per pixel.

syntax

gh_av.video_init_texture_rgb24 (
av_id
)

parameters

av_id ID audio-video object identifier

return values

none

code sample

tex_id = gh_av.video_init_texture_rgb24(av_id)

video_init_texture_yuv420

Creates three textures (Y, U and V) based on video parameters.
These textures can be used with all gh_texture functions.
Each texture has the PF_U8_R pixel format: 1 byte per pixel.

syntax

gh_av.video_init_texture_yuv420 (
av_id,
texY, texU, texV
)

parameters

av_id ID audio-video object identifier
texY, texU, texV ID the three texture identifiers

return values

none

code sample

texY, texU, texV = gh_av.video_init_texture_rgb24(av_id)

video_update_texture

(DEPRECATED) Updates the texture GPU memory with current video frame.

syntax

gh_av.video_update_texture (
av_id,
tex_id
)

parameters

av_id ID audio-video object identifier
tex_id ID texture identifier

return values

none

code sample

gh_av.video_update_texture(av_id, tex_id) -- DEPRECATED

video_update_texture_rgb24

Updates the texture GPU memory with current video frame.
The texture must have the RGB24 pixel format.

syntax

gh_av.video_update_texture_rgb24 (
av_id,
tex_id
)

parameters

av_id ID audio-video object identifier
tex_id ID texture identifier

return values

none

code sample

gh_av.video_update_texture_rgb24(av_id, tex_id)

video_update_texture_yuv420

Updates the three YUV420 textures with current video frame.
Texture must have the PF_U8_R pixel format.

syntax

gh_av.video_update_texture_yuv420 (
av_id,
texY_DUP1,
tuY,
texU,
tuU,
texY_DUP2,
tuV
)

parameters

av_id ID audio-video object identifier
texY_DUP1 ID texture identifier
tuY INTEGER texture unit for texY
texU ID texture identifier
tuU INTEGER texture unit for texU
texY_DUP2 ID texture identifier
tuV INTEGER texture unit for texV

return values

none

code sample

tuY = 0			
tuU = 1			
tuV = 2			
gh_av.video_update_texture_yuv420(av_id, texY, tuY, texU, tuU, texV, tuV)

gh_box2d wip

Box2D Physics module

gh_box2d is the module that manages the Box2D Physics engine.
This module is in WIP state (work in progress) and can change in future versions of GeeXLab.

actor_add_vertices

Adds a vertex to the vertices list of an actor.
This vertices list will be used to build the shape later.

syntax

gh_box2d.actor_add_vertices (
aid,
x, y
)

parameters

aid ID actor identifier
x, y REAL vertex 2D position

return values

none

code sample

b2_triangle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_add_vertices(b2_triangle, -1,-1)
gh_box2d.actor_add_vertices(b2_triangle,  0, 1)
gh_box2d.actor_add_vertices(b2_triangle,  1,-1)
gh_box2d.actor_polygon_build(b2_triangle)

actor_apply_force

Apply a force on an actor at a world point.

syntax

gh_box2d.actor_apply_force (
aid,
force_x, force_y,
point_x, point_y,
wake
)

parameters

aid ID actor identifier
force_x, force_y REAL force in Newtons (N)
point_x, point_y REAL world point
wake INTEGER wake up the actor (1 or 0)

return values

none

code sample

gh_box2d.actor_apply_force(aid, force_x, force_y, point_x, point_y, wake)

actor_apply_force_to_center

Apply a force on the center of mass of an actor.

syntax

gh_box2d.actor_apply_force_to_center (
aid,
force_x, force_y,
wake
)

parameters

aid ID actor identifier
force_x, force_y REAL force in Newtons (N)
wake INTEGER wake up the actor (1 or 0)

return values

none

code sample

gh_box2d.actor_apply_force_to_center(aid, force_x, force_y, wake)

actor_apply_linear_impulse

Apply an impulse on an actor at a world point.

syntax

gh_box2d.actor_apply_linear_impulse (
aid,
impulse_x, impulse_y,
point_x, point_y,
wake
)

parameters

aid ID actor identifier
impulse_x, impulse_y REAL impulse in N-seconds or kg-m/s
point_x, point_y REAL world point
wake INTEGER wake up the actor (1 or 0)

return values

none

code sample

gh_box2d.actor_apply_linear_impulse(aid, impulse_x, impulse_y, point_x, point_y, wake)

actor_apply_linear_impulse_to_center

Apply an impulse on the center of mass of an actor.

syntax

gh_box2d.actor_apply_linear_impulse_to_center (
aid,
impulse_x, impulse_y,
wake
)

parameters

aid ID actor identifier
impulse_x, impulse_y REAL impulse in N-seconds or kg-m/s
wake INTEGER wake up the actor (1 or 0)

return values

none

code sample

gh_box2d.actor_apply_linear_impulse_to_center(aid, impulse_x, impulse_y, wake)

actor_apply_torque

Apply a torque on an actor.

syntax

gh_box2d.actor_apply_torque (
aid,
torque,
wake
)

parameters

aid ID actor identifier
torque REAL torque in N-m
wake INTEGER wake up the actor (1 or 0)

return values

none

code sample

gh_box2d.actor_apply_torque(aid, torque, wake)

actor_apply_transform

Applies the transformation of a Box2D actor to a 3D object.

syntax

gh_box2d.actor_apply_transform (
aid,
object_id
)

parameters

aid ID actor identifier
object_id ID object identifier

return values

none

code sample

gh_box2d.actor_apply_transform(aid, mesh_id)

actor_box_build

Builds a box shaped actor.

syntax

gh_box2d.actor_box_build (
aid
)

parameters

aid ID actor identifier

return values

none

code sample

b2_box = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_box_set_size(b2_box, 2.0, 2.0)
gh_box2d.actor_box_build(b2_box)

actor_box_set_size

Sets the size of a box shaped actor.

syntax

gh_box2d.actor_box_set_size (
aid,
w, h
)

parameters

aid ID actor identifier
w, h REAL width and height

return values

none

code sample

b2_box = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_box_set_size(b2_box, 2.0, 2.0)
gh_box2d.actor_box_build(b2_box)

actor_chain_build

Builds a chain shaped actor from the vertices list initialized with calls to actor_add_vertices().

syntax

gh_box2d.actor_chain_build (
aid
)

parameters

aid ID actor identifier

return values

none

code sample

b2_chain = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_add_vertices(b2_chain, 1, 1)
gh_box2d.actor_add_vertices(b2_chain,  0, -1)
gh_box2d.actor_add_vertices(b2_chain,  -1, -1)
gh_box2d.actor_add_vertices(b2_chain,  -2, 1)
gh_box2d.actor_chain_build(b2_chain)

actor_circle_build

Builds a circle shaped actor.

syntax

gh_box2d.actor_circle_build (
aid
)

parameters

aid ID actor identifier

return values

none

code sample

b2_circle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_circle_set_radius(b2_circle, 2.0, 2.0)
gh_box2d.actor_box_actor_circle_buildbuild(b2_circle)

actor_circle_set_radius

Sets the radius of a circle shaped actor.

syntax

gh_box2d.actor_circle_set_radius (
aid,
r
)

parameters

aid ID actor identifier
r REAL radius

return values

none

code sample

b2_circle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_circle_set_radius(b2_circle, 2.0, 2.0)
gh_box2d.actor_box_actor_circle_buildbuild(b2_circle)

actor_get_contact_actor

Gets the actor ID of a particular contact.

syntax

contact_actor_id, cx, cy = gh_box2d.actor_get_contact_actor (
actor_id,
contact_index
)

parameters

actor_id ID actor identifier
contact_index INTEGER contact index from [0; num_contacts] - call actor_read_contacts() for num_contacts.

return values

contact_actor_id ID ID of the actor in contact
cx, cy REAL position of the contact

code sample

num_contacts, x, y = gh_box2d.actor_read_contacts(actor_id)
for i=0, num_contacts-1 do
  contact_actor_id, cx, cy = gh_box2d.actor_get_contact_actor(actor_id, i)
	...
end

actor_get_transform

Gets the transformation of a Box2D actor.

syntax

x, y, angle = gh_box2d.actor_get_transform (
aid
)

parameters

aid ID actor identifier

return values

x, y REAL actor position
angle REAL actor orientation in radians

code sample

x, y, angle = gh_box2d.actor_get_transform(aid)

actor_is_awake

Gets the awake state of a Box2D actor.

syntax

state = gh_box2d.actor_is_awake (
aid
)

parameters

aid ID actor identifier

return values

state BOOLEAN disabled (0) or enabled (1)

code sample

state = gh_box2d.actor_is_awake(aid)

actor_polygon_build

Builds a polygon shaped actor from the vertices list initialized with calls to actor_add_vertices().

syntax

gh_box2d.actor_polygon_build (
aid,
x, y
)

parameters

aid ID actor identifier
x, y REAL vertex 2D position

return values

none

code sample

b2_triangle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_add_vertices(b2_triangle, -1,-1)
gh_box2d.actor_add_vertices(b2_triangle,  0, 1)
gh_box2d.actor_add_vertices(b2_triangle,  1,-1)
gh_box2d.actor_polygon_build(b2_triangle)

actor_raycast

Casts a ray on an actor and gets the hit point.

syntax

ret, hit_point_x, hit_point_y = gh_box2d.actor_raycast (
aid,
x0, y0,
x1, y1
)

parameters

aid ID actor identifier
x0, y0 REAL ray start
x1, y1 REAL ray end

return values

ret INTEGER 1 if intersection found, 0 otherwise.
hit_point_x, hit_point_y REAL coordinates of the hit point.

code sample

ret, hit_point_x, hit_point_y = gh_box2d.actor_raycast(aid, x0, y0, x1, y1)

actor_read_contacts

Sets the angular velocity of a Box2D actor.

syntax

num_contacts, x, y = gh_box2d.actor_read_contacts (
aid
)

parameters

aid ID actor identifier

return values

num_contacts INTEGER number of contacts
x, y REAL position of the first contact

code sample

num_contacts, x, y = gh_box2d.actor_read_contacts(aid)

actor_set_awake

Sets the awake state of a Box2D actor.

syntax

gh_box2d.actor_set_awake (
aid,
state
)

parameters

aid ID actor identifier
state BOOLEAN disabled (0) or enabled (1)

return values

none

code sample

gh_box2d.actor_set_awake(aid, state)

actor_set_ccd

Sets the CCD (continuous collision detection) state of a Box2D actor.
Useful for fast moving actors like bullets.
Disabled by default.

syntax

gh_box2d.actor_set_ccd (
aid,
state
)

parameters

aid ID actor identifier
state BOOLEAN disabled (0) or enabled (1)

return values

none

code sample

gh_box2d.actor_set_ccd(aid, state)

actor_set_damping

Sets the damping coefficients of a Box2D actor.

syntax

gh_box2d.actor_set_damping (
aid,
linear,
angular
)

parameters

aid ID actor identifier
linear REAL linear damping
angular REAL angular damping

return values

none

code sample

gh_box2d.actor_set_damping(aid, linear, angular)

actor_set_density

Sets the density of an actor.
The mass will be updated.

syntax

gh_box2d.actor_set_density (
aid,
x
)

parameters

aid ID actor identifier
x REAL density

return values

none

code sample

gh_box2d.actor_set_density(aid, x)

actor_set_enabled

Sets the enabled state of a Box2D actor.

syntax

gh_box2d.actor_set_enabled (
aid,
state
)

parameters

aid ID actor identifier
state BOOLEAN disabled (0) or enabled (1)

return values

none

code sample

gh_box2d.actor_set_enabled(aid, state)

actor_set_friction

Sets the friction of an actor.

syntax

gh_box2d.actor_set_friction (
aid,
x
)

parameters

aid ID actor identifier
x REAL friction

return values

none

code sample

gh_box2d.actor_set_friction(aid, x)

actor_set_linear_angular

Sets the angular velocity of a Box2D actor.

syntax

gh_box2d.actor_set_linear_angular (
aid,
x
)

parameters

aid ID actor identifier
x REAL angular velocity

return values

none

code sample

gh_box2d.actor_set_linear_angular(aid, x)

actor_set_linear_velocity

Sets the linear velocity of a Box2D actor.

syntax

gh_box2d.actor_set_linear_velocity (
aid,
x, y
)

parameters

aid ID actor identifier
x, y REAL linear velocity along X and Y axis

return values

none

code sample

gh_box2d.actor_set_linear_velocity(aid, x, y)

actor_set_restitution

Sets the restitution of an actor.

syntax

gh_box2d.actor_set_restitution (
aid,
x
)

parameters

aid ID actor identifier
x REAL restitution

return values

none

code sample

gh_box2d.actor_set_restitution(aid, x)

actor_set_sleeping_allowed

Sets the sleeping allowed state of a Box2D actor.

syntax

gh_box2d.actor_set_sleeping_allowed (
aid,
state
)

parameters

aid ID actor identifier
state BOOLEAN disabled (0) or enabled (1)

return values

none

code sample

gh_box2d.actor_set_sleeping_allowed(aid, state)

actor_set_transform

Sets the transformation of a Box2D actor.

syntax

gh_box2d.actor_set_transform (
aid,
x, y,
angle
)

parameters

aid ID actor identifier
x, y REAL actor position
angle REAL actor orientation in radians

return values

none

code sample

gh_box2d.actor_set_transform(aid, x, y, angle)

get_version

Returns the version of the Box2D engine.

syntax

major, minor, revision = gh_box2d.get_version()

parameters

none

return values

major, minor, revision INTEGER version

code sample

major, minor, revision = gh_box2d.get_version()

init

Initializes the Box2D plugin.
This the first function to call.

syntax

ret = gh_box2d.init()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_box2d.init()

joint_distance_compute_linear_stiffness

Utility function that computes the stiffness and damping of a joint.

syntax

stiffness, damping = gh_box2d.joint_distance_compute_linear_stiffness (
wid,
frequency_hz,
damping_ratio
)

parameters

wid ID world identifier
frequency_hz REAL frequency in Hertz
damping_ratio REAL non-dimensional value, typically between 0 and 1

return values

stiffness, damping REAL stiffness and damping

code sample

frequency_hz = 4.0			
damping_ratio = 0.5
stiffness, damping = gh_box2d.joint_distance_compute_linear_stiffness(jid, frequency_hz, damping_ratio)

joint_distance_set_damping

Sets the damping of a joint.

syntax

gh_box2d.joint_distance_set_damping (
wid,
damping
)

parameters

wid ID world identifier
damping REAL damping value

return values

none

code sample

gh_box2d.joint_distance_set_damping(jid, damping)

joint_distance_set_stiffness

Sets the stiffness of a joint.

syntax

gh_box2d.joint_distance_set_stiffness (
wid,
stiffness
)

parameters

wid ID world identifier
stiffness REAL stiffness value

return values

none

code sample

gh_box2d.joint_distance_set_stiffness(jid, stiffness)

terminate

Terminates the Box2D plugin.
This function should be call in the TERMINATE script.

syntax

ret = gh_box2d.terminate()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_box2d.terminate()

world_clear_forces

Clears all forces of all objects.
Automatically done after each world_step_simulation() unless you disable this feature with world_set_auto_clear_forces().

syntax

gh_box2d.world_clear_forces (
wid
)

parameters

wid ID world identifier

return values

none

code sample

gh_box2d.world_clear_forces(wid)

world_create_actor

Creates a generic actor and adds it to the world.
Its shape (circle, box, polygon, chain) must be defined before calling world_step_simulation().

syntax

aid = gh_box2d.world_create_actor (
wid,
posx, posy,
body_type
)

parameters

wid ID world identifier
posx, posy REAL initial position
body_type STRING body type: static, kinematic or dynamic

return values

aid ID actor identifier

code sample

body_type = "dynamic"			
aid = gh_box2d.world_create_actor(wid, posx, posy, body_type)
gh_box2d.actor_circle_set_radius(aid, 2.0)
gh_box2d.actor_circle_build(aid)

world_create_actor_box

Creates a box actor and adds it to the world.

syntax

aid = gh_box2d.world_create_actor_box (
wid,
posx, posy,
width, height,
body_type,
density,
friction,
restitution
)

parameters

wid ID world identifier
posx, posy REAL initial position
width, height REAL box size
body_type STRING body type: static, kinematic or dynamic
density REAL density - mass will be computed later based on the volume and density.
friction REAL friction
restitution REAL restitution

return values

aid ID actor identifier

code sample

body_type = "dynamic"			
density = 10.0
friction = 0.1
restitution = 0.4
aid = gh_box2d.world_create_actor_box(wid, posx, posy, width, height, body_type, density, friction, restitution)

world_create_actor_circle

Creates a circle (disc?) actor and adds it to the world.

syntax

aid = gh_box2d.world_create_actor_circle (
wid,
posx, posy,
radius,
body_type,
density,
friction,
restitution
)

parameters

wid ID world identifier
posx, posy REAL initial position
radius REAL disc radius
body_type STRING body type: static, kinematic or dynamic
density REAL density - mass will be computed later based on the volume and density.
friction REAL friction
restitution REAL restitution

return values

aid ID actor identifier

code sample

body_type = "dynamic"			
density = 10.0
friction = 0.1
restitution = 0.4
aid = gh_box2d.world_create_actor_circle(wid, posx, posy, radius, body_type, density, friction, restitution)

world_create_joint_distance

Creates a distance joint between two actors (A and B).

syntax

jid = gh_box2d.world_create_joint_distance (
wid,
a,
b,
anchor_a_x, anchor_a_y,
anchor_b_x, anchor_b_y
)

parameters

wid ID world identifier
a ID actor A
b ID actor B
anchor_a_x, anchor_a_y REAL anchor point in actor A
anchor_b_x, anchor_b_y REAL anchor point in actor B

return values

jid ID joint identifier

code sample

jid = gh_box2d.world_create_joint_distance(wid, a, b, anchor_a_x, anchor_a_y, anchor_b_x, anchor_b_y)

world_init

Creates and initializes a physics world.
Every Box2D demo begins with the creation of a world.
A world is the physics hub that manages all Box2D objects.

syntax

wid = gh_box2d.world_init()

parameters

none

return values

wid ID world identifier

code sample

wid = gh_box2d.world_init()

world_kill_actor

Destroys and remove an actor from the world.

syntax

gh_box2d.world_kill_actor (
wid,
aid
)

parameters

wid ID world identifier
aid ID actor identifier

return values

none

code sample

gh_box2d.world_kill_actor(wid, aid)

world_kill_joint

Kills an existing joint.

syntax

gh_box2d.world_kill_joint (
wid,
jid
)

parameters

wid ID world identifier
jid ID joint identifier

return values

none

code sample

gh_box2d.world_kill_joint(wid, jid)

world_set_auto_clear_forces

Set the auto clear forces state.

syntax

gh_box2d.world_set_auto_clear_forces (
wid,
state
)

parameters

wid ID world identifier
state BOOLEAN disables (0) or enabled (1)

return values

none

code sample

state = 0
gh_box2d.world_set_auto_clear_forces(wid, state)

world_set_gravity

Sets the world gravity vector.

syntax

gh_box2d.world_set_gravity (
wid,
x, y
)

parameters

wid ID world identifier
x, y REAL gravity vector

return values

none

code sample

gh_box2d.world_set_gravity(wid, 0, -10)

world_step_simulation

Performs a world simulation step.

syntax

gh_box2d.world_step_simulation (
wid,
time_step,
velocity_iterations,
position_iterations
)

parameters

wid ID world identifier
time_step REAL time step between two frames
velocity_iterations INTEGER number of solver iterations for velocity
position_iterations INTEGER number of solver iterations for position

return values

none

code sample

dt = 1.0/60.0			
velocity_iterations = 8
position_iterations = 4
gh_box2d.world_step_simulation(wid, dt, velocity_iterations, position_iterations)

world_terminate

Terminates and destroys a physics world.

syntax

gh_box2d.world_terminate (
wid
)

parameters

wid ID world identifier

return values

none

code sample

gh_box2d.world_terminate(wid)

gh_bullet3

Bullet Physics module

gh_bullet3 is the module that manages the Bullet Physics engine.

actor_apply_central_force

Applies a force to an actor.

syntax

gh_bullet3.actor_apply_central_force (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL force

return values

none

code sample

gh_bullet3.actor_apply_central_force(actor_id, x, y, z)

actor_apply_central_impulse

Applies an impulse force to an actor.

syntax

gh_bullet3.actor_apply_central_impulse (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL force

return values

none

code sample

gh_bullet3.actor_apply_central_impulse(actor_id, x, y, z)

actor_apply_torque

Applies a torque to an actor.

syntax

gh_bullet3.actor_apply_torque (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL torque

return values

none

code sample

gh_bullet3.actor_apply_torque(actor_id, x, y, z)

actor_apply_transform

Apply the transformation matrix of a physics actor to a 3D object.
It's a manual physcis/graphics synchronization.
Use this function if you don't use scene_sync_3d_objects().

syntax

gh_bullet3.actor_apply_transform (
actor_id,
o3d_id
)

parameters

actor_id ID actor identifier
o3d_id ID 3d object identifier

return values

none

code sample

gh_bullet3.actor_apply_transform(actor_id, o3d_id)

actor_clear_forces

Clears (resets) all forces that act on an actor.

syntax

gh_bullet3.actor_clear_forces (
actor_id
)

parameters

actor_id ID actor identifier

return values

none

code sample

gh_bullet3.actor_clear_forces(actor_id)

actor_create_box

Creates a box actor.

syntax

actor_id = gh_bullet3.actor_create_box (
w, h, d,
x, y, z,
mass,
mat_id
)

parameters

w, h, d REAL dimensions of the box
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_box(w, h, d, x, y, z, mass, mat_id)

actor_create_box_v2

Creates a box actor.

syntax

actor_id = gh_bullet3.actor_create_box_v2 (
w, h, d,
x, y, z,
mass,
ix, iy, iz,
mat_id
)

parameters

w, h, d REAL dimensions of the box
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
ix, iy, iz REAL initial local inertia
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_box_v2(w, h, d, x, y, z, mass, ix, iy, iz, mat_id)

actor_create_cylinder

Creates a cylinder actor.

syntax

actor_id = gh_bullet3.actor_create_cylinder (
main_axis,
height,
radius,
x, y, z,
mass,
mat_id
)

parameters

main_axis ENUM( along_axis ) direction of the main axis: 0 (along X axis), 1 (along Y axis) or 2 (along Z axis)
height REAL cylinder height
radius REAL cylinder radius
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_cylinder(central_axis, height, radius, x, y, z, mass, mat_id)

actor_create_cylinder_v2

Creates a cylinder actor.

syntax

actor_id = gh_bullet3.actor_create_cylinder_v2 (
main_axis,
height,
radius,
x, y, z,
mass,
ix, iy, iz,
mat_id
)

parameters

main_axis ENUM( along_axis ) direction of the main axis: 0 (along X axis), 1 (along Y axis) or 2 (along Z axis)
height REAL cylinder height
radius REAL cylinder radius
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
ix, iy, iz REAL initial local inertia
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_cylinder_v2(central_axis, height, radius, x, y, z, mass, ix, iy, iz, mat_id)

actor_create_mesh

Creates an actor from a mesh.

syntax

actor_id = gh_bullet3.actor_create_mesh (
mesh_id,
convex,
x, y, z,
mass,
mat_id
)

parameters

mesh_id ID mesh identifier
convex BOOLEAN convex mesh: 1 (yes) or 0 (no)
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_mesh(mesh_id, convex, x, y, z, mass, mat_id)

actor_create_mesh_v2

Creates an actor from a mesh.

syntax

actor_id = gh_bullet3.actor_create_mesh_v2 (
mesh_id,
convex,
x, y, z,
mass,
ix, iy, iz,
mat_id
)

parameters

mesh_id ID mesh identifier
convex BOOLEAN convex mesh: 1 (yes) or 0 (no)
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
ix, iy, iz REAL initial local inertia
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_mesh_v2(mesh_id, convex, x, y, z, mass, ix, iy, iz, mat_id)

actor_create_sphere

Creates a sphere actor.

syntax

actor_id = gh_bullet3.actor_create_sphere (
radius,
x, y, z,
mass,
mat_id
)

parameters

radius REAL sphere radius
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_sphere(radius, x, y, z, mass, mat_id)

actor_create_sphere_v2

Creates a sphere actor.

syntax

actor_id = gh_bullet3.actor_create_sphere_v2 (
radius,
x, y, z,
mass,
ix, iy, iz,
mat_id
)

parameters

radius REAL sphere radius
x, y, z REAL initial position of the actor
mass REAL mass (set the mass = 0 for a kinematic actor)
ix, iy, iz REAL initial local inertia
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

actor_id = gh_bullet3.actor_create_sphere_v2(radius, x, y, z, mass, ix, iy, iz, mat_id)

actor_create_static_plane

Creates a static plane actor.
This is an infinite plane defined by a plane equation.

syntax

actor_id = gh_bullet3.actor_create_static_plane (
nx, ny, nz, d,
mat_id
)

parameters

nx, ny, nz, d REAL plane equation
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

nx = 0
ny = 1
nz = 0
d = 0
actor_id = gh_bullet3.actor_create_static_plane(nx, ny, nz, d, mat_id)

actor_create_static_plane_v2

Creates a static plane actor.
This is an infinite plane defined by a plane equation.

syntax

actor_id = gh_bullet3.actor_create_static_plane_v2 (
nx, ny, nz,
px, py, pz,
mat_id
)

parameters

nx, ny, nz REAL plane normal vector
px, py, pz REAL plane position
mat_id ID material identifier

return values

actor_id ID actor identifier

code sample

nx = 1
ny = 0
nz = 0
px = 5
py = 0
pz = 0
actor_id = gh_bullet3.actor_create_static_plane_v2(nx, ny, nz, px, py, pz, mat_id)

actor_get_activation_state

Gets the activation state of an actor.

syntax

state = gh_bullet3.actor_get_activation_state (
actor_id
)

parameters

actor_id ID actor identifier

return values

state INTEGER activation state (0 or 1)

code sample

state = gh_bullet3.actor_get_activation_state(actor_id)

actor_get_angular_speed2

Gets the squared angular speed of an actor.

syntax

s = gh_bullet3.actor_get_angular_speed2 (
actor_id
)

parameters

actor_id ID actor identifier

return values

s REAL squared speed

code sample

s = gh_bullet3.actor_get_angular_speed2(actor_id)

actor_get_angular_velocity

Gets the angular velocity of an actor.

syntax

x, y, z = gh_bullet3.actor_get_angular_velocity (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z= gh_bullet3.actor_get_angular_velocity(actor_id)

actor_get_contact_actor

Gets the actor ID of a particular contact.

syntax

contact_actor_id = gh_bullet3.actor_get_contact_actor (
actor_id,
contact_index
)

parameters

actor_id ID actor identifier
contact_index INTEGER contact index

return values

contact_actor_id ID ID of the actor in contact

code sample

num_contacts, x, y, z = gh_bullet3.actor_get_contact_info(actor_id)
for i=0, num_contacts-1 do
  contact_actor_id = gh_bullet3.actor_get_contact_actor(actor_id, i)
	...
end

actor_get_contact_info

Gets information about contacts of an actor.

syntax

num_contacts = gh_bullet3.actor_get_contact_info (
actor_id,
px, py, pz
)

parameters

actor_id ID actor identifier
px, py, pz REAL position of the first contact

return values

num_contacts INTEGER number of contacts

code sample

num_contacts, px, py, pz = gh_bullet3.actor_get_contact_info(actor_id)

actor_get_linear_speed2

Gets the squared linear speed of an actor.

syntax

s = gh_bullet3.actor_get_linear_speed2 (
actor_id
)

parameters

actor_id ID actor identifier

return values

s REAL squared speed

code sample

s = gh_bullet3.actor_get_linear_speed2(actor_id)

actor_get_linear_velocity

Gets the linear velocity of an actor.

syntax

x, y, z = gh_bullet3.actor_get_linear_velocity (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z= gh_bullet3.actor_get_linear_velocity(actor_id)

actor_get_orientation

Gets the orientation of an actor.

syntax

qx, qy, qz, qw = gh_bullet3.actor_get_orientation (
actor_id
)

parameters

actor_id ID actor identifier

return values

qx, qy, qz, qw REAL orientation quaternion

code sample

qx, qy, qz, qw = gh_bullet3.actor_get_orientation(actor_id)

actor_get_position

Gets the position of an actor.

syntax

x, y, z = gh_bullet3.actor_get_position (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL 3D position

code sample

x, y, z = gh_bullet3.actor_get_position(actor_id)

actor_get_transform_mat16

Returns the transformation matrix of a physics actor.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_bullet3.actor_get_transform_mat16 (
actor_id
)

parameters

actor_id ID actor identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_bullet3.actor_get_transform_mat16(actor_id)

actor_get_transform_pos_qrot

Returns the position and orientation (quaternion) of a physics actor.

syntax

px, py, pz, qx, qy, qz, qw = gh_bullet3.actor_get_transform_pos_qrot (
actor_id
)

parameters

actor_id ID actor identifier

return values

px, py, pz REAL position
qx, qy, qz, qw REAL rotation quaternion

code sample

px, py, pz, qx, qy, qz, qw = gh_bullet3.actor_get_transform_pos_qrot(actor_id)

actor_kill

Destroys an actor.

syntax

gh_bullet3.actor_kill (
actor_id
)

parameters

actor_id ID actor identifier

return values

none

code sample

gh_bullet3.actor_kill(actor_id)

actor_set_3d_object

Allows to associate a physics actor and a 3D object.
Useful for the scene_sync_3d_objects() function.

syntax

gh_bullet3.actor_set_3d_object (
actor_id,
o3d_id
)

parameters

actor_id ID actor identifier
o3d_id ID 3d object identifier

return values

none

code sample

gh_bullet3.actor_set_3d_object(actor_id, o3d_id)

actor_set_activation_state

Sets the activation state of an actor.

syntax

gh_bullet3.actor_set_activation_state (
actor_id,
state
)

parameters

actor_id ID actor identifier
state INTEGER activation state (0 or 1)

return values

none

code sample

gh_bullet3.actor_set_activation_state(actor_id, state)

actor_set_angular_factor

Allows to limit (or amplify) the angular velocity along some axis.

syntax

gh_bullet3.actor_set_angular_factor (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL XX factor

return values

none

code sample

gh_bullet3.actor_set_angular_factor(actor_id, x, y, z)

actor_set_angular_velocity

Sets the angular velocity of an actor.

syntax

gh_bullet3.actor_set_angular_velocity (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL velocity vector

return values

none

code sample

gh_bullet3.actor_set_angular_velocity(actor_id, x, y, z)

actor_set_ccd_params

Sets the CCD (continuous collision detection) parameters.
Useful to improve simulation stability.

syntax

gh_bullet3.actor_set_ccd_params (
actor_id,
motion_threshold,
swept_sphere_radius
)

parameters

actor_id ID actor identifier
motion_threshold REAL CCD is not performed if the motion (in one step) is less then motion_threshold
swept_sphere_radius REAL swept sphere radius (0.0 by default)

return values

none

code sample

gh_bullet3.actor_set_ccd_params(actor_id, motion_threshold, swept_sphere_radius)

actor_set_collision_margin

Sets the collision margin of an actor.
Useful to improve simulation stability.

syntax

gh_bullet3.actor_set_collision_margin (
actor_id,
margin
)

parameters

actor_id ID actor identifier
margin REAL collision margin

return values

none

code sample

gh_bullet3.actor_set_collision_margin(actor_id, margin)

actor_set_damping

Sets damping factors.

syntax

gh_bullet3.actor_set_damping (
actor_id,
linear,
angular
)

parameters

actor_id ID actor identifier
linear REAL linear damping
angular REAL angular damping

return values

none

code sample

gh_bullet3.actor_set_damping(actor_id, linear, angular)

actor_set_gravity

Sets a gravity vector for an actor.

syntax

gh_bullet3.actor_set_gravity (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL gravity vector

return values

none

code sample

gh_bullet3.actor_set_gravity(actor_id, x, y, z)

actor_set_linear_factor

Allows to limit (or amplify) the linear velocity along some axis.

syntax

gh_bullet3.actor_set_linear_factor (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL XX factor

return values

none

code sample

gh_bullet3.actor_set_linear_factor(actor_id, x, y, z)

actor_set_linear_velocity

Sets the linear velocity of an actor.

syntax

gh_bullet3.actor_set_linear_velocity (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL velocity vector

return values

none

code sample

gh_bullet3.actor_set_linear_velocity(actor_id, x, y, z)

actor_set_material

Updates an actor's material.

syntax

gh_bullet3.actor_set_material (
actor_id,
mat_id
)

parameters

actor_id ID actor identifier
mat_id ID material identifier

return values

none

code sample

gh_bullet3.actor_set_material(actor_id, mid)

actor_set_orientation

Sets the orientation of an actor.

syntax

gh_bullet3.actor_set_orientation (
actor_id,
qx, qy, qz, qw
)

parameters

actor_id ID actor identifier
qx, qy, qz, qw REAL orientation quaternion

return values

none

code sample

gh_bullet3.actor_set_orientation(actor_id, qx, qy, qz, qw)

actor_set_position

Sets the position of an actor.

syntax

gh_bullet3.actor_set_position (
actor_id,
x, y, z
)

parameters

actor_id ID actor identifier
x, y, z REAL 3d position

return values

none

code sample

gh_bullet3.actor_set_position(actor_id, x, y, z)

actor_set_sleeping_thresholds

Sets the linear and angular sleeping thresholds.

syntax

gh_bullet3.actor_set_sleeping_thresholds (
actor_id,
linear,
angular
)

parameters

actor_id ID actor identifier
linear REAL linear sleeping threshold
angular REAL angular sleeping threshold

return values

none

code sample

gh_bullet3.actor_set_sleeping_thresholds(actor_id, linear, angular)

actor_update_mass

Updates the mass of an actor.

syntax

gh_bullet3.actor_update_mass (
actor_id,
mass
)

parameters

actor_id ID actor identifier
mass REAL mass

return values

none

code sample

gh_bullet3.actor_update_mass(actor_id, mass)

get_version

Gets the Bullet API version as a single integer (ex: 288).

syntax

version = gh_bullet3.get_version()

parameters

none

return values

version INTEGER API version

code sample

version = gh_bullet3.get_version()

init

Initializes the Bullet3 plugin.
This the first function to call.

syntax

ret = gh_bullet3.init()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_bullet3.init()

material_create

Creates a new material.

syntax

mat_id = gh_bullet3.material_create (
restitution,
friction
)

parameters

restitution REAL restitution factor
friction REAL friction factor

return values

mat_id ID material identifier

code sample

mat_id = gh_bullet3.material_create(restitution, friction)

material_kill

Destroys a material.

syntax

gh_bullet3.material_kill (
mat_id
)

parameters

mat_id ID material identifier

return values

none

code sample

gh_bullet3.material_kill(mat_id)

material_update

Updates the properties of a material.

syntax

gh_bullet3.material_update (
mat_id,
friction,
restitution
)

parameters

mat_id ID material identifier
friction REAL friction
restitution REAL resilience / restitution

return values

none

code sample

restitution = 0.9
friction = 0.5

gh_bullet3.material_update(mat_id, restitution, friction)

-- now update the material for a particular actor
gh_bullet3.actor_set_material(actor_id, mat_id)

scene_add_actor

Adds a physics actor to a physics scene.

syntax

gh_bullet3.scene_add_actor (
scene_id,
actor_id
)

parameters

scene_id ID scene identifier
actor_id ID actor identifier

return values

none

code sample

gh_bullet3.scene_add_actor(scene_id, actor_id)

scene_check_contacts

Checks all contacts in a scene.

syntax

num_contacts = gh_bullet3.scene_check_contacts (
scene_id
)

parameters

scene_id ID scene identifier

return values

num_contacts INTEGER number of contacts

code sample

num_contacts = gh_bullet3.scene_check_contacts(scene_id)

scene_create

Creates and initializes a physics scene (Bullet Dbvt broadphase).

syntax

scene_id = gh_bullet3.scene_create()

parameters

none

return values

scene_id ID scene identifier

code sample

scene_id = gh_bullet3.scene_create()

scene_create_sap

Creates and initializes a physics scene (Bullet AxisSweep3 broadphase).
For this scene, you have to specify the expected scene dimensions.

syntax

scene_id = gh_bullet3.scene_create_sap (
min_x, min_y, min_z,
max_x, max_y, max_z
)

parameters

min_x, min_y, min_z REAL world dimensions (minimal AABB values)
max_x, max_y, max_z REAL world dimensions (maximal AABB values)

return values

scene_id ID scene identifier

code sample

scene_id = gh_bullet3.scene_create_sap(x0, y0, z0,  x1, x1, z1)

scene_kill

Terminates and destroys a physics scene.

syntax

gh_bullet3.scene_kill (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_bullet3.scene_kill(scene_id)

scene_remove_actor

Removes a physics actor from a physics scene.

syntax

gh_bullet3.scene_remove_actor (
scene_id,
actor_id
)

parameters

scene_id ID scene identifier
actor_id ID actor identifier

return values

none

code sample

gh_bullet3.scene_remove_actor(scene_id, actor_id)

scene_reset_all_contacts

Resets all contacts in a scene.
Should be called before scene_step_simulation().

syntax

gh_bullet3.scene_reset_all_contacts (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_bullet3.scene_reset_all_contacts(scene_id)

scene_set_gravity

Sets the global gravity of the scene (ex: [0.0, -10.0, 0.0])

syntax

gh_bullet3.scene_set_gravity (
scene_id,
x, y, z
)

parameters

scene_id ID scene identifier
x, y, z REAL gravity vector

return values

none

code sample

gh_bullet3.scene_set_gravity(scene_id, x, y, z)

scene_set_solver_num_iterations

Sets the number of iterations of the solver.
The simulation stability increases with the number of iterations but the simulation is slower.

syntax

gh_bullet3.scene_set_solver_num_iterations (
scene_id,
num_iterations
)

parameters

scene_id ID scene identifier
num_iterations INTEGER number of iterations - default value is 10.

return values

none

code sample

gh_bullet3.scene_set_solver_num_iterations(scene_id, iterations)

scene_step_simulation

Performs a scene simulation step.
The relation between the parameters should follow this rule: timeStep < maxSubSteps * fixedTimeStep

syntax

gh_bullet3.scene_step_simulation (
scene_id,
time_step,
max_sub_steps,
fixed_time_step
)

parameters

scene_id ID scene identifier
time_step REAL time step between two frames
max_sub_steps INTEGER number of sub steps
fixed_time_step REAL fixed time step - default value: 1.0/60.0

return values

none

code sample

gh_bullet3.scene_step_simulation(scene_id, dt, max_sub_steps, 1.0/60.0)

scene_sync_3d_objects

Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.

syntax

gh_bullet3.scene_sync_3d_objects (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_bullet3.scene_sync_3d_objects(scene_id)

terminate

Stops the Bullet engine and frees resources.

syntax

ret = gh_bullet3.terminate()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_bullet3.terminate()

gh_camera

Camera module

gh_camera is the module that manages cameras: creation, destruction, setting the parameters (position, filed of view, etc.).

bind

Bind the camera to the renderer: the viewport and projection/view matrices are applied.
This function is useful in conjunction with the gh_object.render() function.

syntax

gh_camera.bind (
cam_id
)

parameters

cam_id ID camera identifier

return values

none

code sample

gh_camera.bind(camera)

bind_v2

Bind the camera to the renderer: the viewport and projection/view matrices are applied.
This function is useful in conjunction with the gh_object.render() function.

syntax

gh_camera.bind_v2 (
cam_id,
update_viewport,
update_scissor,
update_proj_mat,
update_view_mat,
update_fixed_pipeline
)

parameters

cam_id ID camera identifier
update_viewport BOOLEAN updates the viewport: 1 (true) or 0 (false)
update_scissor BOOLEAN updates the scissor rectangle (same size than the viewport): 1 (true) or 0 (false)
update_proj_mat BOOLEAN updates the projection matrix: 1 (true) or 0 (false)
update_view_mat BOOLEAN updates the view matrix: 1 (true) or 0 (false)
update_fixed_pipeline BOOLEAN updates the fixed pipeline (so you will have access to gl_ModelViewProjectionMatrix in a vertex shader for example): 1 (true) or 0 (false)

return values

none

code sample

local update_viewport = 1
local update_scissor = 0
local update_proj_mat = 1
local update_view_mat = 1
local update_fixed_pipeline = 0

gh_camera.bind_v2(cam_id, update_viewport, update_scissor, update_proj_mat, update_view_mat, update_fixed_pipeline)

create_ortho

Creates an orthographic camera.

syntax

cam_id = gh_camera.create_ortho (
left,
right,
bottom,
top,
znear,
zfar
)

parameters

left REAL left clipping plane
right REAL right clipping plane
bottom REAL bottom clipping plane
top REAL top clipping plane
znear REAL near clipping plane
zfar REAL far clipping plane

return values

cam_id ID camera identifier

code sample

w = screen_width
h = screen_height
cam_id = gh_camera.create_ortho(-w/2, w/2, -h/2, h/2, -1.0, 1.0)

create_orthographic

Creates an orthographic camera with default values: left, right, top, bottom are derived from the window size.

syntax

cam_id = gh_camera.create_orthographic()

parameters

none

return values

cam_id ID camera identifier

code sample

cam_id = gh_camera.create_orthographic()

create_persp

Creates a perspective camera.

syntax

cam_id = gh_camera.create_persp (
fov,
aspect,
znear,
zfar
)

parameters

fov REAL field of view in degres
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

cam_id ID camera identifier

code sample

cam_id = gh_camera.create_persp(60, 1.333, 0.1, 1000.0)

create_persp_v2

Creates a perspective camera.

syntax

cam_id = gh_camera.create_persp_v2 (
fov,
is_vertical_fov,
aspect,
znear,
zfar
)

parameters

fov REAL field of view in degres
is_vertical_fov BOOLEAN 1 (vertical fov) or 0 (horizontal fov)
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

cam_id ID camera identifier

code sample

cam_id = gh_camera.create_persp_v2(60, 1, 1.333, 0.1, 1000.0)

create_persp_v3

Creates a perspective camera.

syntax

cam_id = gh_camera.create_persp_v3 (
fov_x,
fov_y,
aspect,
znear,
zfar
)

parameters

fov_x REAL horizontal field of view in degres
fov_y REAL vertical field of view in degres
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

cam_id ID camera identifier

code sample

cam_id = gh_camera.create_persp_v3(60, 70, 1.333, 0.1, 1000.0)

create_perspective

Creates a perspective camera with default values (fov=60, znear=1, zfar=1000, aspect=win_width/win_height).

syntax

cam_id = gh_camera.create_perspective (
pos_x, pos_y, pos_z,
lookat_x, lookat_y, lookat_z
)

parameters

pos_x, pos_y, pos_z REAL position of the camera
lookat_x, lookat_y, lookat_z REAL look at point of the camera

return values

cam_id ID camera identifier

code sample

cam_id = gh_camera.create_perspective(0, 20, 0, 0, 0, 0)

create_perspective_vk

Creates a perspective camera for Vulkan demos.

syntax

cam_id = gh_camera.create_perspective_vk (
fov,
aspect,
znear,
zfar
)

parameters

fov REAL field of view in degres
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

cam_id ID camera identifier

code sample

cam_id = gh_camera.create_perspective_vk(60.0, winW/winH, 1.0, 1000.0)

frustum_check_object_aa_box

Checks the collision between the camera frustum and the aligned bounding box of an object.

syntax

collision = gh_camera.frustum_check_object_aa_box (
cam_id,
obj_id
)

parameters

cam_id ID camera identifier
obj_id ID object identifier

return values

collision BOOLEAN collision: 1 (true) or 0 (false)

code sample

collision = gh_camera.frustum_check_object_aa_box(cam_id, obj_id)

frustum_check_object_sphere

Checks the collision between the camera frustum and the bounding sphere of an object.

syntax

collision = gh_camera.frustum_check_object_sphere (
cam_id,
obj_id
)

parameters

cam_id ID camera identifier
obj_id ID object identifier

return values

collision BOOLEAN collision: 1 (true) or 0 (false)

code sample

collision = gh_camera.frustum_check_object_sphere(cam_id, obj_id)

frustum_check_point

Checks the collision between the camera frustum and a point.

syntax

collision = gh_camera.frustum_check_point (
cam_id,
x, y, z
)

parameters

cam_id ID camera identifier
x, y, z REAL position of the point

return values

collision BOOLEAN collision: 1 (true) or 0 (false)

code sample

collision = gh_camera.frustum_check_point(cam_id, x, y, z)

frustum_check_sphere

Checks the collision between the camera frustum and a sphere.

syntax

collision = gh_camera.frustum_check_sphere (
cam_id,
x, y, z
)

parameters

cam_id ID camera identifier
x, y, z REAL position of the sphere center

return values

collision BOOLEAN collision: 1 (true) or 0 (false)

code sample

collision = gh_camera.frustum_check_sphere(cam_id, radius, x, y, z)

frustum_update

Updates the frustum volume of the camera.
The frustum needs to be updated as soon as the camera view matrix has changed (position or orientation).
Once the frustumn is updated, you can perform collision checks (frustum_check_sphere for example).

syntax

gh_camera.frustum_update (
cam_id
)

parameters

cam_id ID camera identifier

return values

none

code sample

gh_camera.frustum_update(cam_id)

get_euler_angles

Gets the Euler's angles.

syntax

pitch, yaw, roll = gh_camera.get_euler_angles (
cam_id
)

parameters

cam_id ID camera identifier

return values

pitch, yaw, roll REAL Euler's angles in degrees

code sample

pitch, yaw, roll = gh_camera.get_euler_angles(cam_id)

get_fov

Gets the camera field of view (fov).

syntax

fov = gh_camera.get_fov (
cam_id
)

parameters

cam_id ID camera identifier

return values

fov REAL vertical field of view in degrees

code sample

fov = gh_camera.get_fov(cam_id)

get_position

Gets the camera position.

syntax

x, y, z = gh_camera.get_position (
cam_id
)

parameters

cam_id ID camera identifier

return values

x, y, z REAL position

code sample

x, y, z = gh_camera.get_position(cam_id)

get_projection_matrix

Gets the camera projection matrix.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix (
cam_id
)

parameters

cam_id ID camera identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix(cam_id)

get_projection_matrix_4x4

Gets the camera projection matrix.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix_4x4 (
cam_id
)

parameters

cam_id ID camera identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_projection_matrix_4x4(cam_id)

get_up_vector

Gets the camera up vector (y axis).

syntax

x, y, z = gh_camera.get_up_vector (
cam_id
)

parameters

cam_id ID camera identifier

return values

x, y, z REAL up vector

code sample

x, y, z = gh_camera.get_up_vector(cam_id)

get_view

Gets the camera direction (z axis or view vector).

syntax

x, y, z = gh_camera.get_view (
cam_id
)

parameters

cam_id ID camera identifier

return values

x, y, z REAL view vector

code sample

x, y, z = gh_camera.get_view(cam_id)

get_view_matrix

Gets the camera view matrix.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_view_matrix (
cam_id
)

parameters

cam_id ID camera identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_camera.get_view_matrix(cam_id)

get_view_quaternion

Gets the camera view quaternion.

syntax

x, y, z, w = gh_camera.get_view_quaternion (
cam_id
)

parameters

cam_id ID camera identifier

return values

x, y, z, w REAL view quaternion

code sample

x, y, z, w = gh_camera.get_view_quaternion(cam_id)

load_gl2_matrix

Loads matrices in the OpenGL 2 fixed pipeline.

syntax

gh_camera.load_gl2_matrix (
cam_id,
load_proj_mat,
load_view_mat,
object_id
)

parameters

cam_id ID camera identifier
load_proj_mat BOOLEAN load the projection matrix (0 or 1)
load_view_mat BOOLEAN load the view matrix (0 or 1)
object_id ID object identifier

return values

none

code sample

load_proj_mat = 1			
load_view_mat = 1
gh_camera.load_gl2_matrix(cam_id, load_proj_mat, load_view_mat, object_id)

reset_reflection_matrix

Resets the reflection matrix initialized by set_reflection_matrix_v1() or set_reflection_matrix_v2().
The reflection matrix is used in scenes where reflection effect (mirror) is required.
When reflection rendering is done, you have to reset the reflection matrix.

syntax

gh_camera.reset_reflection_matrix (
cam_id
)

parameters

cam_id ID camera identifier

return values

none

code sample

gh_camera.reset_reflection_matrix(cam_id)

set_fov

Sets the camera field of view (fov).

syntax

gh_camera.set_fov (
cam_id,
fov
)

parameters

cam_id ID camera identifier
fov REAL vertical field of view in degrees

return values

none

code sample

gh_camera.set_fov(cam_id, 90)

set_lookat

Sets the camera look at point (what point in space the camera is looking).

syntax

gh_camera.set_lookat (
cam_id,
x, y, z,
lookat_mode
)

parameters

cam_id ID camera identifier
x, y, z REAL the target
lookat_mode REAL 1: the target is a point (3D position) or 0: the target is a direction (3D vector)

return values

none

code sample

-- Look at the center of the scene:
gh_camera.set_lookat(cam_id, 0, 0, 0, 1)

set_orientation_cubemap

Sets the camera orientation according to a cubemap face.

syntax

gh_camera.set_orientation_cubemap (
cam_id,
face
)

parameters

cam_id ID camera identifier
face INTEGER cubemap face (0 to 5)

return values

none

code sample

for face = 0, 5 do
    gh_camera.set_orientation_cubemap(cam_id, face)
    ...
end

set_pitch

Sets the camera pitch angle (x axis).

syntax

gh_camera.set_pitch (
cam_id,
pitch
)

parameters

cam_id ID camera identifier
pitch REAL pitch in degrees

return values

none

code sample

gh_camera.set_pitch(cam_id, pitch)

set_position

Sets the camera position.

syntax

gh_camera.set_position (
cam_id,
x, y, z
)

parameters

cam_id ID camera identifier
x, y, z REAL 3D position of the camera

return values

none

code sample

gh_camera.set_position(cam_id, 0, 10, 20)

set_projection_matrix

Sets the camera projection matrix.

syntax

gh_camera.set_projection_matrix (
cam_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

cam_id ID camera identifier
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

return values

none

code sample

gh_camera.set_projection_matrix(cam_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

set_reflection_matrix_v1

Sets / initializes the reflection matrix.
The reflection matrix is used in scenes where reflection effect (mirror) is required.
When reflection rendering is done, you have to reset the reflection matrix with reset_reflection_matrix().

syntax

gh_camera.set_reflection_matrix_v1 (
cam_id,
px, py, pz,
nx, ny, nz,
y
)

parameters

cam_id ID camera identifier
px, py, pz REAL mirror plane position
nx, ny, nz REAL mirror plane normal
y REAL y offset - default: 0

return values

none

code sample

gh_camera.set_reflection_matrix_v1(cam_id, 0, 10, 0, 0, 0, 1)

set_reflection_matrix_v2

Sets / initializes the reflection matrix.
The reflection matrix is used in scenes where reflection effect (mirror) is required.
When reflection rendering is done, you have to reset the reflection matrix with reset_reflection_matrix().

syntax

gh_camera.set_reflection_matrix_v2 (
cam_id,
a, b, c, d
)

parameters

cam_id ID camera identifier
a, b, c, d REAL mirror plane equation

return values

none

code sample

a, b, c, d = gh_object.get_plane_equation(mirror_plane)

gh_camera.set_reflection_matrix_v2(cam_id, a, b, c, d)

set_reflection_matrix_v3

Sets / initializes the reflection matrix.
The reflection matrix is used in scenes where reflection effect (mirror) is required.
When reflection rendering is done, you have to reset the reflection matrix with reset_reflection_matrix().

syntax

gh_camera.set_reflection_matrix_v3 (
cam_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

cam_id ID camera identifier
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

return values

none

code sample

gh_camera.set_reflection_matrix_v3(cam_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

set_roll

Sets the camera roll angle (z axis).

syntax

gh_camera.set_roll (
cam_id,
roll
)

parameters

cam_id ID camera identifier
roll REAL roll in degrees

return values

none

code sample

gh_camera.set_roll(cam_id, roll)

set_up_vec

Sets the camera up vector.

syntax

gh_camera.set_up_vec (
cam_id,
x, y, z
)

parameters

cam_id ID camera identifier
x, y, z REAL direction of the up vector

return values

none

code sample

-- The up vector is the unit Y axis.
gh_camera.set_up_vec(cam_id, 0, 1, 0)

set_view_matrix

Sets the camera view matrix.

syntax

gh_camera.set_view_matrix (
cam_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

cam_id ID camera identifier
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

return values

none

code sample

gh_camera.set_view_matrix(cam_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

set_viewport

Sets the camera viewport.

syntax

gh_camera.set_viewport (
cam_id,
x,
y,
width,
height
)

parameters

cam_id ID camera identifier
x INTEGER x offset - default: 0
y INTEGER y offset - default: 0
width INTEGER width of the viewport
height INTEGER height of the viewport

return values

none

code sample

gh_camera.set_viewport(cam_id, 0, 0, screen_width, screen_height)

set_yaw

Sets the camera yaw angle (y axis).

syntax

gh_camera.set_yaw (
cam_id,
yaw
)

parameters

cam_id ID camera identifier
yaw REAL yaw in degrees

return values

none

code sample

gh_camera.set_yaw(cam_id, yaw)

update_ortho

Updates an orthographic camera.

syntax

gh_camera.update_ortho (
cam_id,
left,
right,
bottom,
top,
znear,
zfar
)

parameters

cam_id ID camera identifier
left REAL left clipping plane
right REAL right clipping plane
bottom REAL bottom clipping plane
top REAL top clipping plane
znear REAL near clipping plane
zfar REAL far clipping plane

return values

none

code sample

w = screen_width
h = screen_height

gh_camera.update_ortho(cam_id, -w/2, w/2, -h/2, h/2, 1.0, -1.0)

update_persp

Updates a perspective camera.

syntax

gh_camera.update_persp (
cam_id,
fov,
aspect,
znear,
zfar
)

parameters

cam_id ID camera identifier
fov REAL field of view in degres
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

none

code sample

gh_camera.update_persp(cam_id, 60, 1.333, 0.1, 1000.0)

update_persp_v2

Updates a perspective camera.

syntax

gh_camera.update_persp_v2 (
cam_id,
fov,
is_vertical_fov,
aspect,
znear,
zfar
)

parameters

cam_id ID camera identifier
fov REAL field of view in degres
is_vertical_fov BOOLEAN 1 (vertical fov) or 0 (horizontal fov)
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

none

code sample

local is_vertical_fov = 1
gh_camera.update_persp_v2(cam_id, 60, is_vertical_fov, 1.333, 0.1, 1000.0)

update_perspective_vk

Updates a perspective camera for Vulkan demos.

syntax

gh_camera.update_perspective_vk (
cam_id,
fov,
aspect,
znear,
zfar
)

parameters

cam_id ID camera identifier
fov REAL field of view in degres
aspect REAL aspect ratio (usually screen_width / screen_height)
znear REAL near clipping plane
zfar REAL far clipping plane

return values

none

code sample

gh_camera.update_perspective_vk(cam_id, 60.0, winW/winH, 1.0, 1000.0)

gh_cuda nvidia

NVIDIA CUDA module

gh_cuda is the module that manages CUDA functions.
Currently CUDA functions only covers the API level support of CUDA-capable devices.

device_get_attribute_1i

Returns the value of an attribute of a CUDA device.

syntax

x = gh_cuda.device_get_attribute_1i (
dev_index,
attr_name
)

parameters

dev_index INTEGER device index
attr_name ENUM( cuda_1i ) attribute name

return values

x INTEGER attribute value

code sample

--[[
"simd_width"
"mem_pitch"
"registers_per_block"
"texture_align"
"core_clock_rate"
"mem_clock_rate"
"mem_bus_width"
"mem_bandwidth_gbs"
"pci_bus_id"
"l2_cache_size"
"async_count"
"total_constant_memory"
"shared_mem_per_block"
"max_shared_mem_per_sm"
"max_threads_per_block"
"max_threads_per_sm"
"warp_size"
"multiprocessor_count"
"cuda_cores_per_sm"
"cuda_cores"
--]]

attribute = "multiprocessor_count"
x = gh_cuda.device_get_attribute_1i(0, attribute)

device_get_attribute_2i

Returns the value of an attribute of a CUDA device.

syntax

x, y = gh_cuda.device_get_attribute_2i (
dev_index,
attr_name
)

parameters

dev_index INTEGER device index
attr_name ENUM( cuda_2i ) attribute name

return values

x, y INTEGER attribute value

code sample

attribute = "compute_capability"
x, y = gh_cuda.device_get_attribute_2i(0, attribute)

device_get_attribute_3i

Returns the value of an attribute of a CUDA device.

syntax

x, y, z = gh_cuda.device_get_attribute_3i (
dev_index,
attr_name
)

parameters

dev_index INTEGER device index
attr_name ENUM( cuda_3i ) attribute name

return values

x, y, z INTEGER attribute value

code sample

-- "max_threads_dim"
-- "max_grid_size"
-- "max_block_dim"

attribute = "max_threads_dim"
x, y, z = gh_cuda.device_get_attribute_3i(0, attribute)

device_get_name

Returns the name of a CUDA device.

syntax

dev_name = gh_cuda.device_get_name (
dev_index
)

parameters

dev_index INTEGER device index

return values

dev_name STRING name the CUDA device

code sample

name = gh_cuda.device_get_name(0)

device_get_pci_bus_id_string

Returns the PCI bus ID string of a CUDA device.

syntax

pci_bus_id_str = gh_cuda.device_get_pci_bus_id_string (
dev_index
)

parameters

dev_index INTEGER device index

return values

pci_bus_id_str STRING PCI bus ID string

code sample

pci_bus_id_str = gh_cuda.device_get_pci_bus_id_string(0)

device_get_total_memory

Returns the total amount of memory of a CUDA device.

syntax

total_memory = gh_cuda.device_get_total_memory (
dev_index
)

parameters

dev_index INTEGER device index

return values

total_memory INTEGER memory amount in bytes

code sample

total_memory = gh_cuda.device_get_total_memory(0)

get_driver_version

Returns the version of CUDA supported by the graphics driver.

syntax

version = gh_cuda.get_driver_version()

parameters

none

return values

version INTEGER version

code sample

version = gh_cuda.get_driver_version()

get_num_devices

Returns the number of CUDA devices available.

syntax

num_devices = gh_cuda.get_num_devices()

parameters

none

return values

num_devices INTEGER number of CUDA devices

code sample

num_devices = gh_cuda.get_num_devices()

sm_version_to_num_cores

Utility function that returns the number of cores per SM (CUDA multiprocessor) from a CUDA compute capability.

syntax

num_cores_per_sm = gh_cuda.sm_version_to_num_cores (
cc_major,
cc_minor
)

parameters

cc_major INTEGER major version of compute capability
cc_minor INTEGER minor version of compute capability

return values

num_cores_per_sm INTEGER number of cores per SM

code sample

num_cores_per_sm = gh_cuda.sm_version_to_num_cores(6, 0)

gh_flex windowsnvidia

NVIDIA FleX module

gh_flex is the module that manages NVIDIA FleX engine.
Flex is a GPU-based particle simulation library designed for real-time applications.
It provides a unified interface that is capable of simulating fluids, clothing, solids, ropes, and more.
The FleX module requires a CUDA-capable GPU and is currently available on Windows only (the FleX plugin is also available on Linux but the plugin is not stable and then is not shipped yet with GeeXLab).

get_compute_device_name

Gets the name of the current FleX GPU.

syntax

dev_name = gh_flex.get_compute_device_name()

parameters

none

return values

dev_name STRING device name

code sample

gpu = gh_flex.get_compute_device_name()

get_version

Gets the version of FleX.

syntax

v = gh_flex.get_version()

parameters

none

return values

v INTEGER version

code sample

v = gh_flex.get_version()

make_phase

Generates a phase for a particle.
A phase is a bit-vector that defines the behavior of a particle.

syntax

gh_flex.make_phase (
group,
particle_flags,
shape_channels
)

parameters

group INTEGER particle group
particle_flags ENUM( flex_particle_flags ) flags
shape_channels ENUM( flex_particle_flags ) channels for collisions

return values

none

code sample

-- Flags / options
--
eNvFlexPhaseSelfCollide	= 1048576 -- If set this particle will interact with particles of the same group
eNvFlexPhaseSelfCollideFilter	= 2097152 -- If set this particle will ignore collisions with particles closer than the radius in the rest pose, this flag should not be specified unless valid rest positions have been specified using NvFlexSetRestParticles()
eNvFlexPhaseFluid	= 4194304 -- If set this particle will generate fluid density constraints for its overlapping neighbors
eNvFlexPhaseGroupMask = 1048575 -- Bits [ 0, 19] represent the particle group for controlling collisions
eNvFlexPhaseFlagsMask	= 15728640 -- Bits [20, 23] hold flags about how the particle behave
eNvFlexPhaseShapeChannelMask = 2130706432 -- Bits [24, 30] hold flags representing what shape collision channels particles will collide with, see NvFlexMakeShapeFlags() (highest bit reserved for now)
eNvFlexPhaseShapeChannel0	= 16777216 -- Particle will collide with shapes 
with channel 0 set (see NvFlexMakeShapeFlags())
eNvFlexPhaseShapeChannel1 = 33554432

group = 0
particle_flags = eNvFlexPhaseSelfCollide
shape_channels = eNvFlexPhaseShapeChannelMask

phase = gh_flex.make_phase(group, particle_flags, shape_channels)

particles_copy_position_to_vb_fast

Performs a fast copy of particles position from FleX buffer to the vertex buffer used in rendering.

syntax

gh_flex.particles_copy_position_to_vb_fast (
particles_id,
vb_id,
num_particles
)

parameters

particles_id ID particle set identifier
vb_id ID rendering vertex buffer identifier
num_particles INTEGER number of particles

return values

none

code sample

gh_flex.particles_copy_position_to_vb_fast(particles_id, vb_id, num_vertices)

particles_copy_to_vb

Performs a fast copy of particles from FleX buffer to the vertex buffer used in rendering.

syntax

gh_flex.particles_copy_to_vb (
particles_id,
particle_attrib,
vb_id,
num_particles,
vb_start_offset_bytes,
vb_position_stride_bytes,
update_color_alpha,
dt
)

parameters

particles_id ID particle set identifier
particle_attrib ENUM( flex_particle_attrib_name ) particle attribute
vb_id ID rendering vertex buffer identifier
num_particles INTEGER number of particles
vb_start_offset_bytes INTEGER start offset in bytes in the vertex buffer
vb_position_stride_bytes INTEGER size of a vertex in bytes in the vertex buffer. In code samples, the vertex is {vec4 position + vec4 color}. The size is then 32 bytes.
update_color_alpha BOOLEAN updates the alpha value of the color by decreasing it with time step (alpha = alpha - dt): 1 (true) or 0 (false)
dt REAL time step for updating the alpha value

return values

none

code sample

local vb_start_offset_bytes = 0
local vb_position_stride_bytes = 32
local update_color_alpha = 0
local dt = 0.016

gh_flex.particles_copy_to_vb(particles_id, "position", vb_id, num_vertices, vb_start_offset_bytes, vb_position_stride_bytes, update_color_alpha, dt)

-- particles_copy_to_vb() replaces the following code:
--
--[[
function point(buffer_ptr, index, x, y, z, r, g, b, a)
    -- Position
    local buffer_offset_bytes = index * vertex_size
    gh_utils.buffer_write_4f(buffer_ptr, buffer_offset_bytes, x, y, z, 1.0)

    -- Color
    buffer_offset_bytes = buffer_offset_bytes + attrib_size
    gh_utils.buffer_write_4f(buffer_ptr, buffer_offset_bytes, r, g, b, a)
end

gh_flex.particles_map_position(particles_id)
vb_buffer_ptr, bufsize = gh_vb.map(vb_id, "GL_WRITE_ONLY")

for i = 0, num_vertices - 1 do
    x, y, z, w = gh_flex.particles_get_position(particles_id, i)
    local alpha = particles[i+1].a
    if (update_color_alpha == 1) then
        alpha = alpha - dt
        if (alpha < 0) then
            alpha = 0
        end
    end
    particles[i+1].a = alpha
    point(vb_buffer_ptr, i, x, y, z, 1, 1, 1, alpha)
end

gh_vb.unmap(vb_id)
gh_flex.particles_unmap_position(particles_id)
--]]

particles_create

Creates a set of particles.

syntax

particles_id = gh_flex.particles_create (
num_particles
)

parameters

num_particles INTEGER number of particles in the set

return values

particles_id ID particle set identifier

code sample

num_particles = 1000
particles_id = gh_flex.particles_create(num_particles)

particles_get_phase

Gets the phase of a particular particle.
A phase is a bit-vector that defines the behavior of a particle.
See make_phase().

syntax

phase = gh_flex.particles_get_phase (
particles_id,
particle_index
)

parameters

particles_id ID particle set identifier
particle_index INTEGER particle index

return values

phase INTEGER value of the phase

code sample

phase = gh_flex.particles_get_phase(particles_id, particle_index)

particles_get_position

Gets the position of a particular particle.

syntax

x, y, z, w = gh_flex.particles_get_position (
particles_id,
particle_index
)

parameters

particles_id ID particle set identifier
particle_index INTEGER particle index

return values

x, y, z, w REAL 3D position

code sample

x, y, z, w = gh_flex.particles_get_position(particles_id, particle_index)

particles_get_velocity

Gets the velocity of a particular particle.

syntax

x, y, z = gh_flex.particles_get_velocity (
particles_id,
particle_index
)

parameters

particles_id ID particle set identifier
particle_index INTEGER particle index

return values

x, y, z REAL velocity vector

code sample

x, y, z = gh_flex.particles_get_velocity(particles_id, index)

particles_kill

Destroys a set of particles.

syntax

gh_flex.particles_kill (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_kill(particles_id)

particles_map_active_indices

Maps the particles indices buffer.
That allows the CPU to writes to this buffer.

syntax

gh_flex.particles_map_active_indices (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_map_active_indices(particles_id)

particles_map_phase

Maps the particles phase buffer.
That allows the CPU to writes to this buffer.

syntax

gh_flex.particles_map_phase (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_map_phase(particles_id)

particles_map_position

Maps the particles position buffer.
That allows the CPU to writes to this buffer.

syntax

gh_flex.particles_map_position (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_map_position(particles_id)

particles_map_velocity

Maps the particles velocity buffer.
That allows the CPU to writes to this buffer.

syntax

gh_flex.particles_map_velocity (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_map_velocity(particles_id)

particles_set_active_index

Sets which particle is active.

syntax

gh_flex.particles_set_active_index (
particles_id,
index,
particle_index
)

parameters

particles_id ID particle set identifier
index INTEGER index in the active buffer
particle_index INTEGER particle index

return values

none

code sample

-- All the following code can be replaced by one call to particles_update_active()

-- Usually particles_set_active_index() is used as follows:
--

gh_flex.particles_map_active_indices(particles_id)

for i = 0, num_particles - 1 do
    gh_flex.particles_set_active_index(particles_id, i, i)
end

gh_flex.particles_unmap_active_indices(particles_id)
gh_flex.particles_set_num_active_indices(particles_id, num_particles)

-- Upload to GPU
gh_flex.solver_write_particles(solver_id, particles_id)

particles_set_num_active_indices

Sets the number of active particles.

syntax

gh_flex.particles_set_num_active_indices (
particles_id,
num_active
)

parameters

particles_id ID particle set identifier
num_active INTEGER number of active particles

return values

none

code sample

gh_flex.particles_set_num_active_indices(particles_id, num_active)

particles_set_phase

Sets the phase of a particle.
The phase is a bit-vector that defines the behavior of a particle.
Use the function make_phase() to generate a phase.

syntax

gh_flex.particles_set_phase (
particles_id,
particle_index,
phase
)

parameters

particles_id ID particle set identifier
particle_index INTEGER particle index
phase INTEGER particle phase

return values

none

code sample

gh_flex.particles_map_position(particles_id)
gh_flex.particles_map_velocity(particles_id)
gh_flex.particles_map_phase(particles_id)

phase = gh_flex.make_phase(...)

for i = 0, num_particles - 1 do
    x = random(...)
    y = random(...)
    z = random(...)

    -- Mass = 1.0
    w = 1.0
    gh_flex.particles_set_position(particles_id, i, x, y, z, w)

    -- Initial velocity is zero
    gh_flex.particles_set_velocity(particles_id, i, 0.0, 0.0, 0.0)
    gh_flex.particles_set_phase(particles_id, i, phase)
end

gh_flex.particles_unmap_phase(particles_id)
gh_flex.particles_unmap_velocity(particles_id)
gh_flex.particles_unmap_position(particles_id)

-- Upload to GPU
gh_flex.solver_write_particles(solver_id, particles_id)

particles_set_position

Sets the position of a particle.

syntax

gh_flex.particles_set_position (
particles_id,
particle_index,
x, y, z, w
)

parameters

particles_id ID particle set identifier
particle_index INTEGER particle index
x, y, z, w REAL particle position - w holds the inverse of the mass: w=1.0/mass.

return values

none

code sample

gh_flex.particles_map_position(particles_id)

for i = 0, num_particles - 1 do
    x = random(...)
    y = random(...)
    z = random(...)

    -- Mass = 1.0
    w = 1.0
    gh_flex.particles_set_position(particles_id, i, x, y, z, w)
end

gh_flex.particles_unmap_position(particles_id)

-- Upload to GPU
gh_flex.solver_write_particles(solver_id, particles_id)

particles_set_velocity

Sets the velocity of a particle.

syntax

gh_flex.particles_set_velocity (
particles_id,
particle_index,
x, y, z
)

parameters

particles_id ID particle set identifier
particle_index INTEGER particle index
x, y, z REAL particle velocity

return values

none

code sample

gh_flex.particles_map_position(particles_id)
gh_flex.particles_map_velocity(particles_id)

for i = 0, num_particles - 1 do
    x = random(...)
    y = random(...)
    z = random(...)

    -- Mass = 1.0
    w = 1.0
    gh_flex.particles_set_position(particles_id, i, x, y, z, w)

    -- Initial velocity is zero.
    gh_flex.particles_set_velocity(particles_id, i, 0.0, 0.0, 0.0)
end

gh_flex.particles_unmap_velocity(particles_id)
gh_flex.particles_unmap_position(particles_id)

-- Upload to GPU
gh_flex.solver_write_particles(solver_id, particles_id)

particles_unmap_active_indices

Unmaps the particles indices buffer.

syntax

gh_flex.particles_unmap_active_indices (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_unmap_active_indices(particles_id)

particles_unmap_phase

Unmaps the particles phase buffer.

syntax

gh_flex.particles_unmap_phase (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_unmap_phase(particles_id)

particles_unmap_position

Unmaps the particles position buffer.

syntax

gh_flex.particles_unmap_position (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_unmap_position(particles_id)

particles_unmap_velocity

Unmaps the particles velocity buffer.

syntax

gh_flex.particles_unmap_velocity (
particles_id
)

parameters

particles_id ID particle set identifier

return values

none

code sample

gh_flex.particles_unmap_velocity(particles_id)

particles_update_active

Updates all active particles in a single function.

syntax

gh_flex.particles_update_active (
particles_id,
num_active_particles
)

parameters

particles_id ID particle set identifier
num_active_particles INTEGER number of active particles

return values

none

code sample

gh_flex.particles_update_active(particles_id, num_active_particles)

-- particles_update_active() replaces the following code:
--
--[[
gh_flex.particles_set_num_active_indices(particles_id, num_vertices)
gh_flex.particles_map_active_indices(particles_id)

for i = 0, num_vertices - 1 do
    gh_flex.particles_set_active_index(particles_id, i, i)
end

gh_flex.particles_unmap_active_indices(particles_id)
--]]

set_device_index

Sets the device index.
This function allows to select a particular FleX GPU.
Use -1 to auto-select the default PhysX accelerator in NVIDIA control panel.

syntax

gh_flex.set_device_index (
i
)

parameters

i INTEGER device index

return values

none

code sample

gh_flex.set_device_index(-1)

shapes_create

Creates a set of collision shapes.

syntax

shapes_id = gh_flex.shapes_create (
num_shapes
)

parameters

num_shapes INTEGER number of shapes in the set

return values

shapes_id ID shapes set identifier

code sample

num_shapes = 2
shapes_id = gh_flex.shapes_create(num_shapes)

shapes_kill

Destroys a set of shapes.

syntax

gh_flex.shapes_kill (
shapes_id
)

parameters

shapes_id ID shapes set identifier

return values

none

code sample

gh_flex.shapes_kill(shapes_id)

shapes_map

Maps a shapes buffer.
That allows the CPU to writes to this buffer.

syntax

gh_flex.shapes_map (
shapes_id
)

parameters

shapes_id ID shapes set identifier

return values

none

code sample

gh_flex.shapes_map(shapes_id)

shapes_set_box

Sets a box collision shape.

syntax

gh_flex.shapes_set_box (
shapes_id,
shape_index,
shape_channels,
width, height, depth,
x, y, z,
qx, qy, qz, qw
)

parameters

shapes_id ID shapes set identifier
shape_index INTEGER index of the shape between 0 ; num_shapes-1
shape_channels ENUM( flex_particle_flags ) channels for collisions
width, height, depth REAL box size
x, y, z REAL box position
qx, qy, qz, qw REAL box orientation (quaternion)

return values

none

code sample

gh_flex.shapes_map(shapes_id)
shape_index = 0
shape_channels = eNvFlexPhaseShapeChannel0
width = 2.0
height = 2.0
depth = 2.0
gh_flex.shapes_set_box(shapes_id, shape_index, shape_channels,  width, height, depth,  0.0, 1.0, 0.0,  0.0, 0.0, 0.0, 1.0)
gh_flex.shapes_unmap(shapes_id)

shapes_set_box_v2

Sets a box collision shape.

syntax

gh_flex.shapes_set_box_v2 (
shapes_id,
shape_index,
shape_channels,
width, height, depth,
x, y, z,
pitch, yaw, roll
)

parameters

shapes_id ID shapes set identifier
shape_index INTEGER index of the shape between 0 ; num_shapes-1
shape_channels ENUM( flex_particle_flags ) channels for collisions
width, height, depth REAL box size
x, y, z REAL box position
pitch, yaw, roll REAL box orientation (Euler's angles)

return values

none

code sample

gh_flex.shapes_map(shapes_id)

shape_index = 0
shape_channels = eNvFlexPhaseShapeChannel0
width = 2.0
height = 2.0
depth = 2.0

gh_flex.shapes_set_box_v2(shapes_id, shape_index, shape_channels,  width, height, depth,  0.0, 1.0, 0.0,  0.0, 0.0, 0.0)

gh_flex.shapes_unmap(shapes_id)

shapes_set_mesh

Sets a mesh collision shape.

syntax

gh_flex.shapes_set_mesh (
shapes_id,
shape_index,
shape_channels,
mesh_id,
x, y, z,
qx, qy, qz, qw
)

parameters

shapes_id ID shapes set identifier
shape_index INTEGER index of the shape between 0 ; num_shapes-1
shape_channels ENUM( flex_particle_flags ) channels for collisions
mesh_id ID mesh identifier
x, y, z REAL mesh position
qx, qy, qz, qw REAL mesh orientation (quaternion)

return values

none

code sample

gh_flex.shapes_map(shapes_id)

shape_index = 0
shape_channels = eNvFlexPhaseShapeChannel0
mesh_id = gh_mesh.create_torus(2.0, 0.4, 20)

gh_flex.shapes_set_mesh(shapes_id, shape_index, shape_channels,  mesh_id,  0.0, 2.0, 0.0,  0.0, 0.0, 0.0, 1.0)

gh_flex.shapes_unmap(shapes_id)

shapes_set_mesh_v2

Sets a mesh collision shape.

syntax

gh_flex.shapes_set_mesh_v2 (
shapes_id,
shape_index,
shape_channels,
mesh_id,
x, y, z,
pitch, yaw, roll
)

parameters

shapes_id ID shapes set identifier
shape_index INTEGER index of the shape between 0 ; num_shapes-1
shape_channels ENUM( flex_particle_flags ) channels for collisions
mesh_id ID mesh identifier
x, y, z REAL mesh position
pitch, yaw, roll REAL box orientation (Euler's angles)

return values

none

code sample

gh_flex.shapes_map(shapes_id)

shape_index = 0
shape_channels = eNvFlexPhaseShapeChannel0
mesh_id = gh_mesh.create_torus(2.0, 0.4, 20)

gh_flex.shapes_set_mesh_v2(shapes_id, shape_index, shape_channels,  mesh_id,  0.0, 2.0, 0.0,  0.0, 0.0, 0.0)

gh_flex.shapes_unmap(shapes_id)

shapes_set_sphere

Sets a sphere collision shape.

syntax

gh_flex.shapes_set_sphere (
shapes_id,
shape_index,
shape_channels,
radius,
x, y, z
)

parameters

shapes_id ID shapes set identifier
shape_index INTEGER index of the shape between 0 ; num_shapes-1
shape_channels ENUM( flex_particle_flags ) channels for collisions
radius REAL sphere radius
x, y, z REAL sphere position

return values

none

code sample

gh_flex.shapes_map(shapes_id)

shape_index = 0
shape_channels = eNvFlexPhaseShapeChannel0
radius = 2.0

gh_flex.shapes_set_sphere(shapes_id, shape_index, shape_channels, radius, 0.0, 3.0, 0.0)

gh_flex.shapes_unmap(shapes_id)

shapes_unmap

Unmaps the shapes buffer.

syntax

gh_flex.shapes_unmap (
shapes_id
)

parameters

shapes_id ID shapes set identifier

return values

none

code sample

gh_flex.shapes_unmap(shapes_id)

solver_create

Creates a FleX solver.

syntax

solver_id = gh_flex.solver_create (
max_particles
)

parameters

max_particles INTEGER max number of particles managed by the solver

return values

solver_id ID solver identifier

code sample

max_particles = 1000
solver_id = gh_flex.solver_create(max_particles)

solver_kill

Destroys a FleX solver.

syntax

gh_flex.solver_kill (
solver_id
)

parameters

solver_id ID solver identifier

return values

none

code sample

gh_flex.solver_kill(solver_id)

solver_set_num_active_particles

Sets the number of active particles.

syntax

gh_flex.solver_set_num_active_particles (
solver_id,
num_active_particles
)

parameters

solver_id ID solver identifier
num_active_particles INTEGER shapes identifier

return values

none

code sample

gh_flex.solver_set_num_active_particles(solver_id, num_active_particles)

solver_set_param_1f

Set a solver parameter.

syntax

gh_flex.solver_set_param_1f (
solver_id,
param_name,
x
)

parameters

solver_id ID solver identifier
param_name ENUM( flex_solver_param_1f ) param name
x REAL value

return values

none

code sample

params = [[
float radius;						//!< The maximum interaction radius for particles
float solidRestDistance;			//!< The distance non-fluid particles attempt to maintain from each other, must be in the range (0, radius]
float fluidRestDistance;			//!< The distance fluid particles are spaced at the rest density, must be in the range (0, radius], for fluids this should generally be 50-70% of mRadius, for rigids this can simply be the same as the particle radius
// common params
float dynamicFriction;				//!< Coefficient of friction used when colliding against shapes
float staticFriction;				//!< Coefficient of static friction used when colliding against shapes
float particleFriction;				//!< Coefficient of friction used when colliding particles
float restitution;					//!< Coefficient of restitution used when colliding against shapes, particle collisions are always inelastic
float adhesion;						//!< Controls how strongly particles stick to surfaces they hit, default 0.0, range [0.0, +inf]
float sleepThreshold;				//!< Particles with a velocity magnitude < this threshold will be considered fixed
float maxSpeed;						//!< The magnitude of particle velocity will be clamped to this value at the end of each step
float maxAcceleration;				//!< The magnitude of particle acceleration will be clamped to this value at the end of each step (limits max velocity change per-second), useful to avoid popping due to large interpenetrations
float shockPropagation;				//!< Artificially decrease the mass of particles based on height from a fixed reference point, this makes stacks and piles converge faster
float dissipation;					//!< Damps particle velocity based on how many particle contacts it has
float damping;						//!< Viscous drag force, applies a force proportional, and opposite to the particle velocity
// cloth params
float drag;							//!< Drag force applied to particles belonging to dynamic triangles, proportional to velocity^2*area in the negative velocity direction
float lift;							//!< Lift force applied to particles belonging to dynamic triangles, proportional to velocity^2*area in the direction perpendicular to velocity and (if possible), parallel to the plane normal
// fluid params
float cohesion;						//!< Control how strongly particles hold each other together, default: 0.025, range [0.0, +inf]
float surfaceTension;				//!< Controls how strongly particles attempt to minimize surface area, default: 0.0, range: [0.0, +inf]
float viscosity;					//!< Smoothes particle velocities using XSPH viscosity
float vorticityConfinement;			//!< Increases vorticity by applying rotational forces to particles
float anisotropyScale;				//!< Control how much anisotropy is present in resulting ellipsoids for rendering, if zero then anisotropy will not be calculated, see NvFlexGetAnisotropy()
float anisotropyMin;				//!< Clamp the anisotropy scale to this fraction of the radius
float anisotropyMax;				//!< Clamp the anisotropy scale to this fraction of the radius
float smoothing;					//!< Control the strength of Laplacian smoothing in particles for rendering, if zero then smoothed positions will not be calculated, see NvFlexGetSmoothParticles()
float solidPressure;				//!< Add pressure from solid surfaces to particles
float freeSurfaceDrag;				//!< Drag force applied to boundary fluid particles
float buoyancy;						//!< Gravity is scaled by this value for fluid particles
// diffuse params
float diffuseThreshold;				//!< Particles with kinetic energy + divergence above this threshold will spawn new diffuse particles
float diffuseBuoyancy;				//!< Scales force opposing gravity that diffuse particles receive
float diffuseDrag;					//!< Scales force diffuse particles receive in direction of neighbor fluid particles
float diffuseLifetime;				//!< Time in seconds that a diffuse particle will live for after being spawned, particles will be spawned with a random lifetime in the range [0, diffuseLifetime]
// collision params
float collisionDistance;			//!< Distance particles maintain against shapes, note that for robust collision against triangle meshes this distance should be greater than zero
float particleCollisionMargin;		//!< Increases the radius used during neighbor finding, this is useful if particles are expected to move significantly during a single step to ensure contacts aren't missed on subsequent iterations
float shapeCollisionMargin;			//!< Increases the radius used during contact finding against kinematic shapes
float relaxationFactor;				//!< Control the convergence rate of the parallel solver, default: 1, values greater than 1 may lead to instability
]]

gh_flex.solver_set_param_1f(solver_id, "radius", 0.1)
gh_flex.solver_set_param_1f(solver_id, "dynamicFriction", 0.15)

solver_set_param_1i

Set a solver parameter.

syntax

gh_flex.solver_set_param_1i (
solver_id,
param_name,
x
)

parameters

solver_id ID solver identifier
param_name ENUM( flex_solver_param_1i ) param name
x INTEGER value

return values

none

code sample

params = [[
int numIterations;					//!< Number of solver iterations to perform per-substep
int diffuseBallistic;				//!< The number of neighbors below which a diffuse particle is considered ballistic
int numPlanes;						//!< Num collision planes
]]

gh_flex.solver_set_param_1i(solver_id, "numIterations", 2)

solver_set_param_3f

Set a solver parameter.

syntax

gh_flex.solver_set_param_3f (
solver_id,
param_name,
x, y, z
)

parameters

solver_id ID solver identifier
param_name ENUM( flex_solver_param_3f ) param name
x, y, z REAL value

return values

none

code sample

params = [[
float gravity[3];					//!< Constant acceleration applied to all particles
// cloth params
float wind[3];						//!< Constant acceleration applied to particles that belong to dynamic triangles, drag needs to be > 0 for wind to affect triangles
]]

gh_flex.solver_set_param_1f(solver_id, "gravity", 0.0, -10.0, 0.0)

solver_set_param_collision_plane

Set a collision plane (a particular solver parameter).
FleX has a max 8 collision planes.

syntax

gh_flex.solver_set_param_collision_plane (
solver_id,
plane_index,
a, b, c, d
)

parameters

solver_id ID solver identifier
plane_index INTEGER index of the plane: 0 to 7 (8 planes)
a, b, c, d REAL plane equation: ax + by + cz + d = 0

return values

none

code sample

gh_flex.solver_set_param_1i(solver_id, "numPlanes", 1)

plane_index = 0
gh_flex.solver_set_param_collision_plane(solver_id, plane_index, 0.0, 1.0, 0.0, 0.0)

solver_update

Updates a solver: runs the simulation.

syntax

gh_flex.solver_update (
solver_id,
dt,
substeps
)

parameters

solver_id ID solver identifier
dt REAL time step
substeps INTEGER number of simulation substeps

return values

none

code sample

substeps = 2
gh_flex.solver_update(solver_id, dt, substeps)

solver_update_params

Writes params (update) to GPU.

syntax

gh_flex.solver_update_params (
solver_id
)

parameters

solver_id ID solver identifier

return values

none

code sample

gh_flex.solver_update_params(solver_id)

solver_write_particles

Sets / writes particles to GPU.

syntax

gh_flex.solver_write_particles (
solver_id,
particles_id
)

parameters

solver_id ID solver identifier
particles_id ID particles identifier

return values

none

code sample

num_particles = 1000

particles_id = gh_flex.particles_create(num_particles)
...
gh_flex.solver_write_particles(solver_id, particles_id)

solver_write_shapes

Sets / writes collision shapes to GPU.

syntax

gh_flex.solver_write_shapes (
solver_id,
shapes_id
)

parameters

solver_id ID solver identifier
shapes_id ID shapes identifier

return values

none

code sample

num_shapes = 2

shapes_id = gh_flex.shapes_create(num_shapes)
...
gh_flex.solver_write_shapes(solver_id, shapes_id)

start

Starts the FleX engine.
Must be called first.
No-op if called twice.

syntax

state = gh_flex.start()

parameters

none

return values

state BOOLEAN 1 (success) or 0 (error)

code sample

flex_ok = gh_flex.start()

if (flex_ok == 0) then
    -- error
end

stop

Stops the FleX engine.
Must be called at the end of the application (TERMINATE script is a good place).

syntax

state = gh_flex.stop()

parameters

none

return values

state BOOLEAN 1 (success) or 0 (error)

code sample

state = gh_flex.stop()

gh_font

Simple True Type Font module

gh_font is the module that manages TrueType Fonts (TTF) or OpenType Fonts (OTF).
This module is available on all platforms (Windows, Linux, macOS, Raspberry Pi and Tinker Board).

build_texture

Builds the font texture.

syntax

gh_font.build_texture (
font_id,
tex_unit
)

parameters

font_id ID font identifier
tex_unit INTEGER texture unit

return values

none

code sample

gh_font.build_texture(font_id, 0)

clear

This function clears the draw text list.
This function is used with dynamic texts.

syntax

gh_font.clear (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_font.clear(font_id)
gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello!")
gh_font.update(font_id, 0)
gh_font.render(font_id)

create

Creates a font object from a TTF or an OTF file.

syntax

font_id = gh_font.create (
font_filename,
font_height,
font_tex_width,
font_texture_height
)

parameters

font_filename STRING absolute path of the TTF/OTF file
font_height INTEGER height of the font
font_tex_width INTEGER width in pixels of the texture font
font_texture_height INTEGER height in pixels of the texture font

return values

font_id ID font identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
font_id = gh_font.create(demo_dir .. "./data/kool.ttf", 24, 512, 512)

create_from_buffer

Creates a font from a memory buffer.

syntax

font_id = gh_font.create_from_buffer (
buff_ptr,
buff_size,
font_height,
font_tex_width,
font_texture_height,
char_offset_start,
num_chars
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
font_height INTEGER height of the font
font_tex_width INTEGER width in pixels of the texture font
font_texture_height INTEGER height in pixels of the texture font
char_offset_start INTEGER start char offset (0 … 254). Default value: 32
num_chars INTEGER number of chars in the texture. Default value: 256

return values

font_id ID font identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
filename = demo_dir .. "assets/arial.ttf"
buffer, buffer_size = gh_utils.file_buffer_create(filename)

font_id = gh_font.create_from_buffer(buffer, buffer_size, 24, 512, 512, 32, 256)

gh_utils.file_buffer_kill(buffer)

create_from_sqlite3_blob

Creates a font from raw data stored a in a SQLite3 blob.

syntax

font_id = gh_font.create_from_sqlite3_blob (
db_id,
column,
font_height,
font_tex_width,
font_texture_height,
char_offset_start,
num_chars
)

parameters

db_id ID database identifier
column INTEGER index of the column
font_height INTEGER height of the font
font_tex_width INTEGER width in pixels of the texture font
font_texture_height INTEGER height in pixels of the texture font
char_offset_start INTEGER start char offset (0 … 254). Default value: 32
num_chars INTEGER number of chars in the texture. Default value: 256

return values

font_id ID font identifier

code sample

font_id = gh_font.create_from_sqlite3_blob(db_id, column, 24, 512, 512, 32, 256)

create_from_zip

Creates a font from a file stored in a zip archive.

syntax

font_id = gh_font.create_from_zip (
zip_filename,
filename,
font_height,
font_tex_width,
font_texture_height,
char_offset_start,
num_chars
)

parameters

zip_filename STRING absolute path of the zip file
filename STRING font file in the zip archive
font_height INTEGER height of the font
font_tex_width INTEGER width in pixels of the texture font
font_texture_height INTEGER height in pixels of the texture font
char_offset_start INTEGER start char offset (0 … 254). Default value: 32
num_chars INTEGER number of chars in the texture. Default value: 256

return values

font_id ID font identifier

code sample

zip_filename = demo_dir .. "data.zip"
font_id = gh_font.create_from_zip_v1(zip_filename, "fonts/arial.ttf", 24, 512, 512, 32, 256)

create_v2

Creates a font object from a built-in TrueType (TTF) font.

syntax

font_id = gh_font.create_v2 (
font_name,
font_height,
font_tex_width,
font_texture_height
)

parameters

font_name ENUM( builtin_font ) the name of the built-in TTF font (see name in the code snippet)
font_height INTEGER height of the font
font_tex_width INTEGER width in pixels of the texture font
font_texture_height INTEGER height in pixels of the texture font

return values

font_id ID font identifier

code sample

local built_in_fonts = {"roboto_bold", "roboto_medium", "roboto_medium_italic", "technott", "hacked", "top_secret", "timeless_bold", "vcr_osd_mono1"}

font_id = gh_font.create_v2(built_in_fonts[1], 24, 512, 512)

create_v3

Creates a font object from a TTF or an OTF file.
The range of characters that must be loaded is also specified.
Useful to load fonts with Chinese characters for example.

syntax

font_id = gh_font.create_v3 (
font_filename,
font_height,
font_tex_width,
font_texture_height,
char_offset_start,
num_chars
)

parameters

font_filename STRING absolute path of the TTF/OTF file
font_height INTEGER height of the font
font_tex_width INTEGER width in pixels of the texture font
font_texture_height INTEGER height in pixels of the texture font
char_offset_start INTEGER offset of the first character (default: 32)
num_chars INTEGER number of characters (default: 256)

return values

font_id ID font identifier

code sample

char_offset_start = 32
num_chars = 256
font_id = gh_font.create(demo_dir .. "data/kool.ttf", 24, 512, 512, char_offset_start, num_chars)

get_num_strings

Returns the number of strings in a font (added with text_2d() for example) since the last call to gh_font_clear().

syntax

num_strings = gh_font.get_num_strings (
font_id
)

parameters

font_id ID font identifier

return values

num_strings INTEGER number of strings

code sample

num_strings = gh_font.get_num_strings(font_id)

get_string_num_chars

Returns the number of characters of a particular string of a font.

syntax

num_chars = gh_font.get_string_num_chars (
font_id,
string_index
)

parameters

font_id ID font identifier
string_index INTEGER string index

return values

num_chars INTEGER number of characters

code sample

num_chars = gh_font.get_string_num_chars(font_id, string_index)

get_text_width

Returns the width of the text in pixels according to the TrueType font and the font size.

syntax

width = gh_font.get_text_width (
font_id,
text
)

parameters

font_id ID font identifier
text STRING text

return values

width INTEGER width of the text

code sample

text_width = gh_font.get_text_width(font_id, "Hello!")

get_text_width_w

Wide character / unicode version of get_text_width.
Returns the width of the text in pixels according to the TrueType font and the font size.

syntax

width = gh_font.get_text_width_w (
font_id,
text
)

parameters

font_id ID font identifier
text STRING text

return values

width INTEGER width of the text

code sample

text_width = gh_font.get_text_width_w(font_id, "Hello!")

get_texture

Gets the front texture identifier.

syntax

font_tex_id = gh_font.get_texture (
font_id
)

parameters

font_id ID font identifier

return values

font_tex_id ID font texture identifier

code sample

font_tex = gh_font.get_texture(font_id)
...
gh_texture.bind(font_tex, 0)

render

Renders the font.
Performs the real drawing.

syntax

gh_font.render (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_font.render(font_id)

set_scale

Sets the scale for rendering.

syntax

gh_font.set_scale (
font_id,
scale
)

parameters

font_id ID font identifier
scale REAL scale factor (default: 1.0)

return values

none

code sample

gh_font.set_scale(font_id, 2.0)

set_string_char_color_factor

Sets a color factor to a character.
This color factor is multplied by the color of the string.

syntax

gh_font.set_string_char_color_factor (
font_id,
string_index,
char_index,
r, g, b, a
)

parameters

font_id ID font identifier
string_index INTEGER string index
char_index INTEGER character index
r, g, b, a REAL color factor

return values

none

code sample

gh_font.set_string_char_color_factor(font_id, string_index, char_index, r, g, b, a)

set_string_char_position_offset

Translates a particular character with a {x, y, z} offset.

syntax

gh_font.set_string_char_position_offset (
font_id,
string_index,
char_index,
x, y, z
)

parameters

font_id ID font identifier
string_index INTEGER string index
char_index INTEGER character index
x, y, z REAL offset vector

return values

none

code sample

gh_font.set_string_char_position_offset(font_id, string_index, char_index, x, y, z)

text_2d

Sets a text in 2D.
The text is added in a list and the real draw will occur later with a call to gh_font.render().

syntax

gh_font.text_2d (
font_id,
x, y,
r, g, b, a,
text
)

parameters

font_id ID font identifier
x, y REAL start position of the text
r, g, b, a REAL RGBA text color
text STRING text

return values

none

code sample

gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello!")

text_2d_v2

Like text_2d(), text_2d_v2() sets a text in 2D.
But this function takes no position.
It simply appends the text on the same line than the previous one.

syntax

gh_font.text_2d_v2 (
font_id,
r, g, b, a,
text
)

parameters

font_id ID font identifier
r, g, b, a REAL RGBA text color
text STRING text

return values

none

code sample

gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello...")
gh_font.text_2d_v2(font_id, r, g, b, a, " from GeeXLab!")

text_3d

Sets a text in 3D.
The text is added in a list and the real draw will occur later with a call to gh_font.render().

syntax

gh_font.text_3d (
font_id,
x, y, z,
r, g, b, a
)

parameters

font_id ID font identifier
x, y, z REAL start position of the text
r, g, b, a REAL RGBA text color

return values

none

code sample

gh_font.text_3d(font_id, x, y, z, r, g, b, a, "Hello!")

update

Updates the font before the real rendering.

syntax

gh_font.update (
font_id,
mapped_gpu_memory
)

parameters

font_id ID font identifier
mapped_gpu_memory BOOLEAN GPU memory mapping for direct updating: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_font.clear(font_id)
gh_font.text_2d(font_id, x, y, r, g, b, a, "Hello!")
gh_font.update(font_id, 0)
gh_font.render(font_id)

update_texture_2d_array_layer

Update a layer of a texture array with the font texture.

syntax

gh_font.update_texture_2d_array_layer (
font_id,
texarray_id,
layer
)

parameters

font_id ID font identifier
texarray_id ID texture array identifier
layer INTEGER index of the layer in the texture array

return values

none

code sample

layer = 0
gh_font.update_texture_2d_array_layer(font_id, texarray_id, layer)

wtext_2d

Sets a text in 2D.
The text is added in a list and the real draw will occur later with a call to gh_font.render().

syntax

gh_font.wtext_2d (
font_id,
x, y,
r, g, b, a,
text
)

parameters

font_id ID font identifier
x, y REAL start position of the text
r, g, b, a REAL RGBA text color
text STRING text

return values

none

code sample

gh_font.wtext_2d(font_id, x, y, r, g, b, a, "Hello!")

wtext_2d_v2

Like wtext_2d(), wtext_2d_v2() sets a text in 2D.
But this function takes no position.
It simply appends the text on the same line than the previous one.

syntax

gh_font.wtext_2d_v2 (
font_id,
r, g, b, a,
text
)

parameters

font_id ID font identifier
r, g, b, a REAL RGBA text color
text STRING text

return values

none

code sample

gh_font.wtext_2d(font_id, x, y, r, g, b, a, "Hello...")
gh_font.wtext_2d_v2(font_id, r, g, b, a, " from GeeXLab!")

gh_gml windowslinuxmacos

GPU Monitoring module

gh_gml is the GPU monitoring module.
It is available for Windows, Linux, macOS and monitors NVIDIA GeForce/Quadro and AMD Radeon graphics cards.

amd_ags_get_gpu_info

Returns some GPU information for AMD Radeon GPUs.

syntax

num_cus, num_wgps, num_rops, core_clock, mem_clock = gh_gml.amd_ags_get_gpu_info (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

num_cus INTEGER number of compute units
num_wgps INTEGER number of RDNA work group processors
num_rops INTEGER number of render output units
core_clock INTEGER core clock speed at 100% power in MHz
mem_clock INTEGER memory clock speed at 100% power in MHz

code sample

num_cus, num_wgps, num_rops, core_clock, mem_clock = gh_gml.amd_ags_get_gpu_info(gpu_index)

amd_get_overdrive_version

Returns the overdrive version.
For example, the overdrive is 8 for Navi GPUs.

syntax

ver = gh_gml.amd_get_overdrive_version (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

ver INTEGER overdrive version

code sample

ver = gh_gml.amd_get_overdrive_version(gpu_index)

amd_get_power_rdna

Returns the power consumption in Watts of a Navi / RDNA graphics card.

syntax

asic, soc = gh_gml.amd_get_power_rdna (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

asic, soc INTEGER power: ASIC and SoC

code sample

asic, soc = gh_gml.amd_get_power_rdna(gpu_index)

amd_get_temperatures_rdna

Returns the temperatures of a Navi / RDNA graphics card.

syntax

gpu, mem, hotstop = gh_gml.amd_get_temperatures_rdna (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

gpu, mem, hotstop INTEGER temperature of GPU, memory and hotstop/junction

code sample

gpu, mem, hotstop = gh_gml.amd_get_temperatures_rdna(gpu_index)

geforce_logo_get_illumination

GTX 600/700: gets the current illumination value of the GeForce GTX LED logo.

syntax

illum_value = gh_gml.geforce_logo_get_illumination (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

illum_value REAL logo illumination value

code sample

illum_value = gh_gml.geforce_logo_get_illumination(0)

geforce_logo_is_illumination_supported

GTX 600/700: checks whether the GeForce GTX LED logo is supported.

syntax

is_supported = gh_gml.geforce_logo_is_illumination_supported (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

is_supported BOOLEAN supported: 1 (true) or 0 (false)

code sample

is_supported = gh_gml.geforce_logo_is_illumination_supported(0)

geforce_logo_set_illumination

GTX 600/700: sets the current illumination value of the GeForce GTX LED logo.

syntax

gh_gml.geforce_logo_set_illumination (
gpu_index,
illum_value
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)
illum_value REAL logo illumination value

return values

none

code sample

gh_gml.geforce_logo_set_illumination(0, illum_value)

get_all_limiting_policies

Gets all policies that limits the GPU power (NVIDIA GPUs).

syntax

power, temperature, voltage, overvoltage = gh_gml.get_all_limiting_policies (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

power, temperature, voltage, overvoltage BOOLEAN limited: 1 (true) or 0 (false)

code sample

power, temperature, voltage, overvoltage = gh_gml.get_all_limiting_policies(0)

if (temperature == 1) then
    print("Limiting policy: temperature")
end

get_clocks

Gets the GPU core and memory clock speeds.

syntax

core_clock, mem_clock = gh_gml.get_clocks (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

core_clock, mem_clock INTEGER clock speeds

code sample

core_clock, mem_clock = gh_gml.get_clocks(0)

get_fan_speed

Gets the GPU fan speed.

syntax

percent, rpm = gh_gml.get_fan_speed (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

percent, rpm INTEGER speed in percent and RPM

code sample

percent, rpm = gh_gml.get_fan_speed(0)

get_gpu_architecture

Returns the GPU architecture for recent graphics cards (NVIDIA or AMD).
For example: Maxwell, Turing, GCN1, Vega or RDNA.

syntax

arch = gh_gml.get_gpu_architecture (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

arch STRING architecture

code sample

arch = gh_gml.get_gpu_architecture(gpu_index)

get_gpu_codename

Gets the GPU codename.

syntax

name = gh_gml.get_gpu_codename (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

name STRING codename of the GPU, ex: GK110

code sample

codename = gh_gml.get_gpu_codename(0)

get_gpu_config

Gets the GPU config: cores, TMUs and ROPs.

syntax

cores, tmus, rops = gh_gml.get_gpu_config (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

cores, tmus, rops INTEGER GPU config.

code sample

cores, tmus, rops = gh_gml.get_gpu_config(gpu_index)

get_gpu_cores

Gets the shader cores of the GPU.

syntax

num_cores = gh_gml.get_gpu_cores (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

num_cores INTEGER number of cores

code sample

cores = gh_gml.get_gpu_cores(0)

get_gpu_driver

Gets the GPU driver.

syntax

name = gh_gml.get_gpu_driver (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

name STRING driver name

code sample

driver_name = gh_gml.get_gpu_driver(0)

get_gpu_driver_v2

Gets graphics driver information.

syntax

driver_name, driver_version = gh_gml.get_gpu_driver_v2 (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

driver_name STRING name of the driver (AMD: Adrenalin 2020 for example, nothin with NVIDIA)
driver_version STRING version of the driver (AMD: 20.2.1, NVIDIA: 442.37...)

code sample

driver_name, driver_version = gh_gml.get_gpu_driver_v2(gpu_index)

get_gpu_eus

Gets the number of EUs (execution units) for Intel Arc GPUs.

syntax

num_eus = gh_gml.get_gpu_eus (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

num_eus INTEGER number of EUs

code sample

eus = gh_gml.get_gpu_eus(0)

get_gpu_fullname

Gets the GPU name.

syntax

name = gh_gml.get_gpu_fullname (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

name STRING name of the GPU, ex: GeForce GTX 780

code sample

gpu_name = gh_gml.get_gpu_fullname(0)

get_gpu_rt_tensor_cores

Gets the number of RT (raytracing) and tensor cores.
NVIDIA Turing+ GPUs only.

syntax

rt_cores, tensor_cores = gh_gml.get_gpu_rt_tensor_cores (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

rt_cores INTEGER number of raytracing cores
tensor_cores INTEGER number of tensor cores

code sample

rt_cores, tensor_cores = gh_gml.get_gpu_rt_tensor_cores(gpu_index)

get_memory_info_v2

Gets memory size information.
Currently on NVIDIA only.

syntax

memory_size_mb, cur_available_memory_size_mb = gh_gml.get_memory_info_v2 (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

memory_size_mb INTEGER total memory size in MB
cur_available_memory_size_mb INTEGER current available memory size in MB

code sample

memory_size_mb, cur_available_memory_size_mb = gh_gml.get_memory_info_v2(gpu_index)

get_num_gpus

Returns the number of GPUs.

syntax

num_gpus = gh_gml.get_num_gpus()

parameters

none

return values

num_gpus INTEGER number of GPUs

code sample

num_gpus = gh_gml.get_num_gpus()

get_pci_identifiers

alias →

Gets the PCI identifiers of the GPU (device and subdevice IDs).

syntax

vendorID, deviceID, subvendorID, subdeviceID = gh_gml.get_pci_identifiers (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

vendorID, deviceID, subvendorID, subdeviceID INTEGER PCI identifiers

code sample

vendorID, deviceID, subvendorID, subdeviceID = gh_gml.get_pci_identifiers(0)

get_revision_id

Gets the revision ID of the GPU.

syntax

revID = gh_gml.get_revision_id (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

revID INTEGER PCI identifiers

code sample

revID = gh_gml.get_revision_id(0)

get_temperatures

Gets the GPU core, mem, board and VRM temperatures if available.

syntax

gpu, mem, pcb, vrm = gh_gml.get_temperatures (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

gpu, mem, pcb, vrm INTEGER temperatures in degrees

code sample

gpu, mem, pcb, vrm = gh_gml.get_temperatures(0)

get_usages

Gets the GPU core and memory usages.

syntax

core_usage, mem_usage = gh_gml.get_usages (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

core_usage, mem_usage INTEGER usages

code sample

core_usage, mem_usage = gh_gml.get_usages(0)

get_vram_usage

Returns the size and usage of the graphics memory.

syntax

vram_size_mb, vram_usage_mb = gh_gml.get_vram_usage (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

vram_size_mb INTEGER size of the VRAM in MB
vram_usage_mb INTEGER amount of VRAM in use in MB

code sample

vram_size_mb, vram_usage_mb = gh_gml.get_vram_usage(gpu_index)

gpu_power_get_current_value_DUP1

GTX 600/700: returns the current GPU power.

syntax

power = gh_gml.gpu_power_get_current_value_DUP1 (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

power INTEGER power in percent

code sample

power = gh_gml.gpu_power_get_current_value(0)

gpu_power_get_current_value_DUP2

Returns the size and usage of the graphics memory.

syntax

gpu_power_percent, gpu_power_watts = gh_gml.gpu_power_get_current_value_DUP2 (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

gpu_power_percent REAL GPU power draw in percent
gpu_power_watts REAL GPU power draw in Watts

code sample

gpu_power_percent, gpu_power_watts = gh_gml.gpu_power_get_current_value(gpu_index)

gpu_power_get_current_value_v2

Returns the size and usage of the graphics memory.

syntax

total_board_power_watts, chip_power_watts = gh_gml.gpu_power_get_current_value_v2 (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

total_board_power_watts REAL total board power draw in Watts
chip_power_watts REAL GPU power draw in Watts

code sample

total_board_power_watts, chip_power_watts = gh_gml.gpu_power_get_current_value_v2(gpu_index)

gpu_power_get_power_limit

GTX 600/700: returns the power limit (or power target) of the GPU.

syntax

power = gh_gml.gpu_power_get_power_limit (
gpu_index
)

parameters

gpu_index INTEGER index of the GPU in the range (0 … num_gpus - 1)

return values

power INTEGER power in percent

code sample

power_target = gh_gml.gpu_power_get_power_limit(0)

gh_gpu_buffer

GPU buffers management module

Low level GPU buffers management module: creation, destruction and update (uniform buffers, shader storage buffer, etc).

atomic_counter_get_value

Gets the value of an atomic counter.

syntax

x = gh_gpu_buffer.atomic_counter_get_value (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x INTEGER atomic counter value

code sample

x = gh_gpu_buffer.atomic_counter_get_value(gpubuff_id, 4)

atomic_counter_set_value

Sets the value of an atomic counter.

syntax

gh_gpu_buffer.atomic_counter_set_value (
gpubuff_id,
offset,
x
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x INTEGER value

return values

none

code sample

gh_gpu_buffer.atomic_counter_set_value(gpubuff_id, 4, x)

bind

Binds a GPU buffer object.

syntax

gh_gpu_buffer.bind (
gpubuff_id
)

parameters

gpubuff_id ID gpu buffer identifier

return values

none

code sample

gh_gpu_buffer.bind(gpubuff_id)

bind_base

Binds a GPU buffer object on a specific buffer binding point.

syntax

gh_gpu_buffer.bind_base (
gpubuff_id,
binding_point_index
)

parameters

gpubuff_id ID gpu buffer identifier
binding_point_index INTEGER index of the binding point

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

bind_range

Binds a part of a GPU buffer object on a specific buffer binding point.

syntax

gh_gpu_buffer.bind_range (
gpubuff_id,
binding_point_index,
offset,
size
)

parameters

gpubuff_id ID gpu buffer identifier
binding_point_index INTEGER index of the binding point
offset INTEGER offset from the start of the buffer in bytes
size INTEGER size in bytes

return values

none

code sample

binding_point_index = 1
gh_gpu_buffer.bind_range(gpubuff_id, binding_point_index, 128, 256)

create

Creates a GPU buffer object.

syntax

gpubuff_id = gh_gpu_buffer.create (
buff_type,
buff_usage,
buff_size,
buff_states
)

parameters

buff_type ENUM( gpu_buffer_type ) type of the buffer: 'UNIFORM', 'SHADER_STORAGE', 'ATOMIC_COUNTER', etc.
buff_usage ENUM( gpu_buffer_usage ) usage based on OpenGL constants: 'GL_STATIC_DRAW', 'GL_DYNAMIC_READ', etc.
buff_size INTEGER size of the buffer in bytes
buff_states STRING reserved. Set it to ''

return values

gpubuff_id ID gpu buffer identifier

code sample

gpubuff_id = gh_gpu_buffer.create("SHADER_STORAGE", "GL_DYNAMIC_COPY", 256, "")

create_from_uniform_block

Creates an uniform buffer object from a shader uniform block description.

syntax

gpubuff_id = gh_gpu_buffer.create_from_uniform_block (
buff_usage,
gpuprog_id,
uniform_block_index,
buff_states
)

parameters

buff_usage ENUM( gpu_buffer_usage ) usage based on OpenGL constants: 'GL_STATIC_DRAW', 'GL_DYNAMIC_READ', etc.
gpuprog_id ID gpu program identifier
uniform_block_index INTEGER index of the uniform block in the shader. Use gh_gpu_program.get_interface_block_index() to get this index.
buff_states STRING reserved. Set it to ''

return values

gpubuff_id ID gpu buffer identifier

code sample

uniform_block_index = gh_gpu_program.get_interface_block_index(gpuprog_id, "UNIFORM", "CameraMatrix")

gpubuff_id = gh_gpu_buffer.create_from_uniform_block("GL_DYNAMIC_READ", gpuprog_id, uniform_block_index, "")

get_value_1f

Reads a 1D value from a GPU buffer.

syntax

x = gh_gpu_buffer.get_value_1f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x REAL value

code sample

x = gh_gpu_buffer.set_value_1f(gpubuff_id, offset)

get_value_2f

Reads a 2D value from a GPU buffer.

syntax

x, y = gh_gpu_buffer.get_value_2f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x, y REAL value

code sample

x, y = gh_gpu_buffer.set_value_2f(gpubuff_id, offset)

get_value_3f

Reads a 3D value from a GPU buffer.

syntax

x, y, z = gh_gpu_buffer.get_value_3f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x, y, z REAL value

code sample

x, y, z = gh_gpu_buffer.set_value_3f(gpubuff_id, offset)

get_value_4f

Reads a 4D value from a GPU buffer.

syntax

x, y, z, w = gh_gpu_buffer.get_value_4f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x, y, z, w REAL value

code sample

x, y, z, w = gh_gpu_buffer.set_value_4f(gpubuff_id, offset)

map

Maps a GPU buffer.

syntax

buffer, buff_size = gh_gpu_buffer.map (
gpubuff_id,
access_mode
)

parameters

gpubuff_id ID gpu buffer identifier
access_mode ENUM( gpu_buffer_access_mode_1 ) access mode based on OpenGL constants: 'GL_READ_WRITE', 'GL_WRITE_ONLY', 'GL_READ_ONLY'

return values

buffer POINTER memory buffer
buff_size INTEGER buffer size in bytes

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

buffer, buffer_size = gh_gpu_buffer.map(gpubuff_id, "GL_WRITE_ONLY")
... WriteSomething(buffer, buffer_size)
gh_gpu_buffer.unmap(gpubuff_id)

map_range

Maps a range of a GPU buffer.

syntax

buffer, buff_size = gh_gpu_buffer.map_range (
gpubuff_id,
offset,
size,
access_mode
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
size INTEGER size in bytes
access_mode ENUM( gpu_buffer_access_mode_2 ) access mode based on OpenGL constants: 'GL_MAP_READ_BIT', 'GL_MAP_WRITE_BIT', 'GL_MAP_INVALIDATE_RANGE_BIT', 'GL_MAP_INVALIDATE_BUFFER_BIT', etc

return values

buffer POINTER memory buffer
buff_size INTEGER buffer size in bytes

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

buffer, buffer_size = gh_gpu_buffer.map_range(gpubuff_id, 0, 256, "GL_MAP_WRITE_BIT GL_MAP_INVALIDATE_RANGE_BIT")
... WriteSomething(buffer, buffer_size)
gh_gpu_buffer.unmap(gpubuff_id)

set_matrix4x4

Writes a 4x4 matrix value to a GPU buffer.
The matrix comes from an object (camera, mesh, etc.).

syntax

gh_gpu_buffer.set_matrix4x4 (
gpubuff_id,
offset,
obj_id,
matrix_type
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
obj_id ID object identifier
matrix_type ENUM( gpu_buffer_matrix_type ) type of the matrix: 'camera_view_projection', 'camera_view', 'camera_inv_view', 'camera_projection', 'camera_inv_projection' 'object_local_tranform', 'object_global_tranform'

return values

none

code sample

gh_gpu_buffer.set_matrix4x4(gpubuff_id, offset, cam_id, "camera_view camera_projection")

set_value_1f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.set_value_1f (
gpubuff_id,
offset,
x
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x REAL value

return values

none

code sample

gh_gpu_buffer.set_value_1f(gpubuff_id, offset, x)

set_value_1ui

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.set_value_1ui (
gpubuff_id,
offset,
x
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x INTEGER value

return values

none

code sample

gh_gpu_buffer.set_value_1ui(gpubuff_id, 0, x)

set_value_1ui64_bindless_texture

Writes a value to a GPU buffer.
For bindless textures only.

syntax

gh_gpu_buffer.set_value_1ui64_bindless_texture (
gpubuff_id,
offset,
tex_id
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
tex_id ID bindless texture identifier

return values

none

code sample

gh_gpu_buffer.set_value_1ui64_bindless_texture(gpubuff_id, 0, tex_id)

set_value_2f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.set_value_2f (
gpubuff_id,
offset,
x, y
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x, y REAL value

return values

none

code sample

gh_gpu_buffer.set_value_2f(gpubuff_id, offset, x, y)

set_value_3f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.set_value_3f (
gpubuff_id,
offset,
x, y, z
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x, y, z REAL value

return values

none

code sample

gh_gpu_buffer.set_value_3f(gpubuff_id, offset, x, y, z)

set_value_4f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.set_value_4f (
gpubuff_id,
offset,
x, y, z, w
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x, y, z, w REAL value

return values

none

code sample

gh_gpu_buffer.set_value_4f(gpubuff_id, offset, x, y, z, w)

set_value_4x4f

Writes a value (a 4x4 matrix) to a GPU buffer.

syntax

gh_gpu_buffer.set_value_4x4f (
gpubuff_id,
offset,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

return values

none

code sample

gh_gpu_buffer.set_value_4x4f(gpubuff_id, offset, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

sub_data_read_1f

Reads a value from a GPU buffer.

syntax

x = gh_gpu_buffer.sub_data_read_1f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x REAL value

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

x = gh_gpu_buffer.sub_data_read_1f(gpubuff_id, 128)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_read_1ui

Reads a value from a GPU buffer.

syntax

x = gh_gpu_buffer.sub_data_read_1ui (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x INTEGER value

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

x = gh_gpu_buffer.sub_data_read_1ui(gpubuff_id, 4)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_read_2f

Reads a value from a GPU buffer.

syntax

x, y = gh_gpu_buffer.sub_data_read_2f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x, y REAL value

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

x, y = gh_gpu_buffer.sub_data_read_2f(gpubuff_id, 128)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_read_3f

Reads a value from a GPU buffer.

syntax

x, y, z = gh_gpu_buffer.sub_data_read_3f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x, y, z REAL value

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

x, y, z = gh_gpu_buffer.sub_data_read_3f(gpubuff_id, 128)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_read_4f

Reads a value from a GPU buffer.

syntax

x, y, z, w = gh_gpu_buffer.sub_data_read_4f (
gpubuff_id,
offset
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes

return values

x, y, z, w REAL value

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

x, y, z, w = gh_gpu_buffer.sub_data_read_4f(gpubuff_id, 128)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_write_1f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.sub_data_write_1f (
gpubuff_id,
offset,
x
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x REAL value

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

gh_gpu_buffer.sub_data_write_1f(gpubuff_id, 128, x)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_write_1ui

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.sub_data_write_1ui (
gpubuff_id,
offset,
x
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x INTEGER value

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

gh_gpu_buffer.sub_data_write_1ui(gpubuff_id, 4, x)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_write_2f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.sub_data_write_2f (
gpubuff_id,
offset,
x, y
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x, y REAL value

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

gh_gpu_buffer.sub_data_write_2f(gpubuff_id, 128, x, y)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_write_3f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.sub_data_write_3f (
gpubuff_id,
offset,
x, y, z
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x, y, z REAL value

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

gh_gpu_buffer.sub_data_write_3f(gpubuff_id, 128, x, y, z)

gh_gpu_buffer.unbind(gpubuff_id)

sub_data_write_4f

Writes a value to a GPU buffer.

syntax

gh_gpu_buffer.sub_data_write_4f (
gpubuff_id,
offset,
x, y, z, w
)

parameters

gpubuff_id ID gpu buffer identifier
offset INTEGER offset from the start of the buffer in bytes
x, y, z, w REAL value

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

gh_gpu_buffer.sub_data_write_4f(gpubuff_id, 128, x, y, z, w)

gh_gpu_buffer.unbind(gpubuff_id)

unbind

Unbinds a GPU buffer object.

syntax

gh_gpu_buffer.unbind (
gpubuff_id
)

parameters

gpubuff_id ID gpu buffer identifier

return values

none

code sample

gh_gpu_buffer.unbind(gpubuff_id)

unmap

Unmaps a GPU buffer.

syntax

gh_gpu_buffer.unmap (
gpubuff_id
)

parameters

gpubuff_id ID gpu buffer identifier

return values

none

code sample

gh_gpu_buffer.bind_base(gpubuff_id, 0)

gh_gpu_buffer.map(gpubuff_id, "GL_WRITE_ONLY")
... WriteSomething(gpubuff_id)
gh_gpu_buffer.unmap(gpubuff_id)

gh_gpu_program

GPU program module

gh_gpu_program is the module that manages GPU programs based on the GLSL language: creation, destruction, binding, uniforms settings.

add_shader_from_buffer

Adds a shader, specified by a memory buffer, to an existing GPU program, created by create_empty().

syntax

ret = gh_gpu_program.add_shader_from_buffer (
gpuprog_id,
buff_ptr,
buff_size,
shader_type
)

parameters

gpuprog_id ID gpu program identifier
buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
shader_type ENUM( gpu_program_shader_type ) type of shader (vertex, pixel, etc.)

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

-- shader types:
GPU_SHADER_VERTEX = 0
GPU_SHADER_PIXEL = 1
GPU_SHADER_GEOMETRY = 2
GPU_SHADER_TESS_CONTROL = 3
GPU_SHADER_TESS_EVAL = 4
GPU_SHADER_COMPUTE = 5

gpuprog_id = gh_gpu_program.create_empty("GPUProg01")

filename = demo_dir .. "assets/vertex_shader.txt"
buffer, buffer_size = gh_utils.file_buffer_create(filename)

gh_gpu_program.add_shader_from_buffer(gpuprog_id, buffer, buffer_size, GPU_SHADER_VERTEX)

gh_utils.file_buffer_kill(buffer)

filename = demo_dir .. "assets/pixel_shader.txt"
buffer, buffer_size = gh_utils.file_buffer_create(filename)

gh_gpu_program.add_shader_from_buffer(gpuprog_id, buffer, buffer_size, GPU_SHADER_PIXEL)

gh_utils.file_buffer_kill(buffer)

bind

Binds (makes it active) the GPU program to the renderer.
To unbind a GPU program, just pass 0 as gpu program identifier.

syntax

gh_gpu_program.bind (
gpuprog_id
)

parameters

gpuprog_id ID gpu program identifier

return values

none

code sample

gh_gpu_program.bind(gpuprog_id) -- Binding
...
gh_gpu_program.bind(0) -- Unbinding

create

Creates a GLSL program from vertex (vs), pixel (ps), geometry (gs), tessellation control and evaluation (tcs and tes) or compute (cs) shaders.

syntax

gpuprog_id = gh_gpu_program.create (
vs,
ps,
gs,
tcs,
tes,
cs
)

parameters

vs STRING vertex shader source code string
ps STRING pixel shader source code string
gs STRING geometry shader source code string
tcs STRING tessellation control shader source code string
tes STRING tessellation eval shader source code string
cs STRING compute shader source code string

return values

gpuprog_id ID gpu program identifier

code sample

vs = "......"
ps = "......"
gpuprog_id = gh_gpu_program.create(vs, ps, "", "", "", "")

create_empty

Creates an empty GPU program.

syntax

gpuprog_id = gh_gpu_program.create_empty (
program_name
)

parameters

program_name STRING name of the GPU program

return values

gpuprog_id ID gpu program identifier

code sample

gpuprog_id = gh_gpu_program.create_empty("GPUProg01")

create_from_file

Loads a GLSL source code from file (the file contains all shaders) and creates a new GPU program node.

syntax

gpuprog_id = gh_gpu_program.create_from_file (
filename,
absolute_path
)

parameters

filename STRING GPU program source code filename
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)

return values

gpuprog_id ID gpu program identifier

code sample

abs_path = 0 -- relative path
gpuprog_id = gh_gpu_program.create_from_file("data/shader.glsl", abs_path)

create_from_file_v3

Loads a GLSL source code from file (the file contains all shaders) and creates a new GPU program node.

syntax

gpuprog_id = gh_gpu_program.create_from_file_v3 (
program_name,
filename
)

parameters

program_name STRING name of the GPU program
filename STRING absolute path of the GPU program source code file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
gpuprog_id = gh_gpu_program.create_from_file_v3("LightingProg", demo_dir .. "./data/lighting_prog.glsl")

create_from_shader_files

Creates a GLSL program from separate shader files.

syntax

gpuprog_id = gh_gpu_program.create_from_shader_files (
program_name,
vs_filename,
ps_filename,
gs_filename,
tcs_filename,
tes_filename,
cs_filename
)

parameters

program_name STRING name of the GPU program
vs_filename STRING absolute path of the vertex shader file
ps_filename STRING absolute path of the pixel shader file
gs_filename STRING absolute path of the geometry shader file
tcs_filename STRING absolute path of the tessellation control shader file
tes_filename STRING absolute path of the tessellation eval shader file
cs_filename STRING absolute path of the compute shader file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
vs = demo_dir .. "./shaders/vs.txt"
ps = demo_dir .. "./shaders/ps.txt"
gpuprog_id = gh_gpu_program.create_from_shader_files("LightingProg", vs, ps, "", "", "", "")

create_from_shader_files_gl_smolv

opengl

Creates a GPU program for OpenGL from SMOL-V (compressed SPIR-V) module files.
The name of the entry point of SPIR-V modules must be 'main'.

syntax

gpuprog_id = gh_gpu_program.create_from_shader_files_gl_smolv (
program_name,
vs_fname,
ps_fname,
gs_fname,
tcs_fname,
tes_fname,
cs_fname
)

parameters

program_name STRING name of the GPU program
vs_fname STRING vertex shader: absolute path of the SMOL-V file
ps_fname STRING pixel shader: absolute path of the SMOL-V file
gs_fname STRING geometry shader: absolute path of the SMOL-V file
tcs_fname STRING tessellation control shader: absolute path of the SMOL-V file
tes_fname STRING tessellation eval shader: absolute path of the SMOL-V file
cs_fname STRING compute shader: absolute path of the SMOL-V file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
vs = demo_dir .. "./shaders/vs.spv"
ps = demo_dir .. "./shaders/ps.spv"
gs = ""
tcs = ""
tes = ""
cs = ""
gpuprog_id = gh_gpu_program.create_from_shader_files_gl_smolv("prog", vs, ps, gs, tcs, tes, cs)

create_from_shader_files_gl_spirv

opengl

Creates a GPU program for OpenGL from SPIR-V module files.
The name of the entry point of SPIR-V modules must be 'main'.

syntax

gpuprog_id = gh_gpu_program.create_from_shader_files_gl_spirv (
program_name,
vs_fname,
ps_fname,
gs_fname,
tcs_fname,
tes_fname,
cs_fname
)

parameters

program_name STRING name of the GPU program
vs_fname STRING vertex shader: absolute path of the SPIR-V file
ps_fname STRING pixel shader: absolute path of the SPIR-V file
gs_fname STRING geometry shader: absolute path of the SPIR-V file
tcs_fname STRING tessellation control shader: absolute path of the SPIR-V file
tes_fname STRING tessellation eval shader: absolute path of the SPIR-V file
cs_fname STRING compute shader: absolute path of the SPIR-V file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
vs = demo_dir .. "./shaders/vs.spv"
ps = demo_dir .. "./shaders/ps.spv"
gs = ""
tcs = ""
tes = ""
cs = ""
gpuprog_id = gh_gpu_program.create_from_shader_files_gl_spirv("prog", vs, ps, gs, tcs, tes, cs)

create_from_zip_file

Creates a GLSL program from separate shader files stored in a zip file.

syntax

gpuprog_id = gh_gpu_program.create_from_zip_file (
zip_filename,
program_name,
vs_filename,
ps_filename,
gs_filename,
tcs_filename,
tes_filename,
cs_filename
)

parameters

zip_filename STRING absolute path of the zip file
program_name STRING name of the GPU program
vs_filename STRING absolute path of the vertex shader file
ps_filename STRING absolute path of the pixel shader file
gs_filename STRING absolute path of the geometry shader file
tcs_filename STRING absolute path of the tessellation control shader file
tes_filename STRING absolute path of the tessellation eval shader file
cs_filename STRING absolute path of the compute shader file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
local zip_filename = demo_dir .. "demo.zip"

vs = "shaders/vs.txt"
ps = "shaders/ps.txt"

gpuprog_id = gh_gpu_program.create_from_zip_file(zip_filename, "LightingProg", vs, ps, "", "", "", "")

create_from_zip_file_gl_spirv

opengl

Creates a GPU program for OpenGL from SPIR-V module files in a zip archive.
The name of the entry point of SPIR-V modules must be 'main'.

syntax

gpuprog_id = gh_gpu_program.create_from_zip_file_gl_spirv (
zip_fname,
program_name,
vs_fname,
ps_fname,
gs_fname,
tcs_fname,
tes_fname,
cs_fname
)

parameters

zip_fname STRING absolute path to the zip file
program_name STRING name of the GPU program
vs_fname STRING vertex shader: path of the SPIR-V file in the zip archive
ps_fname STRING pixel shader: path of the SPIR-V file in the zip archive
gs_fname STRING geometry shader: path of the SPIR-V file in the zip archive
tcs_fname STRING tessellation control shader: path of the SPIR-V file in the zip archive
tes_fname STRING tessellation eval shader: path of the SPIR-V file in the zip archive
cs_fname STRING compute shader: path of the SPIR-V file in the zip archive

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
zip_fname = demo_dir .. "data.zip"
vs = demo_dir .. "./shaders/vs.spv"
ps = demo_dir .. "./shaders/ps.spv"
gs = ""
tcs = ""
tes = ""
cs = ""
gpuprog_id = gh_gpu_program.create_from_shader_files_gl_spirv(zip_fname, "prog", vs, ps, gs, tcs, tes, cs)

create_gl_spirv

opengl

Creates a GPU program for OpenGL from SPIR-V modules.
The name of the entry point of SPIR-V modules must be 'main'.

syntax

gpuprog_id = gh_gpu_program.create_gl_spirv (
program_name,
vs,
ps,
gs,
tcs,
tes,
cs
)

parameters

program_name STRING name of the GPU program
vs STRING vertex shader source code
ps STRING pixel shader source code
gs STRING geometry shader source code
tcs STRING tessellation control shader source code
tes STRING tessellation eval shader source code
cs STRING compute shader source code

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()

vs = "void main(){ ... }"
ps = "void main(){ ... }"
gs = ""
tcs = ""
tes = ""
cs = ""
gpuprog_id = gh_gpu_program.create_gl_spirv("prog", vs, ps, gs, tcs, tes, cs)

create_mesh_task_from_shader_files

Creates a GLSL mesh shader program from separate mesh/task shader files.

syntax

gpuprog_id = gh_gpu_program.create_mesh_task_from_shader_files (
program_name,
ms_filename,
ts_filename,
ps_filename
)

parameters

program_name STRING name of the GPU program
ms_filename STRING absolute path of the mesh shader file
ts_filename STRING absolute path of the task shader file
ps_filename STRING absolute path of the pixel shader file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
vs = demo_dir .. "./shaders/ms.txt"
ps = demo_dir .. "./shaders/ps.txt"
mesh_prog = gh_gpu_program.create_mesh_task_from_shader_files("MeshProg", ms, "", ps)

create_mesh_task_from_shader_files_gl_spirv

opengl

Creates a GPU mesh shader program for OpenGL from SPIR-V module files.
The name of the entry point of SPIR-V modules must be 'main'.

syntax

gpuprog_id = gh_gpu_program.create_mesh_task_from_shader_files_gl_spirv (
program_name,
ms_fname,
ts_fname,
ps_fname
)

parameters

program_name STRING name of the GPU program
ms_fname STRING mesh shader: absolute path of the SPIR-V file
ts_fname STRING task shader: absolute path of the SPIR-V file
ps_fname STRING pixel shader: absolute path of the SPIR-V file

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
ms = demo_dir .. "./shaders/ms.spv"
ps = demo_dir .. "./shaders/ps.spv"
ts = ""
meshprog = gh_gpu_program.create_mesh_task_from_shader_files_gl_spirv("prog", ms, ts, ps)

create_v2

Creates a GLSL program from vertex (vs), pixel (ps), geometry (gs), tessellation control (tcs), evaluation (tes) or compute (cs) shaders.
All these shaders are memory buffers.

syntax

gpuprog_id = gh_gpu_program.create_v2 (
program_name,
vs,
ps,
gs,
tcs,
tes,
cs
)

parameters

program_name STRING name of the GPU program
vs STRING vertex shader source code string
ps STRING pixel shader source code string
gs STRING geometry shader source code string
tcs STRING tessellation control shader source code string
tes STRING tessellation eval shader source code string
cs STRING compute shader source code string

return values

gpuprog_id ID gpu program identifier

code sample

vs = "......"
ps = "......"
gpuprog_id = gh_gpu_program.create_v2("LightingProg", vs, ps, "", "", "", "")

get_interface_block_index

Gets the index of an interface block.

syntax

block_index = gh_gpu_program.get_interface_block_index (
gpuprog_id,
block_type,
block_name
)

parameters

gpuprog_id ID gpu program identifier
block_type ENUM( gpu_buffer_type ) type of the block: 'UNIFORM', 'SHADER_STORAGE'
block_name STRING name of the block

return values

block_index INTEGER block index

code sample

index = gh_gpu_program.get_interface_block_index(gpuprog_id, "UNIFORM", "CameraMatrix")

get_uniform_array_stride

Gets the stride in bytes of an array inside an uniform block.

syntax

stride = gh_gpu_program.get_uniform_array_stride (
gpuprog_id,
variable_name
)

parameters

gpuprog_id ID gpu program identifier
variable_name STRING name of the variable

return values

stride INTEGER stride in bytes

code sample

stride = gh_gpu_program.get_uniform_array_stride(gpuprog_id, "positions")

get_uniform_block_size

Gets the size in bytes of an uniform block.

syntax

block_size = gh_gpu_program.get_uniform_block_size (
gpuprog_id,
block_index
)

parameters

gpuprog_id ID gpu program identifier
block_index INTEGER block index

return values

block_size INTEGER block size in bytes

code sample

index = gh_gpu_program.get_interface_block_index(gpuprog_id, "UNIFORM", "CameraMatrix")
size = gh_gpu_program.get_uniform_block_size(gpuprog_id, index)

get_uniform_size_and_offset

Gets the size and offset in bytes of a variable inside an uniform block.

syntax

size, offset = gh_gpu_program.get_uniform_size_and_offset (
gpuprog_id,
variable_name
)

parameters

gpuprog_id ID gpu program identifier
variable_name STRING name of the variable

return values

size, offset INTEGER size and offset in bytes

code sample

size, offset = gh_gpu_program.get_uniform_size_and_offset(gpuprog_id, "positions")

get_vertex_attrib_name

Gets the name of a vertex attribute.

syntax

name = gh_gpu_program.get_vertex_attrib_name (
gpuprog_id,
vertex_index
)

parameters

gpuprog_id ID gpu program identifier
vertex_index INTEGER vertex attribute index

return values

name STRING vertex attrib name

code sample

gh_gpu_program.bind(gpuprog_id)
name = gh_gpu_program.get_vertex_attrib_name(gpuprog_id, 0)

run_compute

Runs a compute program (OpenGL 4.3+ feature).
Based on GL_ARB_compute_shader.

syntax

gh_gpu_program.run_compute (
gpuprog_id,
num_groups_x, num_groups_y, num_groups_z
)

parameters

gpuprog_id ID gpu program identifier
num_groups_x, num_groups_y, num_groups_z INTEGER specifies the number of local work groups that will be dispatched in the X, Y and Z dimensions

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.run_compute(gpuprog_id, 16, 16, 16)

run_compute_group_size

Runs a compute program (OpenGL 4.3+ feature) and allows the specification of group size.

syntax

gh_gpu_program.run_compute_group_size (
gpuprog_id,
num_groups_x, num_groups_y, num_groups_z,
work_group_size_x, work_group_size_y, work_group_size_z
)

parameters

gpuprog_id ID gpu program identifier
num_groups_x, num_groups_y, num_groups_z INTEGER specifies the number of local work groups that will be dispatched in the X, Y and Z dimensions
work_group_size_x, work_group_size_y, work_group_size_z INTEGER specifies the work group size in the X, Y and Z dimensions

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.run_compute_group_size(gpuprog_id, num_groups_x, num_groups_y, num_groups_z, work_group_size_x, work_group_size_y, work_group_size_z)

set_livecoding_state

Sets the live coding from file state.
If state is 1, you can edit the shader in any text editor and instantly see the effects in GeeXLab.

syntax

gh_gpu_program.set_livecoding_state (
gpuprog_id,
shader_type,
state
)

parameters

gpuprog_id ID gpu program identifier
shader_type ENUM( gpu_program_shader_type ) type of shader (vertex, pixel, etc.)
state BOOLEAN live coding: 1 (enabled) or 0 (disabled)

return values

none

code sample

GPU_SHADER_VERTEX = 0
GPU_SHADER_PIXEL = 1
GPU_SHADER_GEOMETRY = 2
GPU_SHADER_TESS_CONTROL = 3
GPU_SHADER_TESS_EVAL = 4
GPU_SHADER_COMPUTE = 5

shader_type = GPU_SHADER_PIXEL
state = 1
gh_gpu_program.set_livecoding_state(gpuprog_id, shader_type, state)

set_shader_storage_block_binding

Sets the buffer binding point of a shader storage block.

syntax

gh_gpu_program.set_shader_storage_block_binding (
gpuprog_id,
block_index,
binding_point_index
)

parameters

gpuprog_id ID gpu program identifier
block_index INTEGER block index
binding_point_index INTEGER index of a GPU buffer binding point

return values

none

code sample

gh_gpu_program.set_shader_storage_block_binding(gpuprog_id, index, 3)

set_uniform_block_binding

Sets the buffer binding point of an uniform block.

syntax

gh_gpu_program.set_uniform_block_binding (
gpuprog_id,
block_index,
binding_point_index
)

parameters

gpuprog_id ID gpu program identifier
block_index INTEGER block index
binding_point_index INTEGER index of a GPU buffer binding point

return values

none

code sample

gh_gpu_program.set_uniform_block_binding(gpuprog_id, index, 2)

set_vertex_attrib_name

Sets the name of a vertex attribute.

syntax

gh_gpu_program.set_vertex_attrib_name (
gpuprog_id,
vertex_index,
name
)

parameters

gpuprog_id ID gpu program identifier
vertex_index INTEGER vertex attribute index
name STRING vertex attrib name

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.set_vertex_attrib_name(gpuprog_id, 0, "gxl3d_Position")

uniform1d

Sets the value of an FP64 uniform variable.

syntax

gh_gpu_program.uniform1d (
gpuprog_id,
uniform_name,
x
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1d(gpuprog_id, "r", 0.25)

uniform1f

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform1f (
gpuprog_id,
uniform_name,
x
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x REAL uniform value

return values

none

code sample

elapsed_time = gh_utils.get_elapsed_time()

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1f(gpuprog_id, "time", elapsed_time)

uniform1fv

lua

Sets the value of an uniform array.

syntax

gh_gpu_program.uniform1fv (
gpuprog_id,
uniform_name,
array_count,
array
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
array_count INTEGER number of entries of the uniform array
array TABLE uniform array

return values

none

code sample

temperatures = {}
temperatures[1] = 20.0
temperatures[2] = 21.0
temperatures[3] = 24.0
temperatures[4] = 29.0

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1fv(gpuprog_id, "temperatures", 4, temperatures)

uniform1i

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform1i (
gpuprog_id,
uniform_name,
x
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x INTEGER uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1i(gpuprog_id, "index", 2)

uniform1iv

Sets the value of an uniform array.

syntax

gh_gpu_program.uniform1iv (
gpuprog_id,
uniform_name,
array_count,
array
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
array_count INTEGER number of entries of the uniform array
array TABLE uniform array

return values

none

code sample

material_ids = {}

InitMaterialIDs(material_ids)

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1iv(gpuprog_id, "material_ids", material_ids, 10)

uniform1ui64

Sets the value of an uniform variable.
Useful with bindless texture (OpenGL 4.4).

syntax

gh_gpu_program.uniform1ui64 (
gpuprog_id,
uniform_name,
x
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x INTEGER uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1ui64(gpuprog_id, "tex", bindless_texture_handle)

uniform1ui64v

lua

Sets the value of an uniform array.
Useful with bindless texture (OpenGL 4.4).

syntax

gh_gpu_program.uniform1ui64v (
gpuprog_id,
uniform_name,
array_count,
array
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
array_count INTEGER number of entries of the uniform array
array TABLE uniform array

return values

none

code sample

all_texture_handles = {}

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1ui64v(gpuprog_id, "all_textures", 32, all_texture_handles)

uniform2d

Sets the value of an FP64 uniform variable.

syntax

gh_gpu_program.uniform2d (
gpuprog_id,
uniform_name,
x, y
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform2d(gpuprog_id, "rg", 0.25, 0.22)

uniform2f

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform2f (
gpuprog_id,
uniform_name,
x, y
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform2f(gpuprog_id, "uv", 0.1, 1.0)

uniform2fv

Sets the value of an uniform array.

syntax

gh_gpu_program.uniform2fv (
gpuprog_id,
uniform_name,
array_count,
array
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
array_count INTEGER number of entries of the uniform array
array TABLE uniform array (lua: array - Python: list). In Lua, each element must be: {x=..., y=...}. In Python, each element is a tuple: (0.25, 0.59)

return values

none

code sample

uv = {}  
uv[1]={x=0, y=0}
uv[2]={x=0.2, y=0}
uv[3]={x=0.4, y=0.2}
uv[4]={x=0.6, y=0.25}
uv[5]={x=0.8, y=0.5}

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform2fv(gpuprog_id, "uv", 5, uv)

uniform2i

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform2i (
gpuprog_id,
uniform_name,
x, y
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y INTEGER uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform2i(gpuprog_id, "rg", 250, 25)

uniform3d

Sets the value of an FP64 uniform variable.

syntax

gh_gpu_program.uniform3d (
gpuprog_id,
uniform_name,
x, y, z
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform3d(gpuprog_id, "rgb", 0.25, 0.25, 0.45)

uniform3f

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform3f (
gpuprog_id,
uniform_name,
x, y, z
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform3f(gpuprog_id, "rgb", 0.25, 0.25, 0.45)

uniform3fv

Sets the value of an uniform array.

syntax

gh_gpu_program.uniform3fv (
gpuprog_id,
uniform_name,
array_count,
array
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
array_count INTEGER number of entries of the uniform array
array TABLE uniform array (lua: array - Python: list). In Lua, each element must be: {x=..., y=..., z=...}. In Python, each element is a tuple: (0.25, 0.59, 0.0)

return values

none

code sample

xyz = {} -- array element: {x=0, y=0, z=0}

InitXYZ(xyz)

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform3fv(gpuprog_id, "xyz", 10, xyz)

uniform3i

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform3i (
gpuprog_id,
uniform_name,
x, y, z
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z INTEGER uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform3i(gpuprog_id, "rgb", 250, 25, 45)

uniform4d

Sets the value of an FP64 uniform variable.

syntax

gh_gpu_program.uniform4d (
gpuprog_id,
uniform_name,
x, y, z, w
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z, w REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform4d(gpuprog_id, "rgba", 0.25, 0.25, 0.45, 1.0)

uniform4f

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform4f (
gpuprog_id,
uniform_name,
x, y, z, w
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z, w REAL uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform4f(gpuprog_id, "rgba", 0.25, 0.25, 0.45, 1.0)

uniform4f_array

Sets the value of an uniform array of vec4.
Currently limited to one vec4.

syntax

gh_gpu_program.uniform4f_array (
gpuprog_id,
uniform_name,
x, y, z, w
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z, w REAL Uniform value. The four elements of an uniform array: float xyzw[4]

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform4f_array(gpuprog_id, "all_params", 0.2, 10.4, 0.003, 0.001)

uniform4fv

Sets the value of an uniform array.

syntax

gh_gpu_program.uniform4fv (
gpuprog_id,
uniform_name,
array_count,
array
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
array_count INTEGER number of entries of the uniform array
array TABLE uniform array (lua: array - Python: list). In Lua, each element must be: {x=..., y=..., z=..., w=...}. In Python, each element is a tuple: (0.25, 0.59, 0.0, 1.0)

return values

none

code sample

xyzw = {} -- array element: {x=0, y=0, z=0, w=0}

InitXYZW(xyzw)

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform4fv(gpuprog_id, "xyzw", 10, xyzw)

uniform4i

Sets the value of an uniform variable.

syntax

gh_gpu_program.uniform4i (
gpuprog_id,
uniform_name,
x, y, z, w
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z, w INTEGER uniform value

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform4i(gpuprog_id, "rgba", 250, 25, 45, 100)

uniform4i_array

Sets the value of an uniform array of vec4i.
Currently limited to one vec4i.

syntax

gh_gpu_program.uniform4i_array (
gpuprog_id,
uniform_name,
x, y, z, w
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
x, y, z, w INTEGER Uniform value. The four elements of an uniform array: int xyzw[4]

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform4i_array(gpuprog_id, "all_textures", 0, 1, 2, 3)

uniform_3x3f

Sets a 3x3 matrix uniform.

syntax

gh_gpu_program.uniform_3x3f (
gpuprog_id,
uniform_name,
m0,m1,m2,m3,m4,m5,m6,m7,m8
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
m0,m1,m2,m3,m4,m5,m6,m7,m8 REAL the 9 floats that make the 3x3 matrix

return values

none

code sample

gh_gpu_program.uniform_3x3f(gpuprog_id, "rotMatrix", m0,m1,m2,m3,m4,m5,m6,m7,m8)

uniform_4x4f

Sets a 4x4 matrix uniform.

syntax

gh_gpu_program.uniform_4x4f (
gpuprog_id,
uniform_name,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

gpuprog_id ID gpu program identifier
uniform_name STRING uniform name
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

return values

none

code sample

gh_gpu_program.uniform_4x4f(gpuprog_id, "myMatrix", m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

uniform_camera_matrices

Sets the matrices of a camera as uniforms.

syntax

gh_gpu_program.uniform_camera_matrices (
gpuprog_id,
cam_id,
uniform_name_view_mat,
uniform_name_proj_mat
)

parameters

gpuprog_id ID gpu program identifier
cam_id ID camera identifier
uniform_name_view_mat STRING name of the view matrix
uniform_name_proj_mat STRING name of the projection matrix

return values

none

code sample

gh_gpu_program.uniform_camera_matrices(gpuprog_id, camera, "ViewMat", "ProjMat")

uniform_camera_matrices_v2

Sets the matrices of a camera as uniforms.

syntax

gh_gpu_program.uniform_camera_matrices_v2 (
gpuprog_id,
cam_id,
uniform_name_view_mat,
uniform_name_proj_mat,
uniform_name_viewproj_mat
)

parameters

gpuprog_id ID gpu program identifier
cam_id ID camera identifier
uniform_name_view_mat STRING name of the view matrix
uniform_name_proj_mat STRING name of the projection matrix
uniform_name_viewproj_mat STRING name of the view projection matrix

return values

none

code sample

gh_gpu_program.uniform_camera_matrices_v2(gpuprog_id, camera, "ViewMat", "ProjMat", "ViewProjMat")

uniform_matrix

Sets an uniform 4x4 matrix (mat4 in GLSL) built from the transformation matrix of an object (camera, mesh, etc.).

syntax

gh_gpu_program.uniform_matrix (
gpuprog_id,
object_id,
uniform_name,
matrix_type,
upload_to_gpu
)

parameters

gpuprog_id ID gpu program identifier
object_id ID object identifier
uniform_name STRING name of the uniform 4x4 matrix
matrix_type INTEGER type of the matrix: 'camera_view_projection', 'camera_view', 'camera_inv_view', 'camera_projection', 'camera_inv_projection' 'object_local_tranform', 'object_global_tranform'
upload_to_gpu INTEGER If 1, the uniform value is immedialtly uploaded to the GPU. If 0, the value will be uploaded later during the rendering.

return values

none

code sample

gh_gpu_program.uniform_matrix(gpuprog_id, camera_id, "ViewMatrix", "camera_view")
gh_gpu_program.uniform_matrix(gpuprog_id, camera_id, "ProjMatrix", "camera_projection")
gh_gpu_program.uniform_matrix(gpuprog_id, object_id, "ModelMatrix", "object_global_tranform")

uniform_modelviewproj_matrices

Sets the ModelViewProjection and ModelView matrices from a camera and an object.

syntax

gh_gpu_program.uniform_modelviewproj_matrices (
gpuprog_id,
cam_id,
obj_id,
uniform_name_modelviewproj_mat,
uniform_name_modelview_mat
)

parameters

gpuprog_id ID gpu program identifier
cam_id ID camera identifier
obj_id ID object identifier
uniform_name_modelviewproj_mat STRING name of the model view projection matrix
uniform_name_modelview_mat STRING name of the model view matrix

return values

none

code sample

gh_gpu_program.uniform_modelviewproj_matrices(gpuprog_id, camera, mesh, "ModelViewProj", "ModelView")

uniform_object_matrix

Sets the local matrix of an object as uniform.

syntax

gh_gpu_program.uniform_object_matrix (
gpuprog_id,
obj_id,
uniform_name_mat
)

parameters

gpuprog_id ID gpu program identifier
obj_id ID object identifier
uniform_name_mat STRING name of the uniform variable

return values

none

code sample

gh_gpu_program.uniform_object_matrix(gpuprog_id, object, "ModelMat")

uniform_subroutine

Sets the matrices of a camera as uniforms.

syntax

gh_gpu_program.uniform_subroutine (
gpuprog_id,
shader_type,
subroutine_uniform_name,
subroutine_name
)

parameters

gpuprog_id ID gpu program identifier
shader_type ENUM( gpu_program_shader_type ) type of shader (vertex, pixel, etc.)
subroutine_uniform_name STRING uniform name of the subroutine
subroutine_name STRING name of the real subroutine

return values

none

code sample

GPU_SHADER_VERTEX = 0
GPU_SHADER_PIXEL = 1
GPU_SHADER_GEOMETRY = 2
GPU_SHADER_TESS_CONTROL = 3
GPU_SHADER_TESS_EVAL = 4
GPU_SHADER_COMPUTE = 5

gh_gpu_program.uniform_subroutine(gpuprog_id, GPU_SHADER_PIXEL, "Color", "ColorBlue")

uniform_transform_matrix_v1

Builds a matrix from position, rotation and scale and passes this matrix to the shader.

syntax

gh_gpu_program.uniform_transform_matrix_v1 (
gpuprog_id,
uniform_matrix_name,
posx, posy, posz,
pitch, yaw, roll,
sx, sy, sz,
transform_order
)

parameters

gpuprog_id ID gpu program identifier
uniform_matrix_name STRING name of the uniform variable
posx, posy, posz REAL 3D position
pitch, yaw, roll REAL Euler angles in degrees
sx, sy, sz REAL 3D scale
transform_order INTEGER order of transformation to build the matrix: 0 (ORDER_TRS - default), 1 (ORDER_RTS), 2 (ORDER_TSR) or 3 (ORDER_RST)

return values

none

code sample

local transform_order = 0
gh_gpu_program.uniform_transform_matrix_v1(gpuprog_id, "ModelMatrix", posx, posy, posz, pitch, yaw, roll, sx, sy, sz, transform_order)

uniform_transform_matrix_v2

Builds a matrix from position, rotation and scale and passes this matrix to the shader.

syntax

gh_gpu_program.uniform_transform_matrix_v2 (
gpuprog_id,
uniform_matrix_name,
posx, posy, posz,
qx, qy, qz, qw,
sx, sy, sz,
transform_order
)

parameters

gpuprog_id ID gpu program identifier
uniform_matrix_name STRING name of the uniform variable
posx, posy, posz REAL 3D position
qx, qy, qz, qw REAL Orientation quaternion
sx, sy, sz REAL 3D scale
transform_order INTEGER order of transformation to build the matrix: 0 (ORDER_TRS - default), 1 (ORDER_RTS), 2 (ORDER_TSR) or 3 (ORDER_RST)

return values

none

code sample

local transform_order = 0
gh_gpu_program.uniform_transform_matrix_v1(gpuprog_id, "ModelMatrix", posx, posy, posz, qx, qy, qz, qw, sx, sy, sz, transform_order)

update_shader_from_file

Updates an shader of an existing GPU program.

syntax

gh_gpu_program.update_shader_from_file (
gpuprog_id,
filename,
is_abs_path,
shader_type
)

parameters

gpuprog_id ID gpu program identifier
filename STRING shader filename
is_abs_path INTEGER filename is specified with an absolute (1) or relative (0) path
shader_type STRING type of shader: vertex, pixel, geometry, tess_control, tess_eval, compute, mesh, task)

return values

none

code sample

gh_gpu_program.update_shader_from_file(gpuprog_id, "data/ps.txt", 0, "pixel")

update_shader_from_memory

Updates an shader of an existing GPU program.

syntax

gh_gpu_program.update_shader_from_memory (
gpuprog_id,
shader_code,
shader_type
)

parameters

gpuprog_id ID gpu program identifier
shader_code STRING shader code (a string)
shader_type STRING type of shader: vertex, pixel, geometry, tess_control, tess_eval, compute, mesh, task)

return values

none

code sample

pixel_shader = "....."
gh_gpu_program.update_shader_from_memory(gpuprog_id, pixel_shader, "pixel")

vk_add_spirv_module_file

vulkan

Adds a SPIR-V module from a regular file to an existing GPU program.

syntax

gh_gpu_program.vk_add_spirv_module_file (
gpuprog_id,
filename,
entry_point,
shader_type
)

parameters

gpuprog_id ID gpu program identifier
filename STRING filename of the SPIR-V module
entry_point STRING entry point of the SPIR-V module. Usually main.
shader_type INTEGER type of the shader: vertex, pixel, tessellation, geometry, raygen, etc.

return values

none

code sample

demo_dir = gh_utils.get_demo_dir()

filename_vs = demo_dir .. "./spirv/vs.spv"
filename_ps = demo_dir .. "./spirv/ps.spv"

GPU_SHADER_VERTEX = 0
GPU_SHADER_PIXEL = 1
GPU_SHADER_GEOMETRY = 2
GPU_SHADER_TESS_CONTROL = 3
GPU_SHADER_TESS_EVAL = 4
GPU_SHADER_COMPUTE = 5
GPU_SHADER_MESH_NV = 6
GPU_SHADER_TASK_NV = 7
GPU_SHADER_RT_RAYGEN = 8
GPU_SHADER_RT_ANY_HIT = 9
GPU_SHADER_RT_CLOSEST_HIT = 10
GPU_SHADER_RT_MISS = 11
GPU_SHADER_RT_INTERSECTION = 12

prog = gh_gpu_program.create_empty("gpu_prog") 
gh_gpu_program.vk_add_spirv_module_file(prog, filename_vs, "main", GPU_SHADER_VERTEX)
gh_gpu_program.vk_add_spirv_module_file(prog, filename_ps, "main", GPU_SHADER_PIXEL)

vk_add_spirv_module_zip

vulkan

Adds a SPIR-V module (from a zip file) to an existing GPU program.

syntax

gh_gpu_program.vk_add_spirv_module_zip (
zip_filename,
gpuprog_id,
filename,
entry_point,
shader_type
)

parameters

zip_filename STRING filename of the zip archive
gpuprog_id ID gpu program identifier
filename STRING filename of the SPIR-V module in the zip archive
entry_point STRING entry point of the SPIR-V module. Usually main.
shader_type INTEGER type of the shader: vertex, pixel, tessellation, geometry, raygen, etc.

return values

none

code sample

demo_dir = gh_utils.get_demo_dir()
zip_filename = demo_dir .. "data.zip"

filename_vs = "spirv/vs.spv"
filename_ps = "spirv/ps.spv"

GPU_SHADER_VERTEX = 0
GPU_SHADER_PIXEL = 1
GPU_SHADER_GEOMETRY = 2
GPU_SHADER_TESS_CONTROL = 3
GPU_SHADER_TESS_EVAL = 4
GPU_SHADER_COMPUTE = 5
GPU_SHADER_MESH_NV = 6
GPU_SHADER_TASK_NV = 7
GPU_SHADER_RT_RAYGEN = 8
GPU_SHADER_RT_ANY_HIT = 9
GPU_SHADER_RT_CLOSEST_HIT = 10
GPU_SHADER_RT_MISS = 11
GPU_SHADER_RT_INTERSECTION = 12

prog = gh_gpu_program.create_empty("gpu_prog") 
gh_gpu_program.vk_add_spirv_module_zip(zip_filename, prog, filename_vs, "main", GPU_SHADER_VERTEX)
gh_gpu_program.vk_add_spirv_module_zip(zip_filename, prog, filename_ps, "main", GPU_SHADER_PIXEL)

vk_create_from_smolv_module_file

vulkan

Creates a Vulkan GPU program from SMOL-V (compressed SPIR-V) modules.

syntax

gpuprog_id = gh_gpu_program.vk_create_from_smolv_module_file (
program_name,
vs_fname, vs_entry_point,
ps_fname, ps_entry_point,
gs_fname, gs_entry_point,
tcs_fname, tcs_entry_point,
tes_fname, tes_entry_point,
cs_fname, cs_entry_point
)

parameters

program_name STRING name of the GPU program
vs_fname, vs_entry_point STRING vertex shader: absolute path of the shader file, entry point name
ps_fname, ps_entry_point STRING pixel shader: ...
gs_fname, gs_entry_point STRING geometry shader: ...
tcs_fname, tcs_entry_point STRING tessellation control shader: ...
tes_fname, tes_entry_point STRING tessellation eval shader: ...
cs_fname, cs_entry_point STRING compute shader: ...

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()

vs = demo_dir .. "./shaders/vs.spv"
ps = demo_dir .. "./shaders/ps.spv"

gpuprog_id = gh_gpu_program.vk_create_from_smolv_module_file("LightingProg", vs,"main", ps,"main", "","", "","", "","", "","")

vk_create_from_spirv_module_file

vulkan

Creates a Vulkan GPU program from SPIR-V modules.

syntax

gpuprog_id = gh_gpu_program.vk_create_from_spirv_module_file (
program_name,
vs_fname, vs_entry_point,
ps_fname, ps_entry_point,
gs_fname, gs_entry_point,
tcs_fname, tcs_entry_point,
tes_fname, tes_entry_point,
cs_fname, cs_entry_point
)

parameters

program_name STRING name of the GPU program
vs_fname, vs_entry_point STRING vertex shader: absolute path of the shader file, entry point name
ps_fname, ps_entry_point STRING pixel shader: ...
gs_fname, gs_entry_point STRING geometry shader: ...
tcs_fname, tcs_entry_point STRING tessellation control shader: ...
tes_fname, tes_entry_point STRING tessellation eval shader: ...
cs_fname, cs_entry_point STRING compute shader: ...

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()

vs = demo_dir .. "./shaders/vs.spv"
ps = demo_dir .. "./shaders/ps.spv"

gpuprog_id = gh_gpu_program.vk_create_from_spirv_module_file("LightingProg", vs,"main", ps,"main", "","", "","", "","", "","")

vk_create_from_spirv_module_zip

vulkan

Creates a Vulkan GPU program from SPIR-V modules stored in a zip archive.

syntax

gpuprog_id = gh_gpu_program.vk_create_from_spirv_module_zip (
zip_filename,
program_name,
vs_fname, vs_entry_point,
ps_fname, ps_entry_point,
gs_fname, gs_entry_point,
tcs_fname, tcs_entry_point,
tes_fname, tes_entry_point,
cs_fname, cs_entry_point
)

parameters

zip_filename STRING absolute path to the zip archive
program_name STRING name of the GPU program
vs_fname, vs_entry_point STRING vertex shader: absolute path of the shader file, entry point name
ps_fname, ps_entry_point STRING pixel shader: ...
gs_fname, gs_entry_point STRING geometry shader: ...
tcs_fname, tcs_entry_point STRING tessellation control shader: ...
tes_fname, tes_entry_point STRING tessellation eval shader: ...
cs_fname, cs_entry_point STRING compute shader: ...

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()

zipfile = demo_dir .. "data.zip"

vs = "shaders/vs.spv"
ps = "shaders/ps.spv"

gpuprog_id = gh_gpu_program.vk_create_from_spirv_module_zip(zipfile, "LightingProg", vs,"main", ps,"main", "","", "","", "","", "","")

vk_create_mesh_task_from_spirv_module_file

vulkan

Creates a Vulkan GPU mesh shader program from SPIR-V modules.

syntax

gpuprog_id = gh_gpu_program.vk_create_mesh_task_from_spirv_module_file (
program_name,
ms_fname, ms_entry_point,
ts_fname, ts_entry_point,
ps_fname, ps_entry_point
)

parameters

program_name STRING name of the GPU program
ms_fname, ms_entry_point STRING mesh shader: absolute path of the shader file, entry point name
ts_fname, ts_entry_point STRING task shader: ...
ps_fname, ps_entry_point STRING pixel shader: ...

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
ms = demo_dir .. "./shaders/ms.spv"
ps = demo_dir .. "./shaders/ps.spv"
meshprog = gh_gpu_program.vk_create_mesh_task_from_spirv_module_file("MeshProg", ms,"main",  "","",  ps,"main")

vk_create_mesh_task_from_spirv_module_zip

vulkan

Creates a Vulkan GPU mesh shader program from SPIR-V modules stored in a zip archive.

syntax

gpuprog_id = gh_gpu_program.vk_create_mesh_task_from_spirv_module_zip (
zip_filename,
program_name,
ms_fname, ms_entry_point,
ts_fname, ts_entry_point,
ps_fname, ps_entry_point
)

parameters

zip_filename STRING absolute path to the zip archive
program_name STRING name of the GPU program
ms_fname, ms_entry_point STRING mesh shader: absolute path of the shader file, entry point name
ts_fname, ts_entry_point STRING task shader: ...
ps_fname, ps_entry_point STRING pixel shader: ...

return values

gpuprog_id ID gpu program identifier

code sample

local demo_dir = gh_utils.get_demo_dir()
zipfile = demo_dir .. "data.zip"
ms = "shaders/ms.spv"
ps = "shaders/ps.spv"
meshprog = gh_gpu_program.vk_create_mesh_task_from_spirv_module_zip(zipfile, "MeshProg", ms,"main",  "","",  ps,"main")

gh_imagemagick

ImageMagick module

gh_imagemagick is the module that manages ImageMagick functions.
ImageMagick allows to create, edit, compose, or convert bitmap images, read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, TIFF, DPX, EXR, WebP, Postscript, PDF, and SVG....

file_convert

Converts an image file (new format).

syntax

ret = gh_imagemagick.file_convert (
src_filename,
dst_filename
)

parameters

src_filename STRING absolute path of the source image file
dst_filename STRING absolute path of the destination image file

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_imagemagick.file_convert(src_filename, dst_filename)

file_crop

Crops an image file.

syntax

ret = gh_imagemagick.file_crop (
src_filename,
dst_filename,
x, y, width, height
)

parameters

src_filename STRING absolute path of the source image file
dst_filename STRING absolute path of the destination image file
x, y, width, height INTEGER crop rectangle

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_imagemagick.file_crop(src_filename, dst_filename, x, y, width, height)

file_exif_get_num_properties

Gets the number of EXIF properties of an image.

syntax

num_exif = gh_imagemagick.file_exif_get_num_properties (
filename
)

parameters

filename STRING absolute path of the image file

return values

num_exif INTEGER number of EXIF properties

code sample

num_exif = gh_imagemagick.file_exif_get_num_properties(filename)

file_exif_get_property

Gets a particular EXIF property of an image.

syntax

prop_name, prop_value = gh_imagemagick.file_exif_get_property (
filename,
prop_index
)

parameters

filename STRING absolute path of the image file
prop_index INTEGER property index

return values

prop_name, prop_value STRING property name and value

code sample

prop_name, prop_value = gh_imagemagick.file_exif_get_property(filename, prop_index)

file_exif_to_log

Writes to the log all EXIF data of an image.

syntax

gh_imagemagick.file_exif_to_log (
filename
)

parameters

filename STRING absolute path of the image file

return values

none

code sample

gh_imagemagick.file_exif_to_log(filename)

file_ping

Returns simple information (size and format) about an image file without loading it in memory.

syntax

format, width, height = gh_imagemagick.file_ping (
filename
)

parameters

filename STRING absolute path of the image file

return values

format STRING image format (jpg, png, etc.)
width, height INTEGER size of the image

code sample

w, h, format = gh_imagemagick.file_ping(filename)

file_resize

Resizes an image file.

syntax

ret = gh_imagemagick.file_resize (
src_filename,
dst_filename,
width, height
)

parameters

src_filename STRING absolute path of the source image file
dst_filename STRING absolute path of the destination image file
width, height INTEGER new size

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_imagemagick.file_resize(src_filename, dst_filename, 640, 480)

texture_auto_level

Applies an auto level effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_auto_level (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_imagemagick.texture_auto_level(tex_id)
gh_imagemagick.texture_update(tex_id)

texture_blur

Applies a blur effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_blur (
tex_id,
radius, sigma
)

parameters

tex_id ID texture identifier
radius, sigma REAL effect params.

return values

none

code sample

gh_imagemagick.texture_blur(tex_id, radius, sigma)
gh_imagemagick.texture_update(tex_id)

texture_charcoal

Applies a charcoal effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_charcoal (
tex_id,
radius, sigma
)

parameters

tex_id ID texture identifier
radius, sigma REAL effect params.

return values

none

code sample

gh_imagemagick.texture_charcoal(tex_id, radius, sigma)
gh_imagemagick.texture_update(tex_id)

texture_cleanup

Frees all ImageMagick resources allocated by the texture.
Should be called in a TERMINATE script.

syntax

gh_imagemagick.texture_cleanup (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_imagemagick.texture_cleanup(tex_id)

texture_constitute

Updates the texture to be ImageMagick-compatible.
The texture can be used with other imagemagick functions.

syntax

ret = gh_imagemagick.texture_constitute (
tex_id
)

parameters

tex_id ID texture identifier

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_imagemagick.texture_constitute(tex_id)

texture_create_from_buffer

Creates a texture object from a memory buffer.

syntax

tex_id = gh_imagemagick.texture_create_from_buffer (
buff_ptr,
buff_size,
pf,
gen_mipmaps,
free_cpu_memory,
upload_to_gpu
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
pf ENUM( pixel_format ) pixel format. See all PF_xxx values.
gen_mipmaps BOOLEAN mipmap generation: 1 (enabled) or 0 (disabled). Currently, works with OpenGL renderer only.
free_cpu_memory BOOLEAN frees the CPU memory after loading in GPU memory: 1 (true) or 0 (false)
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

code sample

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 PF_U8_RGBA = 3
local upload_to_gpu = 1
local gen_mipmaps = 1
local free_cpu_memory = 1
filename = demo_dir .. "assets/image.jpg"

buffer, buffer_size = gh_utils.file_buffer_create(filename)
tex_id = gh_imagemagick.texture_create_from_buffer(buffer, buffer_size, PF_U8_RGBA, gen_mipmaps, free_cpu_memory, upload_to_gpu)
gh_utils.file_buffer_kill(buffer)

texture_create_from_file

Creates a texture object from an image file.

syntax

tex_id = gh_imagemagick.texture_create_from_file (
filename,
pf,
gen_mipmaps,
free_cpu_memory,
upload_to_gpu
)

parameters

filename STRING absolute path of the image file
pf ENUM( pixel_format ) pixel format. See all PF_xxx values.
gen_mipmaps BOOLEAN mipmap generation: 1 (enabled) or 0 (disabled). Currently, works with OpenGL renderer only.
free_cpu_memory BOOLEAN frees the CPU memory after loading in GPU memory: 1 (true) or 0 (false)
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

code sample

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_imagemagick.texture_create_from_file(filename, PF_U8_RGBA, gen_mipmaps, free_cpu_memory, upload_to_gpu)

texture_create_from_zip_file

Creates a texture object from an image file stored in a zip archive.

syntax

tex_id = gh_imagemagick.texture_create_from_zip_file (
zip_filename,
filename,
pf,
gen_mipmaps,
free_cpu_memory,
upload_to_gpu
)

parameters

zip_filename STRING absolute path of the zip file
filename STRING image file in the zip archive
pf ENUM( pixel_format ) pixel format. See all PF_xxx values.
gen_mipmaps BOOLEAN mipmap generation: 1 (enabled) or 0 (disabled). Currently, works with OpenGL renderer only.
free_cpu_memory BOOLEAN frees the CPU memory after loading in GPU memory: 1 (true) or 0 (false)
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

code sample

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 PF_U8_RGBA = 3
local upload_to_gpu = 1
local gen_mipmaps = 1
local free_cpu_memory = 1
local demo_dir = gh_utils.get_demo_dir()
zip_filename = demo_dir .. "demo.zip"
filename = "assets/image.jpg"

tex_id = gh_imagemagick.texture_create_from_zip_file(zip_filename, filename, PF_U8_RGBA, gen_mipmaps, free_cpu_memory, upload_to_gpu)

texture_crop

Applies a crop effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_crop (
tex_id,
x, y, width, height
)

parameters

tex_id ID texture identifier
x, y, width, height INTEGER cropping region

return values

none

code sample

gh_imagemagick.texture_crop(tex_id, x, y, width, height)
gh_imagemagick.texture_update(tex_id)

texture_decipher

Applies a decipher effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_decipher (
tex_id,
passphrase
)

parameters

tex_id ID texture identifier
passphrase STRING effect param.

return values

none

code sample

gh_imagemagick.texture_decipher(tex_id, "geexlab")
gh_imagemagick.texture_update(tex_id)

texture_edge

Applies an edge effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_edge (
tex_id,
radius
)

parameters

tex_id ID texture identifier
radius REAL effect param.

return values

none

code sample

gh_imagemagick.texture_edge(tex_id, radius)
gh_imagemagick.texture_update(tex_id)

texture_emboss

Applies an emboss effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_emboss (
tex_id,
radius, sigma
)

parameters

tex_id ID texture identifier
radius, sigma REAL effect params.

return values

none

code sample

gh_imagemagick.texture_emboss(tex_id, radius, sigma)
gh_imagemagick.texture_update(tex_id)

texture_encipher

Applies an encipher effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_encipher (
tex_id,
passphrase
)

parameters

tex_id ID texture identifier
passphrase STRING effect param.

return values

none

code sample

gh_imagemagick.texture_encipher(tex_id, "geexlab")
gh_imagemagick.texture_update(tex_id)

texture_flip

Applies a flip effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_flip (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_imagemagick.texture_flip(tex_id)
gh_imagemagick.texture_update(tex_id)

texture_flop

Applies a flop effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_flop (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_imagemagick.texture_flop(tex_id)
gh_imagemagick.texture_update(tex_id)

texture_gaussian_blur

Applies a motion blur effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_gaussian_blur (
tex_id,
radius, sigma
)

parameters

tex_id ID texture identifier
radius, sigma REAL effect params.

return values

none

code sample

gh_imagemagick.texture_gaussian_blur(tex_id, radius, sigma)
gh_imagemagick.texture_update(tex_id)

texture_motion_blur

Applies a motion blur effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_motion_blur (
tex_id,
radius, sigma, angle
)

parameters

tex_id ID texture identifier
radius, sigma, angle REAL effect params.

return values

none

code sample

gh_imagemagick.texture_motion_blur(tex_id, radius, sigma, angle)
gh_imagemagick.texture_update(tex_id)

texture_negate

Applies a negate effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_negate (
tex_id,
only_negate_grayscale_pixels
)

parameters

tex_id ID texture identifier
only_negate_grayscale_pixels BOOLEAN only negate grayscale pixels: 1 (true) or 0 (false)

return values

none

code sample

gh_imagemagick.texture_negate(tex_id, 0)
gh_imagemagick.texture_update(tex_id)

texture_oil_paint

Applies a oil paint effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_oil_paint (
tex_id,
radius, sigma
)

parameters

tex_id ID texture identifier
radius, sigma REAL effect params.

return values

none

code sample

gh_imagemagick.texture_oil_paint(tex_id, radius, sigma)
gh_imagemagick.texture_update(tex_id)

texture_posterize

Applies a posterize effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_posterize (
tex_id,
num_colors,
dither_method_type
)

parameters

tex_id ID texture identifier
num_colors INTEGER effect params.
dither_method_type ENUM( imagemagick_dither_method ) dithering method

return values

none

code sample

dither_method_type:
"none"
"riemersma"
"floydsteinberg"
num_colors = 4
dither_method_type = "none"

gh_imagemagick.texture_posterize(tex_id, num_colors, dither_method_type)
gh_imagemagick.texture_update(tex_id)

texture_quantize

Applies a quantize effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_quantize (
tex_id,
num_colors,
color_space_type,
treedepth,
dither_method_type
)

parameters

tex_id ID texture identifier
num_colors INTEGER number of colors
color_space_type ENUM( imagemagick_color_space_type ) color space
treedepth INTEGER effect params.
dither_method_type ENUM( imagemagick_dither_method ) dithering method

return values

none

code sample

color_space_type:
'cmy'
'cmyk'
'gray'
'hsb'
'hsl'
'luv'
'rgb'
'srgb'
'xyz'
'ycbcr'
'yuv'
dither_method_type:
'none'
'riemersma'
'floydsteinberg'

num_colors = 4
color_space_type = "srgb"
treedepth = 1
dither_method_type = "none"

gh_imagemagick.texture_quantize(tex_id, num_colors, color_space_type, treedepth, dither_method_type)
gh_imagemagick.texture_update(tex_id)

texture_read

Reads the content of an image file and stores it in an existing texture.

syntax

gh_imagemagick.texture_read (
tex_id,
filename,
pf
)

parameters

tex_id ID texture identifier
filename STRING absolute path of the image file
pf ENUM( pixel_format ) pixel format. See all PF_xxx values.

return values

none

code sample

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

gh_imagemagick.texture_read(tex_id, filename, PF_U8_RGBA)

texture_resize

Applies a resize effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_resize (
tex_id,
width, height
)

parameters

tex_id ID texture identifier
width, height INTEGER new size

return values

none

code sample

gh_imagemagick.texture_resize(tex_id, width, height)
gh_imagemagick.texture_update(tex_id)

texture_sepia

Applies a sepia effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_sepia (
tex_id,
threshold
)

parameters

tex_id ID texture identifier
threshold REAL effect param.

return values

none

code sample

gh_imagemagick.texture_sepia(tex_id, threshold)
gh_imagemagick.texture_update(tex_id)

texture_sharpen

Applies a sharpen effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_sharpen (
tex_id,
radius, sigma
)

parameters

tex_id ID texture identifier
radius, sigma REAL effect params.

return values

none

code sample

gh_imagemagick.texture_sharpen(tex_id, radius, sigma)
gh_imagemagick.texture_update(tex_id)

texture_sketch

Applies a sketch effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_sketch (
tex_id,
radius, sigma, angle
)

parameters

tex_id ID texture identifier
radius, sigma, angle REAL effect params.

return values

none

code sample

gh_imagemagick.texture_sketch(tex_id, radius, sigma, angle)
gh_imagemagick.texture_update(tex_id)

texture_solarize

Applies a solarize effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_solarize (
tex_id,
threshold
)

parameters

tex_id ID texture identifier
threshold REAL effect param.

return values

none

code sample

gh_imagemagick.texture_solarize(tex_id)
gh_imagemagick.texture_update(tex_id)

texture_swirl

Applies a swirl effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_swirl (
tex_id,
degrees,
interpolation_method
)

parameters

tex_id ID texture identifier
degrees REAL effect param.
interpolation_method ENUM( imagemagick_interpolation_method ) interpolation

return values

none

code sample

interpolation_method:
'spline'
'nearest'
'triangular_mesh'
'integer_floor'
'catrom'
'blend'
'bilinear'
'background'
'average16'
'average9'
'average4'

gh_imagemagick.texture_swirl(tex_id, degrees, "triangular_mesh")
gh_imagemagick.texture_update(tex_id)

texture_transpose

Applies a transpose effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_transpose (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_imagemagick.texture_transpose(tex_id)
gh_imagemagick.texture_update(tex_id)

texture_update

Updates the texture after ImageMagick operations on it (like cropping, effects, etc.).

syntax

gh_imagemagick.texture_update (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_imagemagick.texture_update(tex_id)

texture_wave

Applies a wave effect on the ImageMagick data of a texture.

syntax

gh_imagemagick.texture_wave (
tex_id,
amplitude, wave_length,
interpolation_method
)

parameters

tex_id ID texture identifier
amplitude, wave_length REAL effect params.
interpolation_method ENUM( imagemagick_interpolation_method ) interpolation

return values

none

code sample

interpolation_method:
'spline'
'nearest'
'triangular_mesh'
'integer_floor'
'catrom'
'blend'
'bilinear'
'background'
'average16'
'average9'
'average4'

gh_imagemagick.texture_wave(tex_id, amplitude, wave_length, "bilinear")
gh_imagemagick.texture_update(tex_id)

texture_write

Writes / saves a texture to a file.

syntax

gh_imagemagick.texture_write (
tex_id,
filename
)

parameters

tex_id ID texture identifier
filename STRING absolute path of the image file

return values

none

code sample

gh_imagemagick.texture_write(tex_id, filename)

gh_imgui

ImGui module

gh_imgui is the module that manages the ImGui library and allows to draw widgets.
Available in GeeXLab 0.17+.
All possible constants are defined in {GeeXLab folder}/libs/lua/imgui.lua or in {GeeXLab folder}/libs/python/imgui.py

add_bezier_curve_to_drawlist

Adds a Bezier curve to the current drawlist.

syntax

gh_imgui.add_bezier_curve_to_drawlist (
x0, y0,
cp0x, cp0y,
cp1x, cp1y,
x1, y1,
r, g, b, a
)

parameters

x0, y0 REAL start position
cp0x, cp0y REAL control point 0
cp1x, cp1y REAL control point 1
x1, y1 REAL end position
r, g, b, a REAL RGBA color

return values

none

code sample

gh_imgui.add_bezier_curve_to_drawlist(p0_x, p0_y, ctrl0_x, ctrl0_y, ctrl1_x, ctrl1_y, p1_x, p1_y, r, g, b, a)

add_circle_to_drawlist

Adds a circle to the current drawlist.

syntax

gh_imgui.add_circle_to_drawlist (
center_x, center_y,
radius,
r, g, b, a,
line_thickness,
num_segments,
filled
)

parameters

center_x, center_y REAL position of the circle center
radius REAL radius of the circle
r, g, b, a REAL RGBA color
line_thickness REAL line thickness
num_segments INTEGER number of segments of the circle
filled INTEGER solid (1) or wireframe (0)

return values

none

code sample

thickness = 2
num_segments = 20
filled = 1

gh_imgui.add_circle_to_drawlist(center_x, center_y, radius, r, g, b, a, thickness, num_segments, filled)

add_font_from_buffer

Adds a new font from a memory buffer.

syntax

font_id = gh_imgui.add_font_from_buffer (
buff_ptr,
buff_size,
font_size
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
font_size INTEGER size of the font

return values

font_id ID font identifier

code sample

filename = demo_dir .. "assets/arial.ttf"

buffer, buffer_size = gh_utils.file_buffer_create(filename)

font_id = gh_imgui.add_font_from_buffer(buffer, buffer_size, 24)

gh_utils.file_buffer_kill(buffer)

add_font_from_file

Adds a new font to the ImGui engine.

syntax

font_id = gh_imgui.add_font_from_file (
font_filename,
font_size
)

parameters

font_filename STRING absolute path of the font file
font_size INTEGER size of the font

return values

font_id ID font identifier

code sample

font_id = gh_imgui.add_font_from_file(font_filename, 24)

add_font_from_zip_file

Adds a new font from a zip file to the ImGui engine.

syntax

font_id = gh_imgui.add_font_from_zip_file (
zip_filename,
font_filename,
font_size
)

parameters

zip_filename STRING absolute path of the zip file
font_filename STRING absolute path of the font file
font_size INTEGER size of the font

return values

font_id ID font identifier

code sample

font_id = gh_imgui.add_font_from_zip_file(zip_filename, font_filename, 24)

add_line_to_drawlist

Adds a line to the current drawlist.

syntax

gh_imgui.add_line_to_drawlist (
x0, y0,
x1, y1,
r, g, b, a
)

parameters

x0, y0 REAL start position
x1, y1 REAL end position
r, g, b, a REAL RGBA color

return values

none

code sample

gh_imgui.add_line_to_drawlist(start_x, start_y, end_x, end_y, r, g, b, a)

add_quad_to_drawlist

Adds a quad to the current drawlist.

syntax

gh_imgui.add_quad_to_drawlist (
ax, ay,
bx, by,
cx, cy,
dx, dy,
r, g, b, a,
thickness,
filled
)

parameters

ax, ay REAL position of the 1st point
bx, by REAL position of the 2nd point
cx, cy REAL position of the 3rd point
dx, dy REAL position of the 4th point
r, g, b, a REAL RGBA color
thickness REAL line thickness
filled INTEGER solid (1) or wireframe (0)

return values

none

code sample

thickness = 2
filled = 1

gh_imgui.add_quad_to_drawlist(ax, ay, bx, by, cx, cy, dx, dy, r, g, b, a, thickness, filled)

add_rect_filled_multicolor_to_drawlist

Adds a multi-colored rectangle to the current drawlist.

syntax

gh_imgui.add_rect_filled_multicolor_to_drawlist (
p_min_x, p_min_y,
p_max_x, p_max_y,
r0, g0, b0, a0,
r1, g1, b1, a1,
r2, g2, b2, a2,
r3, g3, b3, a3
)

parameters

p_min_x, p_min_y REAL position of the bottom_left corner
p_max_x, p_max_y REAL position of the top right corner
r0, g0, b0, a0 REAL RGBA up-left
r1, g1, b1, a1 REAL RGBA up-right
r2, g2, b2, a2 REAL RGBA bottom-right
r3, g3, b3, a3 REAL RGBA bottom-left

return values

none

code sample

gh_imgui.add_rect_filled_multicolor_to_drawlist(p_min_x, p_min_y, p_max_x, p_max_y, 
r0, g0, b0, a0,
r1, g1, b1, a1,
r2, g2, b2, a2,
r3, g3, b3, a3)

add_rect_to_drawlist

Adds a rectangle to the current drawlist.

syntax

gh_imgui.add_rect_to_drawlist (
p_min_x, p_min_y,
p_max_x, p_max_y,
r, g, b, a,
rounding,
thickness,
filled
)

parameters

p_min_x, p_min_y REAL position of the bottom_left corner
p_max_x, p_max_y REAL position of the top right corner
r, g, b, a REAL RGBA color
rounding REAL corner rounding
thickness REAL line thickness
filled INTEGER solid (1) or wireframe (0)

return values

none

code sample

rounding = 0
thickness = 2
filled = 1

gh_imgui.add_rect_to_drawlist(p_min_x, p_min_y, p_max_x, p_max_y, r, g, b, a, rounding, thickness, filled)

add_triangle_to_drawlist

Adds a triangle to the current drawlist.

syntax

gh_imgui.add_triangle_to_drawlist (
p1x, p1y,
p2x, p2y,
p3x, p3y,
r, g, b, a,
thickness,
filled
)

parameters

p1x, p1y REAL position of the first vertex
p2x, p2y REAL position of the second vertex
p3x, p3y REAL position of the third vertex
r, g, b, a REAL RGBA color
thickness REAL line thickness
filled INTEGER solid (1) or wireframe (0)

return values

none

code sample

thickness = 2
filled = 1

gh_imgui.add_triangle_to_drawlist(p1x, p1y, p2x, p2y, p3x, p3y, r, g, b, a, thickness, filled)

begin_child

Begins a scrolling region.

syntax

gh_imgui.begin_child (
label,
width, height,
border,
flags
)

parameters

label STRING name of the button
width, height REAL size of the region
border BOOLEAN border: 1 (enabled) or 0 (disabled)
flags ENUM( imgui_WindowFlags ) see window flags (ImGuiWindowFlags_xxx) in imgui.lua

return values

none

code sample

gh_imgui.begin_child(label, w, h, border, flags)

begin_disabled

Disables all user interactions and darkens items visuals.
end_disabled() must be called to end the disabled section.

syntax

gh_imgui.begin_disabled (
disabled
)

parameters

disabled INTEGER 0 or 1

return values

none

code sample

gh_imgui.begin_disabled(1)

bullet

Adds a bullet (for lists).

syntax

gh_imgui.bullet()

parameters

none

return values

none

code sample

gh_imgui.bullet()

button

Create a button.

syntax

pressed = gh_imgui.button (
label,
width, height
)

parameters

label STRING name of the button
width, height INTEGER width and height of the button

return values

pressed BOOLEAN pressed: 1 (true) or 0 (false)

code sample

pressed = gh_imgui.button("Fire", 200, 20)

button_arrow

Create a arrow shaped button.

syntax

pressed = gh_imgui.button_arrow (
label,
direction
)

parameters

label STRING name of the button
direction ENUM( arrow_dir ) arrow direction: 0 (left), 1 (right), 2(up) and 3(down)

return values

pressed BOOLEAN pressed: 1 (true) or 0 (false)

code sample

pressed = gh_imgui.button_arrow("Fire", 1)

calc_text_size

Returns the size (width and height) of a string.

syntax

x, y = gh_imgui.calc_text_size (
text
)

parameters

text STRING text

return values

x, y REAL size of the text

code sample

x, y = gh_imgui.calc_text_size("Hello")

checkbox

Create a checkbox.

syntax

checked = gh_imgui.checkbox (
label,
current_state
)

parameters

label STRING name of the button
current_state BOOLEAN checked: 1 (true) or 0 (false)

return values

checked BOOLEAN checked: 1 (true) or 0 (false)

code sample

checked = gh_imgui.checkbox("Wireframe", checked)

collapsing_header

Creates an header that can be opened or closed.

syntax

opened = gh_imgui.collapsing_header (
label,
flags
)

parameters

label STRING name of the button
flags ENUM( imgui_TreeNodeFlags ) see ImGuiTreeNodeFlags_xxx flags in imgui.lua (GeeXLab lua libs)

return values

opened BOOLEAN 1 (opened) or 0 (closed)

code sample

local flags = 0 -- default

if (gh_imgui.collapsing_header(label, flags) == 1) then
    ...
end

color_edit_rgba

Displays a 4D slider with color picker.

syntax

r, g, b, a = gh_imgui.color_edit_rgba (
label,
r0, b0, g0, a0
)

parameters

label STRING name of the slider
r0, b0, g0, a0 REAL initial 4D value

return values

r, g, b, a REAL RGBA color value

code sample

r, g, b, a = gh_imgui.color_edit_rgba("coloredit01", r0, b0, g0, a0)

color_edit_rgba_v2

Displays a 4D slider with color picker.

syntax

r, g, b, a = gh_imgui.color_edit_rgba_v2 (
label,
r0, b0, g0, a0,
flags
)

parameters

label STRING name of the slider
r0, b0, g0, a0 REAL initial 4D value
flags ENUM( imgui_ColorEditFlags ) ImGuiColorEditFlags_xxx options

return values

r, g, b, a REAL RGBA color value

code sample

flags = ImGuiColorEditFlags_None

r, g, b, a = gh_imgui.color_edit_rgba_v2("coloredit01", r0, b0, g0, a0, flags)

color_picker_rgba

Displays a color picker.

syntax

r, g, b, a = gh_imgui.color_picker_rgba (
label,
r0, b0, g0, a0
)

parameters

label STRING name of the color picker
r0, b0, g0, a0 REAL initial 4D value

return values

r, g, b, a REAL RGBA color value

code sample

r, g, b, a = gh_imgui.color_picker_rgba("coloredit01", r0, b0, g0, a0)

color_picker_rgba_v2

Displays a color picker.

syntax

r, g, b, a = gh_imgui.color_picker_rgba_v2 (
label,
r0, b0, g0, a0,
flags
)

parameters

label STRING name of the color picker
r0, b0, g0, a0 REAL initial 4D value
flags ENUM( imgui_ColorEditFlags ) ImGuiColorEditFlags_xxx options

return values

r, g, b, a REAL RGBA color value

code sample

flags = ImGuiColorEditFlags_None

r, g, b, a = gh_imgui.color_picker_rgba_v2("coloredit01", r0, b0, g0, a0, flags)

color_text_editor_copy_paste_cut

Performs a copy, paste or cut operation.

syntax

gh_imgui.color_text_editor_copy_paste_cut (
te_id,
what
)

parameters

te_id ID text editor identifier
what STRING operation: copy, paste or cut

return values

none

code sample

gh_imgui.color_text_editor_copy_paste_cut(te_id, "copy")

color_text_editor_create

Creates a new text editor widget.

syntax

te_id = gh_imgui.color_text_editor_create()

parameters

none

return values

te_id ID text editor identifier

code sample

te_id = gh_imgui.color_text_editor_create()

color_text_editor_get_current_line_text

Gets the current line.

syntax

line = gh_imgui.color_text_editor_get_current_line_text (
te_id
)

parameters

te_id ID text editor identifier

return values

line STRING current line

code sample

line = gh_imgui.color_text_editor_get_current_line_text(te_id)

color_text_editor_get_cursor_position

Gets the cursor position.

syntax

x, y = gh_imgui.color_text_editor_get_cursor_position (
te_id
)

parameters

te_id ID text editor identifier

return values

x, y INTEGER current cursor position

code sample

x, y = gh_imgui.color_text_editor_get_cursor_position(te_id)

color_text_editor_get_selected_text

Gets the selected text.

syntax

text = gh_imgui.color_text_editor_get_selected_text (
te_id
)

parameters

te_id ID text editor identifier

return values

text STRING selected text

code sample

text = gh_imgui.color_text_editor_get_selected_text(te_id)

color_text_editor_get_text

Gets the text of the editor.

syntax

text = gh_imgui.color_text_editor_get_text (
te_id
)

parameters

te_id ID text editor identifier

return values

text STRING text

code sample

text = gh_imgui.color_text_editor_get_text(te_id)

color_text_editor_get_total_lines

Gets the current number of lines.

syntax

n = gh_imgui.color_text_editor_get_total_lines (
te_id
)

parameters

te_id ID text editor identifier

return values

n INTEGER number of lines

code sample

n = gh_imgui.color_text_editor_get_total_lines(te_id)

color_text_editor_is_text_changed

Allows to know the if text has changed.

syntax

x = gh_imgui.color_text_editor_is_text_changed (
te_id
)

parameters

te_id ID text editor identifier

return values

x INTEGER 1 if text changed, 0 if not.

code sample

x = gh_imgui.color_text_editor_is_text_changed(te_id)

color_text_editor_kill

Destroys a text editor.

syntax

gh_imgui.color_text_editor_kill (
te_id
)

parameters

te_id ID text editor identifier

return values

none

code sample

gh_imgui.color_text_editor_kill(te_id)

color_text_editor_palette_get_color

Gets the color of a particular element.

syntax

r, g, b, a = gh_imgui.color_text_editor_palette_get_color (
te_id,
what
)

parameters

te_id ID text editor identifier
what STRING element name: Default, Keyword, Number, String, Punctuation, Preprocessor, Identifier, KnownIdentifier, PreprocIdentifier, Comment, MultiLineComment, Background, Cursor, Selection, ErrorMarker, Breakpoint, LineNumber, CurrentLineFill, CurrentLineFillInactive, CurrentLineEdge

return values

r, g, b, a REAL RGBA color

code sample

r, g, b, a = gh_imgui.color_text_editor_palette_get_color(te_id, "Background")

color_text_editor_palette_set_color

Sets the color of a particular element.

syntax

gh_imgui.color_text_editor_palette_set_color (
te_id,
what,
r, g, b, a
)

parameters

te_id ID text editor identifier
what STRING element name: Default, Keyword, Number, String, Punctuation, Preprocessor, Identifier, KnownIdentifier, PreprocIdentifier, Comment, MultiLineComment, Background, Cursor, Selection, ErrorMarker, Breakpoint, LineNumber, CurrentLineFill, CurrentLineFillInactive, CurrentLineEdge, XT95Line
r, g, b, a REAL RGBA color

return values

none

code sample

gh_imgui.color_text_editor_palette_set_color(te_id, "Background", r, g, b, a)
gh_imgui.color_text_editor_palette_set_color(te_id, "XT95Line", 0.2, 0.2, 0.2, 0.8)

color_text_editor_render

Draws a text editor.

syntax

gh_imgui.color_text_editor_render (
te_id,
title,
size_x, size_y,
border
)

parameters

te_id ID text editor identifier
title STRING title
size_x, size_y REAL frame size
border INTEGER border (1: yes, 0: no)

return values

none

code sample

gh_imgui.color_text_editor_render(te_id, "Lua Editor", 400, 600, 0)

color_text_editor_selection

Starts or ends text selection.

syntax

gh_imgui.color_text_editor_selection (
te_id,
what
)

parameters

te_id ID text editor identifier
what STRING operation: start, end or clear

return values

none

code sample

gh_imgui.color_text_editor_selection(te_id, "start")

color_text_editor_set_language

Sets a built-in language support.

syntax

gh_imgui.color_text_editor_set_language (
te_id,
lang
)

parameters

te_id ID text editor identifier
lang STRING langaue: lua, glsl, hlsl, cpp, c, sql

return values

none

code sample

gh_imgui.color_text_editor_set_language(te_id, "lua")

color_text_editor_set_palette

Sets a color palette.
Colors can also be modified with color_text_editor_palette_set_color().

syntax

gh_imgui.color_text_editor_set_palette (
te_id,
pal
)

parameters

te_id ID text editor identifier
pal STRING palette: dark, light, retro_blue

return values

none

code sample

gh_imgui.color_text_editor_set_palette(te_id, "dark")

color_text_editor_set_property_bool

Sets a property boolean value.

syntax

gh_imgui.color_text_editor_set_property_bool (
te_id,
what,
x
)

parameters

te_id ID text editor identifier
what STRING property name: whitespaces, readonly, colorizer, handle_mouse_inputs, handle_keyboard_inputs
x INTEGER value

return values

none

code sample

gh_imgui.color_text_editor_set_property_bool(te_id, "whitespaces", 1)

color_text_editor_set_property_int

Sets a property integer value.

syntax

gh_imgui.color_text_editor_set_property_int (
te_id,
what,
x
)

parameters

te_id ID text editor identifier
what STRING property name: tabsize
x INTEGER value

return values

none

code sample

gh_imgui.color_text_editor_set_property_int(te_id, "tabsize", 2)

color_text_editor_set_text

Sets the text of the editor.

syntax

gh_imgui.color_text_editor_set_text (
te_id,
text
)

parameters

te_id ID text editor identifier
text STRING text

return values

none

code sample

gh_imgui.color_text_editor_set_text(te_id, text)

column_get_offset

Gets the offset of a particular column.

syntax

offset = gh_imgui.column_get_offset (
index
)

parameters

index INTEGER column index

return values

offset REAL offset

code sample

offset = gh_imgui.column_get_offset(index)

column_get_width

Gets the width of a particular column.

syntax

width = gh_imgui.column_get_width (
index
)

parameters

index INTEGER column index

return values

width REAL width

code sample

width = gh_imgui.column_get_width(index)

column_next

Starts a new column.

syntax

gh_imgui.column_next()

parameters

none

return values

none

code sample

gh_imgui.columns(2, 1)

-- display widgets
...

-- next column
gh_imgui.column_next()

-- display widgets
...

-- reset to default layout (one column)
gh_imgui.columns(1, 0)

column_set_offset

Sets the offset of a particular column.

syntax

gh_imgui.column_set_offset (
index,
offset
)

parameters

index INTEGER column index
offset REAL offset

return values

none

code sample

gh_imgui.column_set_offset(index, width)

column_set_width

Sets the width of a particular column.

syntax

gh_imgui.column_set_width (
index,
width
)

parameters

index INTEGER column index
width REAL width

return values

none

code sample

gh_imgui.column_set_width(index, width)

columns

Starts/ends a column layout.

syntax

gh_imgui.columns (
num_columns,
border
)

parameters

num_columns INTEGER number of columns
border INTEGER display column border ot not

return values

none

code sample

gh_imgui.columns(2, 1)

-- display widgets
...

-- next column
gh_imgui.column_next()

-- display widgets
...

-- reset to default layout (one column)
gh_imgui.columns(1, 0)

combo_box_add_item

Adds an item to a combo box.

syntax

gh_imgui.combo_box_add_item (
cb_id,
item_label
)

parameters

cb_id ID combo box identifier
item_label STRING label of the item

return values

none

code sample

gh_imgui.combo_box_add_item(cb_id, "Item1")

combo_box_create

Creates a combo box.
Must be called once (usually in an INIT script).

syntax

cb_id = gh_imgui.combo_box_create (
label
)

parameters

label STRING combo box label

return values

cb_id ID combo box identifier

code sample

cb_id = gh_imgui.combo_box_create(label)

combo_box_draw

Draws the combo box.

syntax

selected_item = gh_imgui.combo_box_draw (
cb_id,
initial_selected_item
)

parameters

cb_id ID combo box identifier
initial_selected_item INTEGER index of the initial selected item

return values

selected_item INTEGER index of the current selected item

code sample

selected_item = gh_imgui.combo_box_draw(cb_id, 0)

combo_box_draw_v2

Draws the combo box.

syntax

selected_item = gh_imgui.combo_box_draw_v2 (
cb_id,
initial_selected_item,
height_in_items
)

parameters

cb_id ID combo box identifier
initial_selected_item INTEGER index of the initial selected item
height_in_items INTEGER height of the combo box in items

return values

selected_item INTEGER index of the current selected item

code sample

selected_item = gh_imgui.combo_box_draw_v2(cb_id, 0, 10)

dummy

Places an invisible widget (box).
Useful for layout management.

syntax

gh_imgui.dummy (
width, height
)

parameters

width, height INTEGER dimensions of the box in pixels

return values

none

code sample

gh_imgui.dummy(10, 5)

end_child

End a scrolling region.

syntax

gh_imgui.end_child()

parameters

none

return values

none

code sample

gh_imgui.end_child()

end_disabled

Ends a disabled section.

syntax

gh_imgui.end_disabled()

parameters

none

return values

none

code sample

gh_imgui.end_disabled()

file_browser_add_type_filter

Adds a type filter.

syntax

gh_imgui.file_browser_add_type_filter (
type
)

parameters

type STRING type filter

return values

none

code sample

gh_imgui.file_browser_add_type_filter(".lua")
gh_imgui.file_browser_add_type_filter(".xml")
gh_imgui.file_browser_add_type_filter(".txt")

file_browser_clear_type_filters

Clears all type filters.
In that case the file browser will display all types of files.

syntax

gh_imgui.file_browser_clear_type_filters()

parameters

none

return values

none

code sample

gh_imgui.file_browser_clear_type_filters()

file_browser_close

Closes the file browser: the file browser is no longer displayed with file_browser_display().

syntax

gh_imgui.file_browser_close()

parameters

none

return values

none

code sample

gh_imgui.file_browser_close()

file_browser_display

Displays the file browser.
To really shows it, you must open the file browser with file_browser_open().

syntax

gh_imgui.file_browser_display (
width, height
)

parameters

width, height INTEGER size of the file browser window

return values

none

code sample

gh_imgui.file_browser_display(600, 400)

file_browser_get_selected

Gets the selected filename.

syntax

filename = gh_imgui.file_browser_get_selected()

parameters

none

return values

filename STRING the selected filename

code sample

if (gh_imgui.file_browser_has_selected() == 1) then
	filename = gh_imgui.file_browser_get_selected()
end

file_browser_has_selected

Checks if a file has been selected.

syntax

ret = gh_imgui.file_browser_has_selected()

parameters

none

return values

ret INTEGER 1 (selected) or 0 (not selected)

code sample

if (gh_imgui.file_browser_has_selected() == 1) then
  DoSomething()
end

file_browser_init

Initializes the file browser.
MUST be called before any other file_browser_xxxx() functions.

syntax

gh_imgui.file_browser_init (
flags
)

parameters

flags INTEGER options. See ImGuiFileBrowserFlags_xxxx values in imgui.lua

return values

none

code sample

gh_imgui.file_browser_init(0)

file_browser_open

Opens the file browser: the file browser can be displayed with file_browser_display().

syntax

gh_imgui.file_browser_open()

parameters

none

return values

none

code sample

gh_imgui.file_browser_open()

file_browser_set_current_directory

Sets the current directory before displaying the file browser.

syntax

gh_imgui.file_browser_set_current_directory (
dir
)

parameters

dir STRING directory

return values

none

code sample

gh_imgui.file_browser_set_current_directory(demo_dir)

file_browser_set_title

Sets the file browser title.

syntax

gh_imgui.file_browser_set_title (
text
)

parameters

text STRING title

return values

none

code sample

gh_imgui.file_browser_set_title(title)

frame_begin

Begins ImGui rendering.
This is the first function to call in a FRAME script before any other gh_imgui functions.

syntax

gh_imgui.frame_begin (
width, height,
mouse_x, mouse_y,
mouse_left_button, mouse_right_button,
dt
)

parameters

width, height INTEGER size of the main 3D window (gh_window.getsize(0))
mouse_x, mouse_y INTEGER position of the mouse (gh_input.mouse_get_position())
mouse_left_button, mouse_right_button BOOLEAN state of mouse left and right buttons (gh_input.mouse_get_button_state())
dt REAL time step

return values

none

code sample

gh_imgui.frame_begin(winW, winH, mouse_x, mouse_y, mouse_left_button, mouse_right_button, dt)

frame_begin_v2

Begins ImGui rendering.
This is the first function to call in a FRAME script before any other gh_imgui functions.

syntax

gh_imgui.frame_begin_v2 (
width, height,
mouse_x, mouse_y,
mouse_left_button, mouse_right_button,
mouse_wheel,
dt
)

parameters

width, height INTEGER size of the main 3D window (gh_window.getsize(0))
mouse_x, mouse_y INTEGER position of the mouse (gh_input.mouse_get_position())
mouse_left_button, mouse_right_button BOOLEAN state of mouse left and right buttons (gh_input.mouse_get_button_state())
mouse_wheel INTEGER mouse wheel delta
dt REAL time step

return values

none

code sample

gh_imgui.frame_begin_v2(winW, winH, mouse_x, mouse_y, mouse_left_button, mouse_right_button, mouse_wheel, dt)

frame_end

Ends ImGui rendering.
This is the last function to call in a FRAME script after other gh_imgui functions.

syntax

gh_imgui.frame_end()

parameters

none

return values

none

code sample

gh_imgui.frame_end()

fx_drawlist_coding_party_demo

Implementation of some effects of the ImDrawList online coding party.

syntax

gh_imgui.fx_drawlist_coding_party_demo (
fx_name,
title,
window_flags,
width, height,
size_flags,
x, y,
position_flags
)

parameters

fx_name STRING name of the demo or effect
title STRING window title
window_flags INTEGER window flags
width, height INTEGER window size
size_flags INTEGER size flags
x, y INTEGER window position
position_flags INTEGER position flags

return values

none

code sample

Current demos:
"ocornut_squares"
"ocornut_waves"
"kudaba_thunder_storm"
"crowbarous_blobs"
"badlydrawnrod_racetrack"
"floooh_googly_eyes"
"bdero_particles"



pos_size_flag_always = 1
pos_size_flag_once = 2 
pos_size_flag_first_use_ever = 4
pos_size_flag_appearing = 8  

pos_size_flag = pos_size_flag_always


window_default = 0
window_no_resize = 2
window_no_move = 4
window_no_collapse = 32
window_show_border = 128
window_no_save_settings = 256

window_flags = window_default

gh_imgui.fx_drawlist_coding_party_demo("ocornut_squares", "squares", window_flags, 320, 180, pos_size_flag, 20, 20, pos_size_flag_once)

get_color

Gets the current color value.

syntax

r, g, b, a = gh_imgui.get_color (
item_type
)

parameters

item_type ENUM( imgui_ColoredItems ) type of the widget (see values in the code sample)

return values

r, g, b, a REAL RGBA color value

code sample

widget_type = IMGUI_BUTTON_COLOR

r, g, b, a = gh_imgui.get_color(widget_type)

get_content_region_available_width

Returns the available width inside a window.

syntax

width = gh_imgui.get_content_region_available_width()

parameters

none

return values

width REAL available width

code sample

width = gh_imgui.get_content_region_available_width()

get_cur_font_display_offset

Gets the x and y offset of the current font.

syntax

x, y = gh_imgui.get_cur_font_display_offset()

parameters

none

return values

x, y REAL offsets

code sample

x, y = gh_imgui.get_cur_font_display_offset()

get_cursor_pos

Returns the position of the mouse cursor (cursor position in window coordinates, relative to window position).

syntax

x, y = gh_imgui.get_cursor_pos()

parameters

none

return values

x, y REAL position

code sample

x, y = gh_imgui.get_cursor_pos()

get_cursor_screen_pos

Returns the position of the mouse cursor (cursor position in absolute screen coordinates [0 ; DisplaySize], useful for working with DrawList API).

syntax

x, y = gh_imgui.get_cursor_screen_pos()

parameters

none

return values

x, y REAL position

code sample

x, y = gh_imgui.get_cursor_screen_pos()

get_cursor_start_pos

Gets the initial cursor position in window coordinates.

syntax

x, y = gh_imgui.get_cursor_start_pos()

parameters

none

return values

x, y REAL cursor position

code sample

x, y = gh_imgui.get_cursor_start_pos()

get_font_size

Returns the size (height) of the font.

syntax

size = gh_imgui.get_font_size()

parameters

none

return values

size REAL size

code sample

size = gh_imgui.get_font_size()

get_item_rect

Gets the size (bounding rectangle) of the current item.

syntax

x, y, z, w = gh_imgui.get_item_rect()

parameters

none

return values

x, y, z, w INTEGER size of the current item

code sample

x, y, z, w = gh_imgui.get_item_rect()

get_item_rect_max

Gets the lower-right bounding rectangle of the last item.

syntax

x, y = gh_imgui.get_item_rect_max()

parameters

none

return values

x, y REAL 2D coordinates

code sample

x, y = gh_imgui.get_item_rect_max()

get_item_rect_min

Gets the upper-left bounding rectangle of the last item.

syntax

x, y = gh_imgui.get_item_rect_min()

parameters

none

return values

x, y REAL 2D coordinates

code sample

x, y = gh_imgui.get_item_rect_min()

get_item_spacing

Gets the spacing between items.

syntax

x, y = gh_imgui.get_item_spacing()

parameters

none

return values

x, y REAL spacing

code sample

x, y = gh_imgui.get_item_spacing()

get_mouse_pos

Gets the mouse position.

syntax

x, y = gh_imgui.get_mouse_pos()

parameters

none

return values

x, y REAL mouse position

code sample

x, y = gh_imgui.get_mouse_pos()

get_mouse_pos_on_opening_current_popup

Gets the mouse position when the user is opening a popup / context menu (mouse right click).

syntax

x, y = gh_imgui.get_mouse_pos_on_opening_current_popup()

parameters

none

return values

x, y REAL mouse position

code sample

x, y = gh_imgui.get_mouse_pos_on_opening_current_popup()

get_scroll

Gets the scrolling amount in X and Y [0..get_scroll_max()].

syntax

scroll_x, scroll_y = gh_imgui.get_scroll()

parameters

none

return values

scroll_x, scroll_y REAL scrolling values in X and Y

code sample

scroll_x, scroll_y = gh_imgui.get_scroll()

get_scroll_max

Gets the maximum scrolling amount in X and Y - X => ContentSize.X - WindowSize.X, Y => ContentSize.Y - WindowSize.Y

syntax

scroll_x, scroll_y = gh_imgui.get_scroll_max()

parameters

none

return values

scroll_x, scroll_y REAL scrolling values in X and Y

code sample

scroll_x, scroll_y = gh_imgui.get_scroll_max()

get_text_line_heigh_with_spacing

Distance in pixels between 2 consecutive lines of text

syntax

h = gh_imgui.get_text_line_heigh_with_spacing()

parameters

none

return values

h REAL height

code sample

h = gh_imgui.get_text_line_heigh_with_spacing()

get_text_line_height

Gets the current line height (font size).

syntax

h = gh_imgui.get_text_line_height()

parameters

none

return values

h REAL line height

code sample

h = gh_imgui.get_text_line_height()

get_text_line_height_with_spacing

Gets the distance in pixels between 2 consecutive lines of text.

syntax

h = gh_imgui.get_text_line_height_with_spacing()

parameters

none

return values

h REAL line height

code sample

h = gh_imgui.get_text_line_height_with_spacing()

get_version

Returns the version of ImGui.

syntax

version = gh_imgui.get_version()

parameters

none

return values

version STRING ImGui version

code sample

version_str = gh_imgui.get_version()

get_window_pos

Returns the position of the current window.

syntax

x, y = gh_imgui.get_window_pos()

parameters

none

return values

x, y REAL position

code sample

x, y = gh_imgui.get_window_pos()

get_window_pos_size

Returns the position and size of the current window.

syntax

x, y, width, height = gh_imgui.get_window_pos_size()

parameters

none

return values

x, y, width, height REAL position and size

code sample

x, y, width, height = gh_imgui.get_window_pos_size()

get_window_size

Returns the size of the current window.

syntax

width, height = gh_imgui.get_window_size()

parameters

none

return values

width, height REAL size

code sample

width, height = gh_imgui.get_window_size()

gizmo_begin_frame

Begins the gizmo rendering.
Must be called right after frame_begin().

syntax

gh_imgui.gizmo_begin_frame()

parameters

none

return values

none

code sample

gh_imgui.frame_begin(...)
gh_imgui.gizmo_begin_frame()
...

gizmo_decompose_matrix_to_components

Gets the transformation matrix.

syntax

tx,ty,tz,  rx,ry,rz,  sx,sy,sz = gh_imgui.gizmo_decompose_matrix_to_components (
obj_id
)

parameters

obj_id ID object identifier

return values

tx,ty,tz,  rx,ry,rz,  sx,sy,sz REAL translation vector, rotation vector and scale vector

code sample

tx,ty,tz,  rx,ry,rz,  sx,sy,sz = gh_imgui.gizmo_decompose_matrix_to_components(obj_id)

gizmo_enable

Enables or disables the gizmo.

syntax

gh_imgui.gizmo_enable (
state
)

parameters

state INTEGER 0 or 1

return values

none

code sample

gh_imgui.gizmo_enable(1)

gizmo_is_over

Is the mouse over the gizmo?

syntax

state = gh_imgui.gizmo_is_over()

parameters

none

return values

state BOOLEAN 1 (yes) or 0 (no)

code sample

is_over = gh_imgui.gizmo_is_over()

gizmo_is_using

Is the mouse over the gizmo or is the gizmo in moving state?

syntax

state = gh_imgui.gizmo_is_using()

parameters

none

return values

state BOOLEAN 1 (yes) or 0 (no)

code sample

is_using = gh_imgui.gizmo_is_using()

gizmo_manipulate

Applies the gizmo transformation to an object.

syntax

gh_imgui.gizmo_manipulate (
cam_id,
obj_id,
oper_type,
trans_mode
)

parameters

cam_id ID camera identifier
obj_id ID object identifier
oper_type ENUM( imgui_OperationType ) operation type: 'translate', 'rotate' or 'scale'
trans_mode ENUM( imgui_TransformationMode ) transformation mode: 'local' or 'world'

return values

none

code sample

gh_imgui.gizmo_manipulate(cam_id, obj_id, "rotate", "local")

gizmo_set_rect

Defines the gizmo viewport.

syntax

gh_imgui.gizmo_set_rect (
x, y, width, height
)

parameters

x, y, width, height INTEGER viewport size

return values

none

code sample

gh_imgui.gizmo_set_rect(0, 0, winW, winH)

group_begin

Starts a new group.
All widgets in a group are seen as a single widget.

syntax

gh_imgui.group_begin()

parameters

none

return values

none

code sample

gh_imgui.group_begin()

-- display widgets
...

gh_imgui.group_end()

group_end

Ends a group.

syntax

gh_imgui.group_end()

parameters

none

return values

none

code sample

gh_imgui.group_begin()

-- display widgets
...

gh_imgui.group_end()

image

opengl

Display a texture.
Currently, this fonction works in OpenGL only.

syntax

gh_imgui.image (
tex_id,
width, height
)

parameters

tex_id ID texture identifier as returned by gh_texture.create_xxx() functions
width, height REAL image size

return values

none

code sample

gh_imgui.image(tex0, 200, 200)

image_button

opengl

Display a button with a texture.
Currently, this fonction works in OpenGL only.

syntax

gh_imgui.image_button (
tex_id,
width, height,
frame_padding
)

parameters

tex_id ID texture identifier as returned by gh_texture.create_xxx() functions
width, height REAL image size
frame_padding INTEGER frame padding

return values

none

code sample

gh_imgui.image_button(tex0, 200, 200, 1)

imgui_plot_create

Creates a plotline.

syntax

plot_id = gh_imgui.imgui_plot_create (
label
)

parameters

label STRING name of the plotline

return values

plot_id ID plotline identifier

code sample

plot_id = gh_imgui.imgui_plot_create("myPlotline")

imguizmoquat_gizmo3d_v1

Rotates an object using a virtual trackball.

syntax

gh_imgui.imguizmoquat_gizmo3d_v1 (
label,
size,
mode,
object_id
)

parameters

label STRING label of the gizmo
size REAL size of the item
mode INTEGER gizmo mode
object_id REAL object identifier

return values

none

code sample

local mode3Axes = 1
local modeDirection = 2
local modeDirPlane = 4
local modeDual = 8
local modeMask = 15
local cubeAtOrigin = 16
local sphereAtOrigin = 32
local noSolidAtOrigin = 64
local modeFullAxes = 128
local axesModeMask = 240
gh_imgui.imguizmoquat_gizmo3d_v1("##gizmo01", 100.0, modeDirection + cubeAtOrigin, torus)

imguizmoquat_gizmo3d_v2

Rotates a virtual trackball and returns the orientation quaternion.

syntax

qx, qy, qz, qw = gh_imgui.imguizmoquat_gizmo3d_v2 (
label,
size,
mode,
q0x, q0y, q0z, q0w
)

parameters

label STRING label of the gizmo
size REAL size of the item
mode INTEGER gizmo mode
q0x, q0y, q0z, q0w REAL initial orientation quaternion

return values

qx, qy, qz, qw REAL orientation quaternion

code sample

local mode3Axes = 1
local modeDirection = 2
local modeDirPlane = 4
local modeDual = 8
local modeMask = 15
local cubeAtOrigin = 16
local sphereAtOrigin = 32
local noSolidAtOrigin = 64
local modeFullAxes = 128
local axesModeMask = 240

q0 = {x=0, y=0, z=0, w=0}
qr = {x=0, y=0, z=0, w=0}

qr.x, qr.w, qr.z, qr.w = gh_imgui.imguizmoquat_gizmo3d_v2("##gizmo01", 100.0, modeDirection + cubeAtOrigin, q0.x, q0.y, q0.z, q0.w)

imguizmoquat_gizmo3d_v3

Rotates a virtual trackball and returns the 4x4 orientation matrix.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_imgui.imguizmoquat_gizmo3d_v3 (
label,
size,
mode,
q0x, q0y, q0z, q0w
)

parameters

label STRING label of the gizmo
size REAL size of the item
mode INTEGER gizmo mode
q0x, q0y, q0z, q0w REAL initial orientation quaternion

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

local mode3Axes = 1
local modeDirection = 2
local modeDirPlane = 4
local modeDual = 8
local modeMask = 15
local cubeAtOrigin = 16
local sphereAtOrigin = 32
local noSolidAtOrigin = 64
local modeFullAxes = 128
local axesModeMask = 240

q0 = {x=0, y=0, z=0, w=0}

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_imgui.imguizmoquat_gizmo3d_v3("##gizmo01", 100.0, modeDirection + cubeAtOrigin, q0.x, q0.y, q0.z, q0.w)

imnodes_begin_input_attribute

syntax

gh_imgui.imnodes_begin_input_attribute (
input_attr_id,
pin_shape
)

parameters

input_attr_id INTEGER 
pin_shape INTEGER

return values

none

code sample

ImNodesPinShape_Circle = 0
ImNodesPinShape_CircleFilled = 1
ImNodesPinShape_Triangle = 2
ImNodesPinShape_TriangleFilled = 3
ImNodesPinShape_Quad = 4
ImNodesPinShape_QuadFilled = 5

pin_shape = ImNodesPinShape_CircleFilled
gh_imgui.imnodes_begin_input_attribute(input_attr_id, pin_shape)

imnodes_begin_node

syntax

gh_imgui.imnodes_begin_node (
node_id
)

parameters

node_id INTEGER 

return values

none

code sample

gh_imgui.imnodes_begin_node(node_id)

imnodes_begin_node_editor

ImNodes - top-level function call - Calling this function will result the node editor grid workspace being rendered.

syntax

gh_imgui.imnodes_begin_node_editor()

parameters

none

return values

none

code sample

gh_imgui.imnodes_begin_node_editor()

imnodes_begin_node_title_bar

syntax

gh_imgui.imnodes_begin_node_title_bar()

parameters

none

return values

none

code sample

gh_imgui.imnodes_begin_node_title_bar()

imnodes_begin_output_attribute

syntax

gh_imgui.imnodes_begin_output_attribute (
output_attr_id,
pin_shape
)

parameters

output_attr_id INTEGER 
pin_shape INTEGER

return values

none

code sample

ImNodesPinShape_Circle = 0
ImNodesPinShape_CircleFilled = 1
ImNodesPinShape_Triangle = 2
ImNodesPinShape_TriangleFilled = 3
ImNodesPinShape_Quad = 4
ImNodesPinShape_QuadFilled = 5

pin_shape = ImNodesPinShape_CircleFilled
gh_imgui.imnodes_begin_output_attribute(output_attr_id, pin_shape)

imnodes_clear_node_selection

syntax

gh_imgui.imnodes_clear_node_selection (
node_id
)

parameters

node_id INTEGER 

return values

none

code sample

gh_imgui.imnodes_clear_node_selection(node_id)

imnodes_clear_nodes_selection

syntax

gh_imgui.imnodes_clear_nodes_selection()

parameters

none

return values

none

code sample

gh_imgui.imnodes_clear_nodes_selection()

imnodes_end_node

syntax

gh_imgui.imnodes_end_node()

parameters

none

return values

none

code sample

gh_imgui.imnodes_end_node()

imnodes_end_node_editor

Ends the node editor rendering.

syntax

gh_imgui.imnodes_end_node_editor()

parameters

none

return values

none

code sample

gh_imgui.imnodes_end_node_editor()

imnodes_end_node_title_bar

syntax

gh_imgui.imnodes_end_node_title_bar()

parameters

none

return values

none

code sample

gh_imgui.imnodes_end_node_title_bar()

imnodes_end_output_attribute_DUP1

syntax

gh_imgui.imnodes_end_output_attribute_DUP1()

parameters

none

return values

none

code sample

gh_imgui.imnodes_end_output_attribute()

imnodes_end_output_attribute_DUP2

syntax

gh_imgui.imnodes_end_output_attribute_DUP2()

parameters

none

return values

none

code sample

gh_imgui.imnodes_end_output_attribute()

imnodes_get_node_editor_space_pos

syntax

x, y = gh_imgui.imnodes_get_node_editor_space_pos (
node_id
)

parameters

node_id INTEGER 

return values

x, y REAL 

code sample

x, y = gh_imgui.imnodes_get_node_editor_space_pos(node_id)

imnodes_get_node_grid_space_pos

syntax

x, y = gh_imgui.imnodes_get_node_grid_space_pos (
node_id
)

parameters

node_id INTEGER 

return values

x, y REAL 

code sample

x, y = gh_imgui.imnodes_get_node_grid_space_pos(node_id)

imnodes_get_node_screen_space_pos

syntax

x, y = gh_imgui.imnodes_get_node_screen_space_pos (
node_id
)

parameters

node_id INTEGER 

return values

x, y REAL 

code sample

x, y = gh_imgui.imnodes_get_node_screen_space_pos(node_id)

imnodes_get_selected_node

syntax

node_id = gh_imgui.imnodes_get_selected_node (
index
)

parameters

index INTEGER 

return values

node_id INTEGER 

code sample

node_id = gh_imgui.imnodes_get_selected_node(index)

imnodes_is_editor_hovered

syntax

state = gh_imgui.imnodes_is_editor_hovered()

parameters

none

return values

state BOOLEAN 1 or 0

code sample

state = gh_imgui.imnodes_is_editor_hovered()

imnodes_is_node_hovered

syntax

state, node_id = gh_imgui.imnodes_is_node_hovered()

parameters

none

return values

state BOOLEAN 1 or 0
node_id INTEGER

code sample

state, node_id = gh_imgui.imnodes_is_node_hovered()

imnodes_is_node_selected

syntax

state = gh_imgui.imnodes_is_node_selected (
node_id
)

parameters

node_id INTEGER 

return values

state BOOLEAN 

code sample

state = gh_imgui.imnodes_is_node_selected(node_id)

imnodes_is_pin_hovered

syntax

state, pin_id = gh_imgui.imnodes_is_pin_hovered()

parameters

none

return values

state BOOLEAN 1 or 0
pin_id INTEGER

code sample

state, pin_id = gh_imgui.imnodes_is_pin_hovered()

imnodes_minimap

syntax

gh_imgui.imnodes_minimap (
minimap_size_fraction,
minimap_location
)

parameters

minimap_size_fraction REAL 
minimap_location INTEGER

return values

none

code sample

ImNodesMiniMapLocation_BottomLeft = 0
ImNodesMiniMapLocation_BottomRight = 1
ImNodesMiniMapLocation_TopLeft = 2
ImNodesMiniMapLocation_TopRight = 3

minimap_size_fraction = 0.2			
minimap_location = ImNodesMiniMapLocation_BottomLeft
gh_imgui.imnodes_minimap(minimap_size_fraction, minimap_location)

imnodes_num_selected_nodes

syntax

n = gh_imgui.imnodes_num_selected_nodes()

parameters

none

return values

n INTEGER 

code sample

n = gh_imgui.imnodes_num_selected_nodes()

imnodes_pop_color_style

syntax

gh_imgui.imnodes_pop_color_style()

parameters

none

return values

none

code sample

gh_imgui.imnodes_pop_color_style()

imnodes_pop_style_var

syntax

gh_imgui.imnodes_pop_style_var()

parameters

none

return values

none

code sample

gh_imgui.imnodes_pop_style_var()

imnodes_push_color_style

syntax

r, g, b, a = gh_imgui.imnodes_push_color_style (
color_item
)

parameters

color_item INTEGER 

return values

r, g, b, a REAL 

code sample

ImNodesCol_NodeBackground = 0
ImNodesCol_NodeBackgroundHovered = 1
ImNodesCol_NodeBackgroundSelected = 2
ImNodesCol_NodeOutline = 3
ImNodesCol_TitleBar = 4
ImNodesCol_TitleBarHovered = 5
ImNodesCol_TitleBarSelected = 6
ImNodesCol_Link = 7
ImNodesCol_LinkHovered = 8
ImNodesCol_LinkSelected = 9
ImNodesCol_Pin = 10
ImNodesCol_PinHovered = 11
ImNodesCol_BoxSelector = 12
ImNodesCol_BoxSelectorOutline = 13
ImNodesCol_GridBackground = 14
ImNodesCol_GridLine = 15
ImNodesCol_MiniMapBackground = 16
ImNodesCol_MiniMapBackgroundHovered = 17
ImNodesCol_MiniMapOutline = 18
ImNodesCol_MiniMapOutlineHovered = 19
ImNodesCol_MiniMapNodeBackground = 20
ImNodesCol_MiniMapNodeBackgroundHovered = 21
ImNodesCol_MiniMapNodeBackgroundSelected = 22
ImNodesCol_MiniMapNodeOutline = 23
ImNodesCol_MiniMapLink = 24
ImNodesCol_MiniMapLinkSelected = 25

color_item = ImNodesCol_TitleBar
gh_imgui.imnodes_push_color_style(color_item, r, g, b, a)

imnodes_push_style_var

syntax

value = gh_imgui.imnodes_push_style_var (
style_item
)

parameters

style_item INTEGER 

return values

value REAL 

code sample

ImNodesStyleVar_GridSpacing = 0
ImNodesStyleVar_NodeCornerRounding = 1
ImNodesStyleVar_NodePaddingHorizontal = 2
ImNodesStyleVar_NodePaddingVertical = 3
ImNodesStyleVar_NodeBorderThickness = 4
ImNodesStyleVar_LinkThickness = 5
ImNodesStyleVar_LinkLineSegmentsPerLength = 6
ImNodesStyleVar_LinkHoverDistance = 7
ImNodesStyleVar_PinCircleRadius = 8
ImNodesStyleVar_PinQuadSideLength = 9
ImNodesStyleVar_PinTriangleSideLength = 10
ImNodesStyleVar_PinLineThickness = 11
ImNodesStyleVar_PinHoverRadius = 12
ImNodesStyleVar_PinOffset = 13

style_item = ImNodesStyleVar_GridSpacing
value = 24
gh_imgui.imnodes_push_style_var(style_item, value)

imnodes_read_selected_nodes

syntax

gh_imgui.imnodes_read_selected_nodes()

parameters

none

return values

none

code sample

gh_imgui.imnodes_read_selected_nodes()

imnodes_select_node

syntax

gh_imgui.imnodes_select_node (
node_id
)

parameters

node_id INTEGER 

return values

none

code sample

gh_imgui.imnodes_select_node(node_id)

imnodes_set_node_draggable

syntax

gh_imgui.imnodes_set_node_draggable (
node_id,
state
)

parameters

node_id INTEGER 
state BOOLEAN 1 or 0

return values

none

code sample

gh_imgui.imnodes_set_node_draggable(state)

imnodes_set_node_editor_space_pos

syntax

gh_imgui.imnodes_set_node_editor_space_pos (
node_id,
x, y
)

parameters

node_id INTEGER 
x, y REAL

return values

none

code sample

gh_imgui.imnodes_set_node_editor_space_pos(node_id, x, y)

imnodes_set_node_grid_space_pos

syntax

gh_imgui.imnodes_set_node_grid_space_pos (
node_id,
x, y
)

parameters

node_id INTEGER 
x, y REAL

return values

none

code sample

gh_imgui.imnodes_set_node_grid_space_pos(node_id, x, y)

imnodes_set_node_screen_space_pos

syntax

gh_imgui.imnodes_set_node_screen_space_pos (
node_id,
x, y
)

parameters

node_id INTEGER 
x, y REAL

return values

none

code sample

gh_imgui.imnodes_set_node_screen_space_pos(node_id, x, y)

implot_add_data

Adds data to a plot.
If the plot has been created with max_points greater than zero, data is stored in a circular buffer otherwise in a regular (endless) buffer.

syntax

gh_imgui.implot_add_data (
plotid,
x, y
)

parameters

plotid INTEGER plot identifier.
x, y REAL plot data.

return values

none

code sample

gh_imgui.implot_add_data(plotid, x, y)

implot_begin_plot

Begins the rendering of one or several plots.

syntax

gh_imgui.implot_begin_plot (
label_DUP1,
x_label,
y_label,
label_DUP2,
x, y,
flags,
x_flags,
y_flags,
y2_flags,
y3_flags
)

parameters

label_DUP1 STRING plot label.
x_label STRING X axis label.
y_label STRING y axis label.
label_DUP2 STRING plot label.
x, y REAL plot size.
flags INTEGER plot flags/options.
x_flags INTEGER X axis flags/options.
y_flags INTEGER Y axis flags/options.
y2_flags INTEGER Y axis additional flags/options.
y3_flags INTEGER Y axis additional flags/options.

return values

none

code sample

gh_imgui.implot_begin_plot(label, x_label, y_label, x_size, y_size, flags, x_flags, y_flags, y2_flags, y3_flags)

gh_imguiimplot_draw_plotline(plotid0, ...)
gh_imguiimplot_draw_plotline(plotid1, ...)

gh_imgui.implot_end_plot()

implot_create_dataplot

Creates a plot data set.
This data set will be used with implot_begin_plot() and implot_end_plot() to draw a plot.

syntax

plotid = gh_imgui.implot_create_dataplot (
max_points
)

parameters

max_points INTEGER max number of points of the data plot. Can be 0

return values

plotid INTEGER plot identifier.

code sample

plotid = gh_imgui.implot_create_dataplot(max_points)

implot_draw_plotbars

Draws a plot data set.

syntax

gh_imgui.implot_draw_plotbars (
plotid,
label,
count,
offset,
size,
vertical
)

parameters

plotid INTEGER plot identifier.
label STRING plot data label.
count INTEGER number of points to draw.
offset INTEGER plot data offset.
size REAL size.
vertical INTEGER vertical (1) or hozizontal (0) bars.

return values

none

code sample

gh_imgui.implot_draw_plotbars(plotid, label, count, offset, size, vertical)

implot_draw_plotline

Draws a plot data set.

syntax

gh_imgui.implot_draw_plotline (
plotid,
label,
count,
offset
)

parameters

plotid INTEGER plot identifier.
label STRING plot data label.
count INTEGER number of points to draw.
offset INTEGER plot data offset.

return values

none

code sample

gh_imgui.implot_draw_plotline(plotid, label, count, offset)

implot_draw_plotscatter

Draws a plot data set.

syntax

gh_imgui.implot_draw_plotscatter (
plotid,
label,
count,
offset
)

parameters

plotid INTEGER plot identifier.
label STRING plot data label.
count INTEGER number of points to draw.
offset INTEGER plot data offset.

return values

none

code sample

gh_imgui.implot_draw_plotscatter(plotid, label, count, offset)

implot_draw_plotshaded

Draws a plot data set.

syntax

gh_imgui.implot_draw_plotshaded (
plotid,
label,
count,
offset
)

parameters

plotid INTEGER plot identifier.
label STRING plot data label.
count INTEGER number of points to draw.
offset INTEGER plot data offset.

return values

none

code sample

gh_imgui.implot_draw_plotshaded(plotid, label, count, offset)

implot_end_plot

Ends plot rendering.

syntax

gh_imgui.implot_end_plot()

parameters

none

return values

none

code sample

gh_imgui.implot_end_plot()

implot_get_mouse_pos

Gets mouse position

syntax

x, y = gh_imgui.implot_get_mouse_pos()

parameters

none

return values

x, y REAL mouse position.

code sample

x, y = gh_imgui.implot_get_mouse_pos()

implot_is_hovered

Checks if mouse is over the plot

syntax

state = gh_imgui.implot_is_hovered()

parameters

none

return values

state INTEGER 1 (hovered) or 0 (not hovered).

code sample

is_hovered = gh_imgui.implot_is_hovered()

implot_kill_dataplot

Destroy a plot data set.

syntax

gh_imgui.implot_kill_dataplot (
plotid
)

parameters

plotid INTEGER plot identifier.

return values

none

code sample

gh_imgui.implot_kill_dataplot(plotid)

implot_plottext

Draw a text on a plot at position x, y

syntax

gh_imgui.implot_plottext (
text,
x, y,
vertical,
offset_x, offset_y
)

parameters

text STRING text
x, y REAL text position
vertical INTEGER vertical (1) or horizontal (0) text
offset_x, offset_y REAL offset

return values

none

code sample

gh_imgui.implot_plottext(text, x, y, vertical, offset_x, offset_y)

implot_pop_colormap

Pops (or restores) a color map.

syntax

gh_imgui.implot_pop_colormap (
count
)

parameters

count INTEGER undo multiple pushes at once by increasing count.

return values

none

code sample

ImPlotColormap_Deep     = 0
ImPlotColormap_Dark     = 1
ImPlotColormap_Pastel   = 2
ImPlotColormap_Paired   = 3
ImPlotColormap_Viridis  = 4

gh_imgui.implot_push_colormap(ImPlotColormap_Dark)
...
gh_imgui.implot_pop_colormap(1)

implot_pop_style_color

Restores a color

syntax

gh_imgui.implot_pop_style_color (
count
)

parameters

count INTEGER number of colors to restore (default: 1).

return values

none

code sample

gh_imgui.implot_push_style_color(ImPlotCol_Line, r, g, b, a)
gh_imgui.implot_draw_plotline(plotid1, "MouseX", max_size, offset)
gh_imgui.implot_pop_style_color(1)

implot_push_colormap

Pushes a color map.
This color map is the new active color map.
The color map is specified by an index.
Call implot_pop_colormap() to restore previous color map.

syntax

gh_imgui.implot_push_colormap (
colormap_index
)

parameters

colormap_index INTEGER colormap index/identifier.

return values

none

code sample

ImPlotColormap_Deep     = 0
ImPlotColormap_Dark     = 1
ImPlotColormap_Pastel   = 2
ImPlotColormap_Paired   = 3
ImPlotColormap_Viridis  = 4
ImPlotColormap_Plasma   = 5
ImPlotColormap_Hot      = 6
ImPlotColormap_Cool     = 7
ImPlotColormap_Pink     = 8
ImPlotColormap_Jet      = 9
ImPlotColormap_Twilight = 10
ImPlotColormap_RdBu     = 11
ImPlotColormap_BrBG     = 12
ImPlotColormap_PiYG     = 13
ImPlotColormap_Spectral = 14
ImPlotColormap_Greys    = 15

gh_imgui.implot_push_colormap(ImPlotColormap_Plasma)
...
gh_imgui.implot_pop_colormap(1)

implot_push_style_color

Saves the current color and pushes a new color.

syntax

gh_imgui.implot_push_style_color (
color_index,
r, g, b, a
)

parameters

color_index INTEGER index (identifier) of the color.
r, g, b, a REAL RGBA color.

return values

none

code sample

ImPlotCol_Line = 0
ImPlotCol_Fill = 1
ImPlotCol_MarkerOutline = 2
ImPlotCol_MarkerFill = 3
ImPlotCol_ErrorBar = 4
ImPlotCol_FrameBg = 5
ImPlotCol_PlotBg = 6
ImPlotCol_PlotBorder = 7
ImPlotCol_XAxis = 8
ImPlotCol_YAxis = 9
ImPlotCol_YAxis2 = 10
ImPlotCol_YAxis3 = 11
ImPlotCol_Selection = 12
ImPlotCol_Query = 13

gh_imgui.implot_push_style_color(ImPlotCol_Line, r, g, b, a)
gh_imgui.implot_draw_plotline(plotid1, "MouseX", max_size, offset)
gh_imgui.implot_pop_style_color(1)

implot_push_style_var_1f

Saves a property and pushes a new one

syntax

gh_imgui.implot_push_style_var_1f (
var_id,
x
)

parameters

var_id INTEGER variable identifier.
x REAL value.

return values

none

code sample

ImPlotStyleVar_LineWeight = 0
ImPlotStyleVar_Marker = 1
ImPlotStyleVar_MarkerSize = 2
ImPlotStyleVar_MarkerWeight = 3
ImPlotStyleVar_FillAlpha = 4
ImPlotStyleVar_ErrorBarSize = 5
ImPlotStyleVar_ErrorBarWeight = 6
ImPlotStyleVar_DigitalBitHeight = 7
ImPlotStyleVar_DigitalBitGap = 8

gh_imgui.implot_push_style_var_1i(ImPlotStyleVar_FillAlpha, 0.5)
gh_imgui.implot_draw_plotline(plotid1, "MouseX", max_size, offset)
gh_imgui.implot_pop_style_var(1)

implot_push_style_var_1i

Saves a property and pushes a new one

syntax

gh_imgui.implot_push_style_var_1i (
var_id,
x
)

parameters

var_id INTEGER variable identifier.
x INTEGER value.

return values

none

code sample

ImPlotStyleVar_LineWeight = 0
ImPlotStyleVar_Marker = 1
ImPlotStyleVar_MarkerSize = 2
ImPlotStyleVar_MarkerWeight = 3
ImPlotStyleVar_FillAlpha = 4
ImPlotStyleVar_ErrorBarSize = 5
ImPlotStyleVar_ErrorBarWeight = 6
ImPlotStyleVar_DigitalBitHeight = 7
ImPlotStyleVar_DigitalBitGap = 8

ImPlotMarker_None        = 1
ImPlotMarker_Circle      = 2
ImPlotMarker_Square      = 4
ImPlotMarker_Diamond     = 8
ImPlotMarker_Up          = 16
ImPlotMarker_Down        = 32
ImPlotMarker_Left        = 64
ImPlotMarker_Right       = 128
ImPlotMarker_Cross       = 256
ImPlotMarker_Plus        = 512
ImPlotMarker_Asterisk    = 1024

gh_imgui.implot_push_style_var_1i(ImPlotStyleVar_Marker, ImPlotMarker_Circle)
gh_imgui.implot_draw_plotline(plotid1, "MouseX", max_size, offset)
gh_imgui.implot_pop_style_var(1)

implot_set_next_plot_limits

Sets the limits (X and Y axis) of the next plot.

syntax

gh_imgui.implot_set_next_plot_limits (
x_min,
x_max,
y_min,
y_max,
cond
)

parameters

x_min INTEGER min limit in a X axis.
x_max INTEGER max limit in a X axis.
y_min INTEGER min limit in a Y axis.
y_max INTEGER max limit in a Y axis.
cond INTEGER

return values

none

code sample

ImGuiCond_None          = 0
ImGuiCond_Always        = 1
ImGuiCond_Once          = 2
ImGuiCond_FirstUseEver  = 4
ImGuiCond_Appearing     = 8

gh_imgui.implot_set_next_plot_limits(x-10, x, -10, 30, ImGuiCond_Always)

implot_show_demo_window

Displays the official ImPlot demo.

syntax

gh_imgui.implot_show_demo_window (
show_window
)

parameters

show_window INTEGER 

return values

none

code sample

gh_imgui.implot_show_demo_window(show_window)

indent

Sets indent spacing.

syntax

gh_imgui.indent (
indent_w
)

parameters

indent_w REAL size

return values

none

code sample

indent_w = 10.0
gh_imgui.indent(indent_w)

init

Initialize the ImGui library.
Must be called once in the INIT script.

syntax

error = gh_imgui.init()

parameters

none

return values

error BOOLEAN 1 (success) or 0 (error)

code sample

ret = gh_imgui.init()

input_text

Allows to type a text.

syntax

state, text = gh_imgui.input_text (
label,
max_text_len,
initial_text,
flags
)

parameters

label STRING name of the input field
max_text_len INTEGER max text lenght in bytes (4096 bytes is the default value if max_text_len is set to 0)
initial_text STRING initial text
flags ENUM( imgui_InputTextFlags ) ImGuiInputTextFlags_xxx options

return values

state BOOLEAN state (1 or 0). Useful with ImGuiInputTextFlags_EnterReturnsTrue
text STRING text

code sample

flags = ImGuiInputTextFlags_None

text, state = gh_imgui.input_text("User name", 128, "", flags)

invisible_button

Flexible button behavior without the visuals, frequently useful to build custom behaviors.

syntax

gh_imgui.invisible_button (
label,
w, h,
flags
)

parameters

label STRING label
w, h REAL size of the button
flags INTEGER options

return values

none

code sample

ImGuiButtonFlags_None                   = 0
ImGuiButtonFlags_MouseButtonLeft        = 1
ImGuiButtonFlags_MouseButtonRight       = 2
ImGuiButtonFlags_MouseButtonMiddle      = 4

gh_imgui.invisible_button("canvas", 320, 180, ImGuiButtonFlags_None)

is_any_item_hovered

Check if any item has been hovered by mouse.

syntax

hovered = gh_imgui.is_any_item_hovered()

parameters

none

return values

hovered BOOLEAN hovered: 1 (true) or 0 (false)

code sample

hovered = gh_imgui.is_any_item_hovered()

is_any_window_hovered

Check if any window has been hovered by mouse.

syntax

hovered = gh_imgui.is_any_window_hovered()

parameters

none

return values

hovered BOOLEAN hovered: 1 (true) or 0 (false)

code sample

hovered = gh_imgui.is_any_window_hovered()

is_item_clicked

Check if the current item has been clicked.

syntax

clicked = gh_imgui.is_item_clicked (
mouse_button
)

parameters

mouse_button ENUM( imgui_Mouse ) left button (0) or right button (1)

return values

clicked BOOLEAN clicked: 1 (true) or 0 (false)

code sample

clicked = gh_imgui.is_item_clicked(0)

is_item_hovered

Check if the current item has been hovered by mouse.

syntax

hovered = gh_imgui.is_item_hovered()

parameters

none

return values

hovered BOOLEAN hovered: 1 (true) or 0 (false)

code sample

hovered = gh_imgui.is_item_hovered()

is_mouse_clicked

Check if any window has been hovered by mouse.

syntax

state = gh_imgui.is_mouse_clicked (
button
)

parameters

button ENUM( mouse_button ) mouse button: 0 (left), 1 (right) or 2 (middle)

return values

state BOOLEAN clicked: 1 (true) or 0 (false)

code sample

state = gh_imgui.is_mouse_clicked(button)

is_window_hovered

Check if the current window has been hovered by mouse.

syntax

hovered = gh_imgui.is_window_hovered()

parameters

none

return values

hovered BOOLEAN hovered: 1 (true) or 0 (false)

code sample

hovered = gh_imgui.is_window_hovered()

knob

Displays a knob

syntax

out_value, ret = gh_imgui.knob (
label,
in_value,
v_min, v_max,
speed,
format,
knob_type,
size,
flags,
steps
)

parameters

label STRING label
in_value REAL initial value
v_min, v_max REAL min and max values
speed REAL animation speed
format STRING how the value is displayed.
knob_type INTEGER type of the knob: tick, dot, wiper, ...
size REAL size in pixels of the knob
flags INTEGER flags
steps INTEGER number of steps from start to end

return values

out_value REAL value of the knob between v_min and _vmax
ret INTEGER return code: 1 if OK, 0 if error

code sample

ImGuiKnobVariant_Tick = 1
ImGuiKnobVariant_Dot = 2
ImGuiKnobVariant_Wiper = 4
ImGuiKnobVariant_WiperOnly = 8
ImGuiKnobVariant_WiperDot = 16
ImGuiKnobVariant_Stepped = 32
ImGuiKnobVariant_Space = 64 


ImGuiKnobFlags_NoTitle = 1
ImGuiKnobFlags_NoInput = 2
ImGuiKnobFlags_ValueTooltip = 4
ImGuiKnobFlags_DragHorizontal = 8

-- this is special flag fopr GeeXLab only.
ImGuiKnobFlags_ReadOnlyInput = 16 
-- this is special flag fopr GeeXLab only.
ImGuiKnobFlags_DisableMouse = 32 

value, ret = gh_imgui.knob(label, init_value, v_min, v_max, speed, format, type, size, flags, steps)

list_box_begin

Defines a list box header.

syntax

ret = gh_imgui.list_box_begin (
cb_index,
w, h
)

parameters

cb_index INTEGER combo box index
w, h REAL size of the list box

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_imgui.list_box_begin(cb_index, 0)

list_box_draw

Draws a combo box as a list box.

syntax

selected_item = gh_imgui.list_box_draw (
cb_id,
initial_selected_item
)

parameters

cb_id ID combo box identifier
initial_selected_item INTEGER index of the initial selected item

return values

selected_item INTEGER index of the current selected item

code sample

selected_item = gh_imgui.list_box_draw(cb_id, 0)

list_box_draw_v2

Draws a combo box as a list box.

syntax

selected_item = gh_imgui.list_box_draw_v2 (
cb_id,
initial_selected_item,
height_in_items
)

parameters

cb_id ID combo box identifier
initial_selected_item INTEGER index of the initial selected item
height_in_items INTEGER height of the list box in items

return values

selected_item INTEGER index of the current selected item

code sample

selected_item = gh_imgui.list_box_draw_v2(cb_id, 0, 20)

list_box_end

Ends a list box header.

syntax

gh_imgui.list_box_end()

parameters

none

return values

none

code sample

gh_imgui.list_box_end()

list_clipping_begin

Starts the list clipping.
Allows to speed up rendering of very big lists.

syntax

start_item, end_item = gh_imgui.list_clipping_begin (
num_items
)

parameters

num_items INTEGER number of items

return values

start_item, end_item INTEGER range coreved by the list clipper

code sample

start_item, end_item = gh_imgui.list_clipping_begin(num_items)

list_clipping_end

Ends the list clipping.

syntax

gh_imgui.list_clipping_end (
num_items,
start_item, end_item
)

parameters

num_items INTEGER number of items
start_item, end_item INTEGER range coreved by the list clipper

return values

none

code sample

gh_imgui.list_clipping_end(num_items, start_item, end_item)

memory_editor_create

Creates a memory editor instance.

syntax

meid = gh_imgui.memory_editor_create (
size
)

parameters

size INTEGER size of the window

return values

meid ID memory editor identifier

code sample

meid = gh_imgui.memory_editor_create(1024)

memory_editor_draw_window_DUP1

Draws the window of a memory editor.

syntax

gh_imgui.memory_editor_draw_window_DUP1 (
meid,
title
)

parameters

meid ID memory editor identifier
title STRING title of the window

return values

none

code sample

gh_imgui.memory_editor_draw_window(meid, title)

memory_editor_draw_window_DUP2

Draws the content of a memory editor.

syntax

gh_imgui.memory_editor_draw_window_DUP2 (
meid
)

parameters

meid ID memory editor identifier

return values

none

code sample

gh_imgui.memory_editor_draw_contents(meid)

memory_editor_kill

Destroys a memory editor instance.

syntax

gh_imgui.memory_editor_kill (
meid
)

parameters

meid ID memory editor identifier

return values

none

code sample

gh_imgui.memory_editor_kill(meid)

memory_editor_read_data_from_buffer

Reads data from a memory buffer.

syntax

gh_imgui.memory_editor_read_data_from_buffer (
meid,
buffer,
buffer_size
)

parameters

meid ID memory editor identifier
buffer POINTER memory buffer. See memory buffer function of gh_utils.
buffer_size INTEGER size in bytes of memory buffer.

return values

none

code sample

gh_imgui.memory_editor_read_data_from_buffer(meid, buffer, buffer_size)

memory_editor_read_data_from_file

Fills the content with the data from a file.

syntax

gh_imgui.memory_editor_read_data_from_file (
meid,
filename
)

parameters

meid ID memory editor identifier
filename STRING absolute path to the file

return values

none

code sample

gh_imgui.memory_editor_read_data_from_file(meid, filename)

memory_editor_resize

Resizes a memory editor instance.

syntax

gh_imgui.memory_editor_resize (
meid,
size
)

parameters

meid ID memory editor identifier
size INTEGER size of the window

return values

none

code sample

gh_imgui.memory_editor_resize(meid, 512)

memory_editor_set_data_from_texture

Fills the content with the data from a texture.

syntax

gh_imgui.memory_editor_set_data_from_texture (
meid,
tid
)

parameters

meid ID memory editor identifier
tid ID texture identifier

return values

none

code sample

gh_imgui.memory_editor_set_data_from_texture(meid, tid)

memory_editor_set_value_1u8

Writes a byte.

syntax

gh_imgui.memory_editor_set_value_1u8 (
meid,
index,
x
)

parameters

meid ID memory editor identifier
index INTEGER index of the value
x INTEGER value

return values

none

code sample

gh_imgui.memory_editor_set_value_1u8(meid, 0, 128)

memory_editor_write_data_to_buffer

Writes data to a memory buffer.

syntax

gh_imgui.memory_editor_write_data_to_buffer (
meid,
buffer,
buffer_size
)

parameters

meid ID memory editor identifier
buffer POINTER memory buffer. See memory buffer function of gh_utils.
buffer_size INTEGER size in bytes of memory buffer.

return values

none

code sample

gh_imgui.memory_editor_write_data_to_buffer(meid, buffer, buffer_size)

memory_editor_write_data_to_file

Writes the content to a file.

syntax

gh_imgui.memory_editor_write_data_to_file (
meid,
filename
)

parameters

meid ID memory editor identifier
filename STRING absolute path to the file

return values

none

code sample

gh_imgui.memory_editor_write_data_to_file(meid, filename)

menu_begin

Begins a window menu.

syntax

state = gh_imgui.menu_begin (
label,
enabled
)

parameters

label STRING menu label
enabled BOOLEAN menu: 1 (enabled) or 0 (disabled)

return values

state BOOLEAN 1 or 0 - only call menu_end() if this returns 1

code sample

gh_imgui.menu_begin("File", 1)

menu_begin_bar

Begins a window menu bar.

syntax

state = gh_imgui.menu_begin_bar()

parameters

none

return values

state BOOLEAN 1 or 0 - only call menu_end_bar() if this returns 1

code sample

gh_imgui.menu_begin_bar()

menu_begin_main_bar

Begins the main menu bar (fullscreen menu bar).

syntax

state = gh_imgui.menu_begin_main_bar()

parameters

none

return values

state BOOLEAN 1 or 0 - only call menu_end_main_bar() if this returns 1

code sample

gh_imgui.menu_begin_main_bar()

menu_end

Ends a window menu.

syntax

gh_imgui.menu_end()

parameters

none

return values

none

code sample

gh_imgui.menu_end()

menu_end_bar

Ends a window menu bar.

syntax

gh_imgui.menu_end_bar()

parameters

none

return values

none

code sample

gh_imgui.menu_end_bar()

menu_end_main_bar

Ends the main menu bar.

syntax

gh_imgui.menu_end_main_bar()

parameters

none

return values

none

code sample

gh_imgui.menu_end_main_bar()

menu_item

Adds an item to the current menu.
Must be used between menu_begin() and menu_end().

syntax

state = gh_imgui.menu_item (
label,
shortcut,
selected,
enabled
)

parameters

label STRING menu label
shortcut STRING menu shortcut (not implemented) - set this value to ''
selected BOOLEAN menu selected: 1 (true) or 0 (false)
enabled BOOLEAN menu enabled: 1 (true) or 0 (false)

return values

state BOOLEAN clicked: 1 (true) or 0 (false)

code sample

enabled = 1

gh_imgui.menu_item("Load a file", "", 0, enabled)

plot_add_item

Adds a new item (a line) to an existing plotline.

syntax

item_index = gh_imgui.plot_add_item (
plot_id,
label,
type
)

parameters

plot_id ID plotline identifier
label STRING label
type INTEGER line: 0, scatter: 1, xbar: 2 or ybar: 3

return values

item_index INTEGER index of the new item

code sample

type_line = 0
type_scatter = 1
type_xbar = 2
type_ybar = 3
item_index = gh_imgui.plot_add_item(plot_id, "myNewItem", type_line)

plot_axis_scroll

Call before rendering a plot to scroll the axis in time, displaying history seconds.

syntax

gh_imgui.plot_axis_scroll (
plot_id,
axis,
current_time,
history
)

parameters

plot_id ID plotline identifier
axis INTEGER X axis: 0, Y axis: 1
current_time REAL current time
history REAL history seconds

return values

none

code sample

gh_imgui.plot_axis_scroll(plot_id, axis, current_time, history)

plot_draw

Draws a plotline.

syntax

gh_imgui.plot_draw (
plot_id,
label,
num_items,
size_x, size_y
)

parameters

plot_id ID plotline identifier
label STRING name of the plotline
num_items INTEGER number of lines to draw
size_x, size_y REAL plotline frame size

return values

none

code sample

gh_imgui.plot_draw(plot_id, label, num_items, size_x, size_y)

plot_get_mouse_position

Gets the mouse position related to the plotline.

syntax

x, y = gh_imgui.plot_get_mouse_position()

parameters

none

return values

x, y REAL mouse position

code sample

x, y = gh_imgui.plot_get_mouse_position()

plot_is_hovered

Checks if a plotline is hovered by the mouse.

syntax

state = gh_imgui.plot_is_hovered()

parameters

none

return values

state INTEGER 1: hovered, 0: not hovered

code sample

state = gh_imgui.plot_is_hovered()

plot_item_add_data

Adds data to an item.

syntax

gh_imgui.plot_item_add_data (
plot_id,
item_index,
x, y
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
x, y REAL data - these are the line values in Y and Y

return values

none

code sample

gh_imgui.plot_item_add_data(plot_id, item_index, x, y)

plot_item_buffer_point

Pushes a point into an item data set as if it were a circular buffer of #max_points size.

syntax

gh_imgui.plot_item_buffer_point (
plot_id,
item_index,
x, y,
max_points
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
x, y REAL data - these are the line values in Y and Y
max_points INTEGER max number of points

return values

none

code sample

gh_imgui.plot_item_buffer_point(plot_id, item_index, x, y, max_points)

plot_item_clear_data_DUP1

Clears all data of an item.

syntax

gh_imgui.plot_item_clear_data_DUP1 (
plot_id,
item_index
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item

return values

none

code sample

gh_imgui.plot_item_clear_data(plot_id, item_index)

plot_item_clear_data_DUP2

Resize data of an item.

syntax

gh_imgui.plot_item_clear_data_DUP2 (
plot_id,
item_index,
n
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
n INTEGER data size

return values

none

code sample

gh_imgui.plot_item_resize_data(plot_id, item_index, n)

plot_item_get_data_size

Gets the data size of an item.

syntax

n = gh_imgui.plot_item_get_data_size (
plot_id,
item_index
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item

return values

n INTEGER data size

code sample

n = gh_imgui.plot_item_get_data_size(plot_id, item_index)

plot_item_roll_point

Adds a point to an item data set, clearing it every span seconds.

syntax

gh_imgui.plot_item_roll_point (
plot_id,
item_index,
x, y,
span
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
x, y REAL data - these are the line values in Y and Y
span REAL duration in seconds

return values

none

code sample

gh_imgui.plot_item_roll_point(plot_id, item_index, x, y, span)

plot_item_set_color

Sets the color of an item.

syntax

gh_imgui.plot_item_set_color (
plot_id,
item_index,
r, g, b, a
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
r, g, b, a REAL RGBA color

return values

none

code sample

gh_imgui.plot_item_set_color(plot_id, item_index, r, g, b, a)

plot_item_set_data

Sets data of an item.

syntax

gh_imgui.plot_item_set_data (
plot_id,
item_index,
data_index,
x, y
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
data_index INTEGER index of the data
x, y REAL data - these are the line values in Y and Y

return values

none

code sample

gh_imgui.plot_item_set_data(plot_id, item_index, , data_index, x, y)

plot_item_set_data_begin

Sets the start offset.

syntax

gh_imgui.plot_item_set_data_begin (
plot_id,
item_index,
x
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
x INTEGER offset

return values

none

code sample

gh_imgui.plot_item_set_data_begin(plot_id, item_index, 0)

plot_item_set_label

Sets a label of an item.

syntax

gh_imgui.plot_item_set_label (
plot_id,
item_index,
label
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
label STRING label

return values

none

code sample

gh_imgui.plot_add_item(plot_id, item_index, "myItem")

plot_item_set_size

Sets the size (or tickness) of an item.

syntax

gh_imgui.plot_item_set_size (
plot_id,
item_index,
size
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
size REAL size (or tickness)

return values

none

code sample

gh_imgui.plot_item_set_size(plot_id, item_index, 2.0)

plot_item_set_type

Sets the type of an item.

syntax

gh_imgui.plot_item_set_type (
plot_id,
item_index,
type
)

parameters

plot_id ID plotline identifier
item_index INTEGER index of the item
type INTEGER line: 0, scatter: 1, xbar: 2 or ybar: 3

return values

none

code sample

gh_imgui.plot_item_set_type(plot_id, item_index, type)

plot_kill

Destroys a plotline.

syntax

gh_imgui.plot_kill (
plot_id
)

parameters

plot_id ID plotline identifier

return values

none

code sample

gh_imgui.plot_kill(plot_id)

plot_set_axis_color

Sets the color of an axis.

syntax

gh_imgui.plot_set_axis_color (
plot_id,
axis,
r, g, b, a
)

parameters

plot_id ID plotline identifier
axis INTEGER X axis: 0 or Y axis: 1
r, g, b, a REAL RGBA color

return values

none

code sample

axis_y = 1			
gh_imgui.plot_set_axis_color(plot_id, axis_y, r, g, b, a)

plot_set_axis_label

Sets the label of an axis.

syntax

gh_imgui.plot_set_axis_label (
plot_id,
axis,
label
)

parameters

plot_id ID plotline identifier
axis INTEGER X axis: 0 or Y axis: 1
label STRING label

return values

none

code sample

axis_y = 1			
gh_imgui.plot_set_axis_label(plot_id, axis_y, "Y axis")

plot_set_axis_param_bool

Sets the state a of particular element of an axis.

syntax

gh_imgui.plot_set_axis_param_bool (
plot_id,
axis,
what,
state
)

parameters

plot_id ID plotline identifier
axis INTEGER X axis: 0 or Y axis: 1
what STRING element name: 'show_grid', 'show_tick_marks', 'show_tick_labels', 'adaptive', 'lock_max', 'lock_min', 'flip'
state BOOLEAN 0 (disabled) or 1 (enabled)

return values

none

code sample

axis_x = 0			
axis_y = 1			
state = 1
gh_imgui.plot_set_axis_param_bool(plot_id, axis_x, "show_grid", state)
gh_imgui.plot_set_axis_param_bool(plot_id, axis_y, "show_grid", state)

plot_set_axis_param_float

Sets the value a of particular element of an axis.

syntax

gh_imgui.plot_set_axis_param_float (
plot_id,
axis,
what,
x
)

parameters

plot_id ID plotline identifier
axis INTEGER X axis: 0 or Y axis: 1
what STRING element name: 'minimum', 'maximum', 'zoom_rate'
x REAL value

return values

none

code sample

axis_y = 1			
gh_imgui.plot_set_axis_param_float(plot_id, axis_y, "minimum", -10.0)
gh_imgui.plot_set_axis_param_bool(plot_id, axis_y, "minimum", 10.0)

plot_set_axis_param_int

Sets the value a of particular element of an axis.

syntax

gh_imgui.plot_set_axis_param_int (
plot_id,
axis,
what,
x
)

parameters

plot_id ID plotline identifier
axis INTEGER X axis: 0 or Y axis: 1
what STRING element name: 'divisions', 'subdivisions'
x INTEGER value

return values

none

code sample

axis_x = 0			
gh_imgui.plot_set_axis_param_int(plot_id, axis_x, "divisions", 10)
gh_imgui.plot_set_axis_param_int(plot_id, axis_x, "subdivisions", 4)

plot_set_color

Sets the color a of particular element of a plotline.

syntax

gh_imgui.plot_set_color (
plot_id,
what,
r, g, b, a
)

parameters

plot_id ID plotline identifier
what STRING element name: 'frame', 'background', 'border'
r, g, b, a REAL RGBA color

return values

none

code sample

gh_imgui.plot_set_color(plot_id, "background", 0.4, 0.4, 0.4, 0.85)

plot_set_state

Sets the state a of particular element of a plotline.

syntax

gh_imgui.plot_set_state (
plot_id,
what,
state
)

parameters

plot_id ID plotline identifier
what STRING element name: 'show_crosshairs', 'show_mouse_pos', 'show_legend'
state BOOLEAN 0 (disabled) or 1 (enabled)

return values

none

code sample

gh_imgui.plot_set_state(plot_id, "show_crosshairs", state)

plot_set_title

Sets the title a plotline.

syntax

gh_imgui.plot_set_title (
plot_id,
title
)

parameters

plot_id ID plotline identifier
title STRING title of the plotline

return values

none

code sample

gh_imgui.plot_set_title(plot_id, title)

plotline_create

Creates a plotline.

syntax

index = gh_imgui.plotline_create (
label,
num_points
)

parameters

label STRING label
num_points INTEGER number of points in the plotline

return values

index INTEGER index of the new plotline

code sample

plotline_index = gh_imgui.plotline_create("Curve", 1000)

plotline_draw

Draws a plotline.

syntax

gh_imgui.plotline_draw (
index,
type,
overlay,
values_offset,
scale_min, scale_max,
graph_size_x, graph_size_y
)

parameters

index INTEGER index of the plotline
type ENUM( draw_type ) type: 1 (histogram) or 0 (line)
overlay STRING overlay text
values_offset INTEGER offset
scale_min, scale_max REAL minimal / maximal value
graph_size_x, graph_size_y REAL size of the graph

return values

none

code sample

values_offset = 0
scale_min = 0
scale_max = 100
graph_size_x = 400
graph_size_y = 200

gh_imgui.plotline_draw(plotline_index, type, "overlay!", values_offset, scale_min, scale_max, graph_size_x, graph_size_y)

plotline_draw_v2

Draws a plotline.

syntax

gh_imgui.plotline_draw_v2 (
index,
type,
overlay,
num_values,
values_offset,
scale_min, scale_max,
graph_size_x, graph_size_y
)

parameters

index INTEGER index of the plotline
type ENUM( draw_type ) type: 1 (histogram) or 0 (line)
overlay STRING overlay text
num_values INTEGER number of values to draw
values_offset INTEGER offset
scale_min, scale_max REAL minimal / maximal value
graph_size_x, graph_size_y REAL size of the graph

return values

none

code sample

values_offset = 0
values_count = 1000
scale_min = 0
scale_max = 100
graph_size_x = 400
graph_size_y = 200

gh_imgui.plotline_draw_v2(plotline_index, type, "overlay!", values_count, values_offset, scale_min, scale_max, graph_size_x, graph_size_y)

plotline_get_value1f

Gets a value from the plotline.

syntax

x = gh_imgui.plotline_get_value1f (
index,
value_index
)

parameters

index INTEGER index of the plotline
value_index INTEGER index of value in the plotline

return values

x REAL value

code sample

x = gh_imgui.plotline_get_value1f(plotline_index, value_index)

plotline_set_value1f

Sets a value in the plotline.

syntax

gh_imgui.plotline_set_value1f (
index,
value_index,
x
)

parameters

index INTEGER index of the plotline
value_index INTEGER index of value in the plotline
x REAL value

return values

none

code sample

gh_imgui.plotline_set_value1f(plotline_index, value_index, x)

pop_clip_rect

Pops (restores) a clipping rectangle for the current drawlist.

syntax

gh_imgui.pop_clip_rect()

parameters

none

return values

none

code sample

gh_imgui.pop_clip_rect()

pop_font

Restores the font saved by push_font().

syntax

gh_imgui.pop_font()

parameters

none

return values

none

code sample

gh_imgui.pop_font()

pop_item_width

Restore the width that has been changed by push_item_width().

syntax

gh_imgui.pop_item_width()

parameters

none

return values

none

code sample

local width = gh_imgui.get_content_region_available_width()

gh_imgui.push_item_width(width * 0.8)
...
gh_imgui.pop_item_width()

pop_style_color

Restores a color saved with push_style_color().

syntax

gh_imgui.pop_style_color()

parameters

none

return values

none

code sample

gh_imgui.pop_style_color()

popup_begin

Begins a popup window.
Click outside the popup to close it.

syntax

ret = gh_imgui.popup_begin (
label
)

parameters

label STRING label

return values

ret BOOLEAN popup opened: 1 (true) or 0 (false)

code sample

ret = gh_imgui.popup_begin("blabla")

popup_begin_context

Begins a popup window.

syntax

ret = gh_imgui.popup_begin_context (
label
)

parameters

label STRING label

return values

ret BOOLEAN popup opened: 1 (true) or 0 (false)

code sample

ret = gh_imgui.popup_begin_context("blabla")

popup_end

Ends a popup window.
Call this function only if popup_begin_xxx() return 1 (the popup is opened).

syntax

gh_imgui.popup_end()

parameters

none

return values

none

code sample

gh_imgui.popup_end()

popup_open

Call to mark popup as open (don't call every frame!)

syntax

gh_imgui.popup_open (
label
)

parameters

label STRING label

return values

none

code sample

gh_imgui.popup_open("blabla")

progress_bar

Displays a progress bar.

syntax

gh_imgui.progress_bar (
fraction,
width, height,
overlay
)

parameters

fraction REAL progression of the bar: from 0.0 to 1.0
width, height INTEGER size of the bar
overlay STRING overlay text

return values

none

code sample

gh_imgui.progress_bar(0.45, width, height, overlay_str)

push_clip_rect

Pushes (saves) a clipping rectangle for the current drawlist.

syntax

gh_imgui.push_clip_rect (
x_min, y_min,
x_max, y_max
)

parameters

x_min, y_min REAL 2D coordinates or the upper-left bounding rectangle
x_max, y_max REAL 2D coordinates or the lower-right bounding rectangle

return values

none

code sample

x0, y0 = gh_imgui.get_item_rect_min()
x1, y1 = gh_imgui.get_item_rect_max()
gh_imgui.push_clip_rect(x0, y0, x1, y1)

push_font

Saves the current font and makes a new font the current active font for next text rendering calls.

syntax

gh_imgui.push_font (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_imgui.push_font(font_id)

push_item_width

Sets the width of next items.
This width is valid until a call to pop_item_width().

syntax

gh_imgui.push_item_width (
width
)

parameters

width REAL width in pixels of next items

return values

none

code sample

local width = gh_imgui.get_content_region_available_width()

gh_imgui.push_item_width(width * 0.8)
...
gh_imgui.pop_item_width()

push_style_color

Sets a new color to a particular color element.

syntax

gh_imgui.push_style_color (
item_type,
r, g, b, a
)

parameters

item_type ENUM( imgui_ColoredItems ) type of the widget (see complete list in set_color() function)
r, g, b, a REAL new color

return values

none

code sample

element_type = IMGUI_WINDOW_BG_COLOR

gh_imgui.push_style_color(element_type, r, g, b, a)

radio_button

Display a radio button.

syntax

gh_imgui.radio_button (
name,
active
)

parameters

name STRING name
active BOOLEAN active state: 1 (true) or 0 (false)

return values

none

code sample

gh_imgui.radio_button("radio button 1", 0)
gh_imgui.radio_button("radio button 2", 1)
gh_imgui.radio_button("radio button 3", 0)

rebuild_all_fonts

Rebuild all fonts.
Call this function once you have loaded some fonts with add_font_xxx().

syntax

gh_imgui.rebuild_all_fonts()

parameters

none

return values

none

code sample

gh_imgui.rebuild_all_fonts()

reset_default_font

Resets the default font used by ImGui.

syntax

gh_imgui.reset_default_font()

parameters

none

return values

none

code sample

gh_imgui.reset_default_font()

same_line

Allows to group items horizontally.

syntax

gh_imgui.same_line (
local_pos_x,
spacing_w
)

parameters

local_pos_x REAL default value: 0.0
spacing_w REAL default value: -1.0

return values

none

code sample

gh_imgui.same_line(local_pos_x, spacing_w)

select_draw_list

Select the draw list that will receive all draw commands.
Default is DRAWLIST_WINDOW.

syntax

gh_imgui.select_draw_list (
draw_list
)

parameters

draw_list ENUM( imgui_DrawList ) draw list type

return values

none

code sample

IMGUI_DRAWLIST_WINDOW = 0
IMGUI_DRAWLIST_BACKGROUND = 1
IMGUI_DRAWLIST_FOREGROUND = 2

draw_list = IMGUI_DRAWLIST_WINDOW

gh_imgui.select_draw_list(draw_list)

selectable

Allows to select texts in list / widgets.

syntax

ret = gh_imgui.selectable (
text,
selected,
flags
)

parameters

text STRING label
selected BOOLEAN selected state: 1 (yes) or 0 (no)
flags ENUM( imgui_SelectableFlags ) ImGuiSelectableFlags_xxx options

return values

ret INTEGER state

code sample

-- Possible flags
ImGuiSelectableFlags_None = 0
ImGuiSelectableFlags_DontClosePopups = 1 -- // Clicking this don't close parent popup window
ImGuiSelectableFlags_SpanAllColumns = 2 -- Selectable frame can span all columns (text will still fit in current column)
ImGuiSelectableFlags_AllowDoubleClick = 4 -- Generate press events on double clicks too
ImGuiSelectableFlags_Disabled = 8 -- Cannot be selected, display greyed out text

selected = 0
flags = ImGuiSelectableFlags_SpanAllColumns

ret = gh_imgui.selectable(text, selected, flags)

separator

Adds an horizontal line (separator).

syntax

gh_imgui.separator()

parameters

none

return values

none

code sample

gh_imgui.separator()

set_color

Sets the color of the next widget.

syntax

gh_imgui.set_color (
item_type,
r, g, b, a
)

parameters

item_type ENUM( imgui_ColoredItems ) type of the widget (see values in the code sample)
r, g, b, a REAL RGBA color of the widget

return values

none

code sample

IMGUI_WINDOW_BG_COLOR = 1
IMGUI_TITLE_BG_COLOR = 2
IMGUI_PLOTLINES_COLOR = 3
IMGUI_FRAME_BG_COLOR = 4
IMGUI_TITLE_BG_ACTIVE_COLOR = 5
IMGUI_TITLE_BG_COLLAPSED_COLOR = 6
IMGUI_PLOTHISTOGRAM_COLOR = 7
IMGUI_COMBO_BG_COLOR = 8
IMGUI_BUTTON_COLOR = 9
IMGUI_SEPARATOR_COLOR = 10
IMGUI_RESIZE_GRIP_COLOR = 11
IMGUI_PLOTLINE_HOVERED_COLOR = 12
IMGUI_PLOTHISTOGRAM_HOVERED_COLOR = 13
IMGUI_BUTTON_HOVERED_COLOR = 14
IMGUI_SEPARATOR_HOVERED_COLOR = 15
IMGUI_RESIZE_GRIP_HOVERED_COLOR = 16
IMGUI_HEADER_COLOR = 17
IMGUI_HEADER_HOVERED_COLOR = 18
IMGUI_SLIDER_GRAB_COLOR = 19
IMGUI_CHECK_MARK_COLOR = 20
IMGUI_SCROLLBAR_BG_COLOR = 21
IMGUI_SCROLLBAR_GRAB_COLOR = 22
IMGUI_SCROLLBAR_GRAB_HOVERED_COLOR = 23
IMGUI_TEXT_COLOR = 24
IMGUI_POPUP_BG_COLOR = 25
IMGUI_TEXT_DISABLED_COLOR = 26
IMGUI_CHILD_BG_COLOR = 27
IMGUI_BORDER_COLOR = 28
IMGUI_BORDER_SHADOW_COLOR = 29
IMGUI_FRAME_BG_HOVERED_COLOR = 30
IMGUI_FRAME_BG_ACTIVE_COLOR = 31
IMGUI_MENU_BAR_BG_COLOR = 32
IMGUI_SCROLLBAR_GRAB_ACTIVE_COLOR = 33
IMGUI_SLIDER_GRAB_ACTIVE_COLOR = 34
IMGUI_BUTTON_ACTIVE_COLOR = 35
IMGUI_HEADER_ACTIVE_COLOR = 36
IMGUI_SEPARATOR_ACTIVE_COLOR = 37
IMGUI_RESIZE_GRIP_ACTIVE_COLOR = 38
IMGUI_CLOSE_BUTTON_COLOR = 39
IMGUI_CLOSE_BUTTON_HOVERED_COLOR = 40
IMGUI_CLOSE_BUTTON_ACTIVE_COLOR = 41
IMGUI_PLOTLINES_HOVERED_COLOR = 42
IMGUI_TEXT_SELECTED_BG_COLOR = 43
IMGUI_MODAL_WINDOW_DARKENING_COLOR = 44
IMGUI_DRAG_DROP_TARGET_COLOR = 45
IMGUI_NAV_HIGHLIGHT_COLOR = 46
IMGUI_NAV_WINDOW_IN_HIGHLIGHT_COLOR = 47
IMGUI_MODAL_WINDOW_DIM_BG_COLOR = 48
IMGUI_TAB_COLOR = 49
IMGUI_TAB_HOVERED_COLOR = 50
IMGUI_TAB_ACTIVE_COLOR = 51
IMGUI_TAB_UNFOCUSED_COLOR = 52
IMGUI_TAB_UNFOCUSED_ACTIVE_COLOR = 53

widget_type = IMGUI_BUTTON_COLOR

gh_imgui.set_color(widget_type, r, g, b, a)

set_cur_font_display_offset

Sets the x and y offset of the current font.
Useful to adjust the vertical alignment of a text.

syntax

gh_imgui.set_cur_font_display_offset (
x, y
)

parameters

x, y REAL offsets

return values

none

code sample

gh_imgui.set_cur_font_display_offset(x, y)

set_default_font

Sets the default font.

syntax

gh_imgui.set_default_font (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_imgui.set_default_font(font_id)

set_font_glyph_offset

Allows to set an offset to each glyph of the font (default offset is 0,0).
This can be useful with narrow buttons for example.
set_font_glyph_offset() must be call before rebuild_all_fonts().

syntax

gh_imgui.set_font_glyph_offset (
font_id,
x, y
)

parameters

font_id ID font identifier
x, y INTEGER font offset

return values

none

code sample

gh_imgui.set_font_glyph_offset(font_id, 0, -2)
gh_imgui.rebuild_all_fonts()

set_frame_border_size

Sets the size of the frame border.

syntax

gh_imgui.set_frame_border_size (
x
)

parameters

x REAL size

return values

none

code sample

gh_imgui.set_frame_border_size(x)

set_indent_spacing

Sets the indent size.

syntax

gh_imgui.set_indent_spacing (
spacing
)

parameters

spacing REAL indent spacing

return values

none

code sample

gh_imgui.set_indent_spacing(spacing)

set_item_default_focus

Makes last item the default focused item of a window.

syntax

gh_imgui.set_item_default_focus()

parameters

none

return values

none

code sample

gh_imgui.set_item_default_focus()

set_item_spacing

Sets the spacing between items.

syntax

gh_imgui.set_item_spacing (
x, y
)

parameters

x, y REAL spacing

return values

none

code sample

gh_imgui.set_item_spacing(x, y)

set_keyboard_focus_here

Focuses keyboard on the next widget.
Use positive offset to access sub components of a multiple component widget.
Use -1 to access previous widget.

syntax

gh_imgui.set_keyboard_focus_here (
offset
)

parameters

offset INTEGER offset

return values

none

code sample

gh_imgui.set_keyboard_focus_here(offset)

set_next_item_width

Sets the size of the next item.

syntax

gh_imgui.set_next_item_width (
width
)

parameters

width REAL item width

return values

none

code sample

gh_imgui.set_next_item_width(width)

set_next_window_content_size

Sets the size of the window content.

syntax

gh_imgui.set_next_window_content_size (
width, height
)

parameters

width, height REAL size

return values

none

code sample

gh_imgui.set_next_window_content_size(width, height)

set_next_window_size

Sets the size of the next window.

syntax

gh_imgui.set_next_window_size (
width, height
)

parameters

width, height INTEGER size of the window

return values

none

code sample

gh_imgui.set_next_window_size(width, height)

set_next_window_size_constraints

Sets the size limits of the next window.

syntax

gh_imgui.set_next_window_size_constraints (
min_x, min_y,
max_x, max_y
)

parameters

min_x, min_y INTEGER bottom left corner
max_x, max_y INTEGER top right corner

return values

none

code sample

gh_imgui.set_next_window_size_constraints(min_x, min_y, max_x, max_y)

set_rounding

Sets the rounding of a particular element.
A value of 0 means a squared corner.

syntax

gh_imgui.set_rounding (
what,
x
)

parameters

what STRING name of the element: window, child, popup, frame, scrollbar, grab, tab
x REAL size

return values

none

code sample

gh_imgui.set_rounding("frame", x)

set_scroll

Sets the scrolling amount in X and Y [0..get_scroll_max()].

syntax

gh_imgui.set_scroll (
scroll_x, scroll_y
)

parameters

scroll_x, scroll_y REAL scrolling values in X and Y

return values

none

code sample

gh_imgui.set_scroll(scroll_x, scroll_y)

set_scroll_from_pos_y

Adjusts scrolling amount to make given position visible.
Generally get_cursor_start_pos() + offset to compute a valid position.

syntax

gh_imgui.set_scroll_from_pos_y (
local_y,
center_y_ratio
)

parameters

local_y REAL local y
center_y_ratio REAL y ratio

return values

none

code sample

gh_imgui.set_scroll_from_pos_y(local_y, center_y_ratio)

set_scroll_here_y

Adjusts scrolling amount to make current cursor position visible.
center_y_ratio=0.0: top, 0.5: center, 1.0: bottom.
When using to make a default/current item visible, consider using set_item_default_focus() instead.

syntax

gh_imgui.set_scroll_here_y (
center_y_ratio
)

parameters

center_y_ratio REAL y ratio

return values

none

code sample

gh_imgui.set_scroll_here_y(center_y_ratio)

set_style_colors

Sets a built-in color style.

syntax

gh_imgui.set_style_colors (
style
)

parameters

style ENUM( imgui_Style ) name of the style

return values

none

code sample

-- Available sytles:
"classic"
"dark"
"light"
"krosoft"
"maya"
"rayteak"
"fromhue"
"cherry"
"dark2"
"corporate_grey"

style_name = "classic"
gh_imgui.set_style_colors(style_name)

set_tooltip

Sets a tooltip.

syntax

gh_imgui.set_tooltip (
caption
)

parameters

caption STRING tooltip text

return values

none

code sample

gh_imgui.set_tooltip("This is a tooltip!")

set_window_border_size

Sets the size of the window border.

syntax

gh_imgui.set_window_border_size (
x
)

parameters

x REAL size

return values

none

code sample

gh_imgui.set_window_border_size(x)

set_window_focus

Sets named window to be focused (front-most).

syntax

gh_imgui.set_window_focus (
name
)

parameters

name STRING name of the window

return values

none

code sample

gh_imgui.set_window_focus(name)

set_window_rounding

Sets the window corner rounding.

syntax

gh_imgui.set_window_rounding (
x
)

parameters

x REAL size

return values

none

code sample

gh_imgui.set_window_rounding(x)

set_window_size

Sets the size of a window.

syntax

gh_imgui.set_window_size (
name,
width, height
)

parameters

name STRING window name
width, height INTEGER size of the window

return values

none

code sample

gh_imgui.set_window_size("Control Panel", width, height)

show_demo_window

Renders the ImGui demo window.

syntax

gh_imgui.show_demo_window()

parameters

none

return values

none

code sample

gh_imgui.show_demo_window()

show_metrics_window

Display an ImGui built-in window that shows statistics about all windows.
Call this function between frame_begin() and frame_end().

syntax

gh_imgui.show_metrics_window()

parameters

none

return values

none

code sample

gh_imgui.show_metrics_window()

show_stack_tool_window

Display an ImGui built-in window that shows items unique IDs.
Call this function between frame_begin() and frame_end().

syntax

gh_imgui.show_stack_tool_window()

parameters

none

return values

none

code sample

gh_imgui.show_stack_tool_window()

show_test_window

Shows ImGui test window.

syntax

gh_imgui.show_test_window()

parameters

none

return values

none

code sample

gh_imgui.frame_begin(winW, winH, mouse_x, mouse_y, mouse_left_button, mouse_right_button)

gh_imgui.show_test_window()

gh_imgui.frame_end()

slider_1f

Displays a 1D slider.

syntax

value = gh_imgui.slider_1f (
label,
initial_value,
v_min, v_max,
power
)

parameters

label STRING name of the slider
initial_value REAL initial value
v_min, v_max REAL min / max value of the slider
power REAL use power != 1.0 for logarithmic sliders

return values

value REAL current value

code sample

v = gh_imgui.slider_1f("slider01", initial_value, v_min, v_max, 1.0)

slider_1i

Displays a 1D slider with integer values.

syntax

value = gh_imgui.slider_1i (
label,
initial_value,
v_min, v_max
)

parameters

label STRING name of the slider
initial_value INTEGER initial value
v_min, v_max INTEGER min / max value of the slider

return values

value INTEGER current value

code sample

v = gh_imgui.slider_1i("slider01", initial_value, v_min, v_max)

slider_1i_v2

Displays a 1D slider with integer values.

syntax

value = gh_imgui.slider_1i_v2 (
label,
initial_value,
v_min, v_max,
flags
)

parameters

label STRING name of the slider
initial_value INTEGER initial value
v_min, v_max INTEGER min / max value of the slider
flags INTEGER ImGuiSliderFlags_xxxx flags

return values

value INTEGER current value

code sample

ImGuiSliderFlags_None                   = 0
ImGuiSliderFlags_ClampOnInput           = 16
ImGuiSliderFlags_Logarithmic            = 32
ImGuiSliderFlags_NoRoundToFormat        = 64
ImGuiSliderFlags_NoInput                = 12
v = gh_imgui.slider_1i_v2("slider01", initial_value, v_min, v_max, ImGuiSliderFlags_None)

slider_2f

Displays a 2D slider.

syntax

x, y = gh_imgui.slider_2f (
label,
x0, y0,
v_min, v_max,
power
)

parameters

label STRING name of the slider
x0, y0 REAL initial 2D value
v_min, v_max REAL min / max value of the slider
power REAL use power != 1.0 for logarithmic sliders

return values

x, y REAL current 2D value

code sample

x, y = gh_imgui.slider_2f("slider04", x0, y0, v_min, v_max, 1.0)

slider_3f

Displays a 3D slider.

syntax

x, y, z = gh_imgui.slider_3f (
label,
x0, y0, z0,
v_min, v_max,
power
)

parameters

label STRING name of the slider
x0, y0, z0 REAL initial 3D value
v_min, v_max REAL min / max value of the slider
power REAL use power != 1.0 for logarithmic sliders

return values

x, y, z REAL current 3D value

code sample

x, y, z = gh_imgui.slider_3f("slider03", x0, y0, z0, v_min, v_max, 1.0)

slider_4f

Displays a 4D slider.

syntax

x, y, z, w = gh_imgui.slider_4f (
label,
x0, y0, z0, w0,
v_min, v_max,
power
)

parameters

label STRING name of the slider
x0, y0, z0, w0 REAL initial 4D value
v_min, v_max REAL min / max value of the slider
power REAL use power != 1.0 for logarithmic sliders

return values

x, y, z, w REAL current 4D value

code sample

x, y, z, w = gh_imgui.slider_4f("slider02", x0, y0, z0, w0, v_min, v_max, 1.0)

spacing

Adds a vertical space.

syntax

gh_imgui.spacing()

parameters

none

return values

none

code sample

gh_imgui.spacing()

tab_bar_begin

Begins a tab bar.

syntax

is_opened = gh_imgui.tab_bar_begin (
label
)

parameters

label STRING label

return values

is_opened BOOLEAN 1 (true) or 0 (false)

code sample

ret = gh_imgui.tab_bar_begin("tabbar01")

tab_bar_begin_v2

Begins a tab bar.

syntax

is_opened = gh_imgui.tab_bar_begin_v2 (
label,
flags
)

parameters

label STRING label
flags ENUM( imgui_TabBarFlags ) ImGuiTabBarFlags_xxx options

return values

is_opened BOOLEAN 1 (true) or 0 (false)

code sample

ImGuiTabBarFlags_None = 0,
ImGuiTabBarFlags_Reorderable = 1
ImGuiTabBarFlags_AutoSelectNewTabs = 2
ImGuiTabBarFlags_NoCloseWithMiddleMouseButton = 4
ImGuiTabBarFlags_NoTabListPopupButton = 8
ImGuiTabBarFlags_NoTabListScrollingButtons = 16
ImGuiTabBarFlags_NoTooltip = 32
ImGuiTabBarFlags_FittingPolicyResizeDown = 64
ImGuiTabBarFlags_FittingPolicyScroll = 128

ret = gh_imgui.tab_bar_begin_v2("tabbar01", ImGuiTabBarFlags_Reorderable)

tab_bar_end

Ends a tab bar.

syntax

gh_imgui.tab_bar_end()

parameters

none

return values

none

code sample

ImGuiTabBarFlags_Reorderable = 1

if (gh_imgui.tab_bar_begin_v2("tabbar01", ImGuiTabBarFlags_Reorderable) == 1) then
    ...
    gh_imgui.tab_bar_end()
end

tab_item_begin

Begins a tab bar item.

syntax

is_opened = gh_imgui.tab_item_begin (
label,
show_tab,
flags
)

parameters

label STRING label
show_tab BOOLEAN 1 (show) or 0 (hide)
flags ENUM( imgui_TabItemFlags ) ImGuiTabItemFlags_xxx options

return values

is_opened BOOLEAN 1 (true) or 0 (false)

code sample

flags = ImGuiTabItemFlags_None -- 0
show_tab = 1
if (gh_imgui.tab_bar_begin("tabbar01", show_tab, flags) == 1) then
    flags = 0

    if (gh_imgui.tab_item_begin("TAB1", 1, flags) == 1) then
        gh_imgui.text("This is the TAB1")
        gh_imgui.tab_item_end()
    end

    if (gh_imgui.tab_item_begin("TAB2", 0, flags) == 1) then
        gh_imgui.text("This is the TAB2")
        gh_imgui.tab_item_end()
    end

    gh_imgui.tab_bar_end()
end

tab_item_begin_v2

Begins a tab bar item.

syntax

is_opened = gh_imgui.tab_item_begin_v2 (
label,
flags
)

parameters

label STRING label
flags ENUM( imgui_TabItemFlags ) ImGuiTabItemFlags_xxx options

return values

is_opened BOOLEAN 1 (true) or 0 (false)

code sample

if (gh_imgui.tab_bar_begin_v2("tabbar01", flags) == 1) then
    flags = 0

    if (gh_imgui.tab_item_begin("TAB1", 1, flags) == 1) then
        gh_imgui.text("This is the TAB1")
        gh_imgui.tab_item_end()
    end

    if (gh_imgui.tab_item_begin("TAB2", 1, flags) == 1) then
        gh_imgui.text("This is the TAB2")
        gh_imgui.tab_item_end()
    end

    gh_imgui.tab_bar_end()
end

tab_item_end

Ends a tab bar item.

syntax

gh_imgui.tab_item_end()

parameters

none

return values

none

code sample

flags = 0

if (gh_imgui.tab_bar_begin_v2("tabbar01", flags) == 1) then
    flags = 0

    if (gh_imgui.tab_item_begin("TAB1", 1, flags) == 1) then
        gh_imgui.text("This is the TAB1")
        gh_imgui.tab_item_end()
    end

    if (gh_imgui.tab_item_begin("TAB2", 1, flags) == 1) then
        gh_imgui.text("This is the TAB2")
        gh_imgui.tab_item_end()
    end

    gh_imgui.tab_bar_end()
end

table_begin

Begins a table.

syntax

ret = gh_imgui.table_begin (
label,
num_columns,
flags,
outer_size_x, outer_size_y,
inner_width
)

parameters

label STRING label
num_columns INTEGER number of columns
flags INTEGER options. See all ImGuiTableFlags_xxxx constants in imgui.lua
outer_size_x, outer_size_y REAL outer size
inner_width REAL inner width

return values

ret INTEGER 1 if success or 0 if error

code sample

flags = ImGuiTableFlags_Resizable + ImGuiTableFlags_Borders
num_columns = 2
if (gh_imgui.table_begin("Table1", num_columns, flags, 0,0, 0) == 1) then
	...
	...
  gh_imgui.table_end()
end

table_end

Ends a table.
Must be called only if table_begin() returns 1.

syntax

gh_imgui.table_end()

parameters

none

return values

none

code sample

flags = ImGuiTableFlags_Resizable + ImGuiTableFlags_Borders
num_columns = 2
if (gh_imgui.table_begin("Table1", num_columns, flags, 0,0, 0) == 1) then
	...
	...
  gh_imgui.table_end()
end

table_get_column_count

Returns the number of columns (value passed to BeginTable).

syntax

count = gh_imgui.table_get_column_count()

parameters

none

return values

count INTEGER 

code sample

count = gh_imgui.table_get_column_count()

table_get_column_flags

Returns column flags so you can query their Enabled/Visible/Sorted/Hovered status flags.
Pass -1 to use current column.

syntax

flags = gh_imgui.table_get_column_flags (
column_n
)

parameters

column_n INTEGER column index

return values

flags INTEGER See the ImGuiTableColumnFlags_xxxxx constants in imgui.lua

code sample

flags = gh_imgui.table_get_column_flags(column_n)

table_get_column_index

Returns the current column index.

syntax

index = gh_imgui.table_get_column_index()

parameters

none

return values

index INTEGER 

code sample

index = gh_imgui.table_get_column_index()

table_get_column_name

Returns empty string if column didn't have a name declared by table_setup_column().
Pass -1 to use current column.

syntax

name = gh_imgui.table_get_column_name (
column_n
)

parameters

column_n INTEGER column index

return values

name STRING 

code sample

name = gh_imgui.table_get_column_name(column_n)

table_get_row_index

Returns the current row index.

syntax

index = gh_imgui.table_get_row_index()

parameters

none

return values

index INTEGER 

code sample

index = gh_imgui.table_get_row_index()

table_header

Submits one header cell manually (rarely used).

syntax

gh_imgui.table_header (
label
)

parameters

label STRING 

return values

none

code sample

gh_imgui.table_header(label)

table_headers_row

Submits all headers cells based on data provided to table_setup_column() + submit context menu.

syntax

gh_imgui.table_headers_row()

parameters

none

return values

none

code sample

gh_imgui.table_headers_row()

table_next_column

Appends into the next column (or first column of next row if currently in last column).
Returns true when column is visible.

syntax

ret = gh_imgui.table_next_column()

parameters

none

return values

ret INTEGER 1 if visible or 0 if not

code sample

ret = gh_imgui.table_next_column()

table_next_row_DUP1

Appends into the first cell of a new row.

syntax

gh_imgui.table_next_row_DUP1 (
row_flags,
min_row_height
)

parameters

row_flags INTEGER See ImGuiTableRowFlags_xxxx in imgui.lua
min_row_height INTEGER

return values

none

code sample

gh_imgui.table_next_row(row_flags, min_row_height)

table_next_row_DUP2

Appends into the first cell of a new row.

syntax

gh_imgui.table_next_row_DUP2 (
row_flags,
min_row_height
)

parameters

row_flags INTEGER See ImGuiTableRowFlags_xxxx in imgui.lua
min_row_height INTEGER

return values

none

code sample

gh_imgui.table_next_row(row_flags, min_row_height)

table_set_bg_color

Changes the color of a cell, row, or column.
See ImGuiTableBgTarget_ flags in imgui.lua for details.

syntax

gh_imgui.table_set_bg_color (
target,
r, g, b, a,
column_n
)

parameters

target INTEGER 
r, g, b, a REAL RGBA color
column_n INTEGER column index

return values

none

code sample

gh_imgui.table_set_bg_color(target, r, g, b, a, column_n)

table_set_column_enabled

syntax

gh_imgui.table_set_column_enabled (
column_n,
state
)

parameters

column_n INTEGER 
state BOOLEAN 0 or 1

return values

none

code sample

gh_imgui.table_set_column_enabled(column_n, state)

table_set_column_index

Appends into the specified column.
Returns true when column is visible.

syntax

ret = gh_imgui.table_set_column_index (
column_n
)

parameters

column_n INTEGER column index

return values

ret INTEGER 1 if success or 0 if error

code sample

ret = gh_imgui.table_set_column_index(column_n)

table_setup_column

Allows to to specify label, resizing policy, default width/weight, id, various other flags etc.

syntax

gh_imgui.table_setup_column (
label,
flags,
init_width_or_weight,
user_id
)

parameters

label STRING 
flags INTEGER
init_width_or_weight REAL
user_id INTEGER

return values

none

code sample

gh_imgui.table_setup_column(label, flags, init_width_or_weight, user_id)

table_setup_scroll_freeze

Locks columns/rows so they stay visible when scrolled.

syntax

gh_imgui.table_setup_scroll_freeze (
cols,
rows
)

parameters

cols INTEGER 
rows INTEGER

return values

none

code sample

gh_imgui.table_setup_scroll_freeze(cols, rows)

terminate

Terminates the ImGui library.
Must be called once in the TERMINATE script.

syntax

gh_imgui.terminate()

parameters

none

return values

none

code sample

gh_imgui.terminate()

text

Displays a simple text.

syntax

gh_imgui.text (
text
)

parameters

text STRING text to display

return values

none

code sample

gh_imgui.text("GeeXLab is powerful!")

text_rgba

Displays a colored text.

syntax

gh_imgui.text_rgba (
text,
r, g, b, a
)

parameters

text STRING text to display
r, g, b, a REAL color of the text

return values

none

code sample

gh_imgui.text_rgba("GeeXLab is powerful!", 1.0, 1.0, 0.0, 1.0)

text_unformatted_v1

Displays a raw text without formatting.
Recommended for long chunks of text.

syntax

gh_imgui.text_unformatted_v1 (
text
)

parameters

text STRING text to display

return values

none

code sample

gh_imgui.text_unformatted_v1("GeeXLab is powerful!")

text_unformatted_v2

Displays a raw text without formatting.
Recommended for long chunks of text.

syntax

gh_imgui.text_unformatted_v2 (
text,
text_end
)

parameters

text STRING text to display
text_end STRING XX euh...

return values

none

code sample

gh_imgui.text_unformatted_v2("GeeXLab is powerful!")

text_wrapped

Displays a wrapped text.

syntax

gh_imgui.text_wrapped (
text
)

parameters

text STRING text to display

return values

none

code sample

gh_imgui.text_wrapped("GeeXLab is powerful!")

toggle

Displays a knob

syntax

out_value = gh_imgui.toggle (
label,
in_value,
size_x, size_y,
flags,
animation_duration,
frame_rounding,
knob_rounding
)

parameters

label STRING label
in_value BOOLEAN initial value
size_x, size_y REAL size in pixels of the toggle
flags INTEGER flags
animation_duration REAL animation duration
frame_rounding REAL frame rounding - from 0.0 to 1.0
knob_rounding REAL knob rounding - from 0.0 to 1.0

return values

out_value REAL value of the toggle: 0 or 1

code sample

ImGuiToggleFlags_None                   = 0
ImGuiToggleFlags_Animated               = 1  
ImGuiToggleFlags_BorderedFrame          = 8  
ImGuiToggleFlags_BorderedKnob           = 16 
ImGuiToggleFlags_ShadowedFrame          = 32 
ImGuiToggleFlags_ShadowedKnob           = 64 
ImGuiToggleFlags_A11y                   = 256

size_x = 40
size_y = 20
flags = ImGuiToggleFlags_Animated
animation_duration = 0.1
frame_rounding = 1.0
knob_rounding = 1.0
label = "Horizontal drag"
out_value = gh_imgui.toggle(label, in_value, size_x, size_y, flags, animation_duration, frame_rounding, knob_rounding)

tree_node

Starts a tree.

syntax

state = gh_imgui.tree_node (
label
)

parameters

label STRING label

return values

state BOOLEAN tree opened: 1 (true) or 0 (false)

code sample

node_open = gh_imgui.tree_node("Root")
if (node_open == 1) then
    gh_imgui.tree_node_leaf("Child 1")
    if (gh_imgui.is_item_clicked(mouse_button_left) == 1) then
        tree_selected_node_name = "Child 1"
    end
    gh_imgui.tree_pop()
end

tree_node_ex

Starts a tree.

syntax

state = gh_imgui.tree_node_ex (
label,
flags
)

parameters

label STRING label
flags ENUM( imgui_TreeNodeFlags ) ImGuiTreeNodeFlags_xxx options

return values

state BOOLEAN tree opened: 1 (true) or 0 (false)

code sample

flags = ImGuiTreeNodeFlags_Selected
node_open = gh_imgui.tree_node_ex("Root", flags)
if (node_open == 1) then
    gh_imgui.tree_node_leaf("Child 1")
    if (gh_imgui.is_item_clicked(mouse_button_left) == 1) then
        tree_selected_node_name = "Child 1"
    end
    gh_imgui.tree_pop()
end

tree_node_leaf

Display a tree leaf.

syntax

gh_imgui.tree_node_leaf (
label
)

parameters

label STRING label

return values

none

code sample

node_open = gh_imgui.tree_node("Root")

if (node_open == 1) then
    gh_imgui.tree_node_leaf("Child 1")

    if (gh_imgui.is_item_clicked(mouse_button_left) == 1) then
        tree_selected_node_name = "Child 1"
    end

    gh_imgui.tree_pop()
end

tree_node_leaf_v2

Display a tree leaf.

syntax

gh_imgui.tree_node_leaf_v2 (
label,
flags
)

parameters

label STRING label
flags ENUM( imgui_TreeNodeFlags ) tree options - see ImGuiTreeNodeFlags_xxx constants in libs/lua/imgui.lua

return values

none

code sample

node_open = gh_imgui.tree_node("Root")

if (node_open == 1) then
    local ImGuiTreeNodeFlags_Bullet = 512

    gh_imgui.tree_node_leaf_v2("Child 1", ImGuiTreeNodeFlags_Bullet)

    if (gh_imgui.is_item_clicked(mouse_button_left) == 1) then
        tree_selected_node_name = "Child 1"
    end

    gh_imgui.tree_pop()
end

tree_pop

Ends a tree.

syntax

gh_imgui.tree_pop()

parameters

none

return values

none

code sample

node_open = gh_imgui.tree_node("Root")

if (node_open == 1) then
    gh_imgui.tree_node_leaf("Child 1")

    if (gh_imgui.is_item_clicked(mouse_button_left) == 1) then
        tree_selected_node_name = "Child 1"
    end

    gh_imgui.tree_pop()
end

underline

Draw a colored line under the current item.

syntax

gh_imgui.underline (
r, g, b, a
)

parameters

r, g, b, a REAL color

return values

none

code sample

gh_imgui.underline(r, g, b, a)

unindent

Sets unindent spacing.

syntax

gh_imgui.unindent (
indent_w
)

parameters

indent_w REAL size

return values

none

code sample

gh_imgui.unindent(indent_w)

url

Draw a clickable url.

syntax

clicked = gh_imgui.url (
link_caption,
link_url,
tooltip_text
)

parameters

link_caption STRING caption
link_url STRING url (https://....) - Link can be empty to work like a button
tooltip_text STRING tool tip (can be empty)

return values

clicked INTEGER 1 if clicked, 0 otherwise.

code sample

clicked = gh_imgui.url(link_caption, link_url, tooltip_text)

vslider_1f

Displays a 1D vertical slider.

syntax

value = gh_imgui.vslider_1f (
label,
width, height,
initial_value,
v_min, v_max,
power
)

parameters

label STRING name of the slider
width, height REAL size of the slider
initial_value REAL initial value
v_min, v_max REAL min / max value of the slider
power REAL use power != 1.0 for logarithmic sliders

return values

value REAL current value

code sample

v = gh_imgui.vslider_1f("vslider01", 20, 100, initial_value, v_min, v_max, 1.0)

vslider_1i

Displays a 1D vertical slider with integer values.

syntax

value = gh_imgui.vslider_1i (
label,
width, height,
initial_value,
v_min, v_max
)

parameters

label STRING name of the slider
width, height REAL size of the slider
initial_value INTEGER initial value
v_min, v_max INTEGER min / max value of the slider

return values

value INTEGER current value

code sample

v = gh_imgui.vslider_1i("slider01", 20, 100, initial_value, v_min, v_max)

vslider_1i_v2

Displays a 1D vertical slider with integer values.

syntax

value = gh_imgui.vslider_1i_v2 (
label,
width, height,
initial_value,
v_min, v_max,
flags
)

parameters

label STRING name of the slider
width, height REAL size of the slider
initial_value INTEGER initial value
v_min, v_max INTEGER min / max value of the slider
flags INTEGER ImGuiSliderFlags_xxxx flags

return values

value INTEGER current value

code sample

ImGuiSliderFlags_None                   = 0
ImGuiSliderFlags_ClampOnInput           = 16
ImGuiSliderFlags_Logarithmic            = 32
ImGuiSliderFlags_NoRoundToFormat        = 64
ImGuiSliderFlags_NoInput                = 128
v = gh_imgui.vslider_1i_v2("slider01", 20, 100, initial_value, v_min, v_max, ImGuiSliderFlags_None)

widget

Adds a widget.

syntax

gh_imgui.widget (
widget_type
)

parameters

widget_type ENUM( imgui_Widget ) type of the widget

return values

none

code sample

IMGUI_WIDGET_SEPARATOR = 1
IMGUI_WIDGET_SAME_LINE = 2
IMGUI_WIDGET_BULLET = 3
IMGUI_WIDGET_VERTICAL_SPACING = 4
IMGUI_WIDGET_NEW_LINE = 5

gh_imgui.widget(IMGUI_WIDGET_SEPARATOR)

window_begin

Starts the rendering of a window.

syntax

is_open = gh_imgui.window_begin (
name,
width, height,
pos_x, pos_y,
win_flags,
pos_flags,
size_flags
)

parameters

name STRING name of the window
width, height REAL size of the window
pos_x, pos_y REAL position of the window
win_flags ENUM( imgui_WindowFlags ) window options: set to 0 for default options. Options can be OR-ed.
pos_flags ENUM( imgui_PosSizeFlags ) window position options: set to 4 for default options
size_flags ENUM( imgui_PosSizeFlags ) window size options: set to 4 for default options

return values

is_open BOOLEAN window: 1 (opened) or 0 (collapsed)

code sample

-- Window options
local window_default = 0
local window_no_resize = 2
local window_no_move = 4
local window_no_collapse = 32
local window_show_border = 128
local window_no_save_settings = 256

-- Position or size options
local pos_size_flag_always = 1 -- Always set the pos and/or size
local pos_size_flag_once = 2 -- Set the pos and/or size once per runtime session (only the first call with succeed)
local pos_size_flag_first_use_ever = 4 -- Set the pos and/or size if the window has no saved data (if doesn't exist in the .ini file)
local pos_size_flag_appearing = 8 -- Set the pos and/or size if the window is appearing after being hidden/inactive (or the first time)

-- window_flags = window_no_move | window_no_save_settings
window_flags = 0
pos_flags = pos_size_flag_first_use_ever
size_flags = pos_size_flag_first_use_ever

is_open = gh_imgui.window_begin("GeeXLab ImGui demo", 300, 200, 20, 20, window_flags, pos_flags, size_flags)
if (is_open == 1) then
    gh_imgui.text("GeeXLab is powerful!")
end

gh_imgui.window_end()

window_begin_v2

Starts the rendering of a window.
This window has a close button.

syntax

is_open, show_window = gh_imgui.window_begin_v2 (
name,
width, height,
pos_x, pos_y,
win_flags,
pos_flags,
size_flags,
show_window
)

parameters

name STRING name of the window
width, height REAL size of the window
pos_x, pos_y REAL position of the window
win_flags ENUM( imgui_WindowFlags ) window options: set to 0 for default options. Options can be OR-ed.
pos_flags ENUM( imgui_PosSizeFlags ) window position options: set to 4 for default options
size_flags ENUM( imgui_PosSizeFlags ) window size options: set to 4 for default options
show_window BOOLEAN initial open state of the window: 1 (show) or 0 (hide)

return values

is_open, show_window BOOLEAN is_open: 1 (window opened) or 0 (window collapsed) - show_window: 0 (the user has clicked on the close button)

code sample

-- Window options
local window_default = 0
local window_no_resize = 2
local window_no_move = 4
local window_no_collapse = 32
local window_show_border = 128
local window_no_save_settings = 256

-- Position or size options
local pos_size_flag_always = 1 -- Always set the pos and/or size
local pos_size_flag_once = 2 -- Set the pos and/or size once per runtime session (only the first call with succeed)
local pos_size_flag_first_use_ever = 4 -- Set the pos and/or size if the window has no saved data (if doesn't exist in the .ini file)
local pos_size_flag_appearing = 8 -- Set the pos and/or size if the window is appearing after being hidden/inactive (or the first time)

-- window_flags = window_no_move | window_no_save_settings
window_flags = 0
pos_flags = pos_size_flag_first_use_ever
size_flags = pos_size_flag_first_use_ever

if (show_window == 1) then
    window_flags = 0
    show = show_window

    is_open, show_window = gh_imgui.window_begin_v2("GeeXLab information", 300, 200, 20, 20, window_flags, pos_flags, size_flags, show)
    if (is_open == 1) then
        gh_imgui.text("GeeXLab is powerful!")
    end

    gh_imgui.window_end()
end

window_end

Stops the rendering of a window.

syntax

gh_imgui.window_end()

parameters

none

return values

none

code sample

window_flags = 0
gh_imgui.window_begin("GeeXLab information", 300, 200, 20, 20, window_flags)
gh_imgui.text("GeeXLab is powerful!")
gh_imgui.window_end()

gh_input

User input module

gh_input is the module that manages user's input: mouse, keyboard...

joystick_get_button_state

windows

Gets the status of a particular button of a joystick - only four buttons are supported (Windows only).

syntax

status = gh_input.joystick_get_button_state (
joy_index,
button_index
)

parameters

joy_index INTEGER joystick index - currently 0 or 1
button_index ENUM( joystick_buttons ) button index - currently 0, 1, 2 or 3

return values

status BOOLEAN button status: 1 (pressed) or 0 (released)

code sample

status = gh_input.joystick_get_button_state(joy_index, button_index)

joystick_get_num

windows

Returns the number of joysticks supported (Windows only).

syntax

num_joysticks = gh_input.joystick_get_num()

parameters

none

return values

num_joysticks INTEGER number of joysticks

code sample

num_joys = gh_input.joystick_get_num()

joystick_get_position

windows

Gets the position of a joystick along X, Y and Z axis (Windows only).

syntax

x, y, z = gh_input.joystick_get_position (
joy_index
)

parameters

joy_index INTEGER joystick index - currently 0 or 1

return values

x, y, z REAL position along X, Y and Z axis

code sample

x, y, z = gh_input.joystick_get_position(joy_index)

joystick_get_status

windows

Gets the status of a particular joystick - only two joysticks are supported (Windows only).

syntax

status = gh_input.joystick_get_status (
joy_index
)

parameters

joy_index INTEGER joystick index - currently 0 or 1

return values

status BOOLEAN joystick status: 1 (initialized) or 0 (not plugged or error)

code sample

status = gh_input.joystick_get_status(joy_index)

joystick_init_di

windows

Initializes the joystick using DirectInput (Windows only).

syntax

status = gh_input.joystick_init_di()

parameters

none

return values

status BOOLEAN button status: 1 (ok) or 0 (error)

code sample

-- INIT script			
status = gh_input.joystick_init_di()

joystick_poll_di

windows

Polls the joystick state.
(Windows only).

syntax

status = gh_input.joystick_poll_di()

parameters

none

return values

status BOOLEAN button status: 1 (ok) or 0 (error)

code sample

-- FRAME script
gh_input.joystick_poll_di()

posx, posy, posz = gh_input.joystick_get_position(0)

for i=1, 32 do
  buttons[i] = gh_input.joystick_get_button_state(0, i-1)
end

joystick_terminate_di

windows

Terminates and frees resources used by joystick (Windows only).

syntax

status = gh_input.joystick_terminate_di()

parameters

none

return values

status BOOLEAN button status: 1 (ok) or 0 (error)

code sample

-- TERMINATE script						
status = gh_input.joystick_terminate_di()

keyboard_clear_key_buffer

windows

Clears the keyboard buffer.
Call this function once per frame (Windows only).

syntax

gh_input.keyboard_clear_key_buffer()

parameters

none

return values

none

code sample

gh_input.keyboard_clear_key_buffer()

keyboard_is_key_down

Returns the pressed state of a keyboard key.

syntax

state = gh_input.keyboard_is_key_down (
key
)

parameters

key ENUM( input_kbd ) key code

return values

state BOOLEAN key state: 1 if down (pressed) or 0 if up (not pressed)

code sample

-- More key codes can be found in GeeXLab forum.
local KC_W = 17
local KC_S = 31
local KC_A = 30
local KC_D = 32
local KC_LEFT = 75
local KC_RIGHT = 77
local KC_UP = 72
local KC_DOWN = 80
local KC_SPACE = 57

local is_down = gh_input.keyboard_is_key_down(KC_SPACE)
if (is_down == 1) then
    -- pressed!
end

keyboard_update_buffer

windows

Updates the keyboard buffer.
Call this function before keyboard_is_key_down() (Windows only).

syntax

gh_input.keyboard_update_buffer()

parameters

none

return values

none

code sample

gh_input.keyboard_update_buffer()

local is_down = gh_input.keyboard_is_key_down(KC_SPACE)

mouse_get_button_state

Returns the state of a mouse button.

syntax

state = gh_input.mouse_get_button_state (
button
)

parameters

button ENUM( input_mouse ) mouse button identifier: left button (1) or right button (2)

return values

state BOOLEAN button state: 1 if down (pressed) or 0 if up (not pressed)

code sample

local LEFT_BUTTON = 1
local RIGHT_BUTTON = 2

local is_down = gh_input.mouse_get_button_state(LEFT_BUTTON)

mouse_get_position

Returns the position of the mouse cursor in screen coordinates.
The top-left position is the {0, 0} position.

syntax

x, y = gh_input.mouse_get_position()

parameters

none

return values

x, y INTEGER mouse position

code sample

mx, my = gh_input.mouse_get_position()

mouse_get_wheel_delta

Returns the delta of the mouse wheel.

syntax

delta = gh_input.mouse_get_wheel_delta()

parameters

none

return values

delta INTEGER mouse wheel delta

code sample

delta = gh_input.mouse_get_wheel_delta()

mouse_reset_wheel_delta

Reset the delta value of the mouse wheel.

syntax

gh_input.mouse_reset_wheel_delta()

parameters

none

return values

none

code sample

gh_input.mouse_reset_wheel_delta()

mouse_set_position

Sets the position of the mouse cursor.

syntax

gh_input.mouse_set_position (
x, y
)

parameters

x, y INTEGER mouse position

return values

none

code sample

gh_input.mouse_set_position(x, y)

mouse_show_cursor

windows

Shows or hide the mouse cursor (Windows only).

syntax

gh_input.mouse_show_cursor (
state
)

parameters

state BOOLEAN show (1) or hide (0)

return values

none

code sample

gh_input.mouse_show_cursor(0)

gh_leap windowsmacos

Leap Motion module

gh_leap is the module that manages the Leap Motion device.

get_device_name

Returns the name of a particular device.

syntax

dev_name = gh_leap.get_device_name (
dev_index
)

parameters

dev_index INTEGER device index

return values

dev_name STRING device name

code sample

name = gh_leap.get_device_name(0)

get_finger_bone_direction

Gets the vector direction of a bone of a particular finger.

syntax

dir_x, dir_y, dir_z = gh_leap.get_finger_bone_direction (
hand_index,
fing_index,
bone_index
)

parameters

hand_index INTEGER hand index
fing_index INTEGER finger index
bone_index INTEGER bone index

return values

dir_x, dir_y, dir_z REAL direction vector

code sample

dir_x, dir_y, dir_z = gh_leap.get_finger_bone_direction(hand_index, finger_index, bone_index)

get_finger_bone_position

Gets the position of a bone of a particular finger.

syntax

end_x, end_y, end_z, start_x, start_y, start_z = gh_leap.get_finger_bone_position (
hand_index,
fing_index,
bone_index
)

parameters

hand_index INTEGER hand index
fing_index INTEGER finger index
bone_index INTEGER bone index

return values

end_x, end_y, end_z REAL end position of the bone
start_x, start_y, start_z REAL start position of the bone

code sample

start_x, start_y, start_z, end_x, end_y, end_z = gh_leap.get_finger_bone_position(hand_index, finger_index, bone_index)

get_hand_palm_angles

Gets the plam euler angles for a particular hand.

syntax

pitch, yaw, roll = gh_leap.get_hand_palm_angles (
hand_index
)

parameters

hand_index INTEGER hand index

return values

pitch, yaw, roll REAL Euler's angles

code sample

pitch, yaw, roll = gh_leap.get_hand_palm_angles(hand)

get_hand_palm_normal

Gets the plam normal vector for a particular hand.

syntax

x, y, z = gh_leap.get_hand_palm_normal (
hand_index
)

parameters

hand_index INTEGER hand index

return values

x, y, z REAL normal vector

code sample

x,y,z = gh_leap.get_hand_palm_normal(hand)

get_hand_palm_position

Gets the plam position for a particular hand.

syntax

x, y, z = gh_leap.get_hand_palm_position (
hand_index
)

parameters

hand_index INTEGER hand index

return values

x, y, z REAL position

code sample

x,y,z = gh_leap.get_hand_palm_position(hand)

get_num_devices

Returns the number of devices.

syntax

num_devices = gh_leap.get_num_devices()

parameters

none

return values

num_devices INTEGER number of devices

code sample

n = gh_leap.get_num_devices()

get_num_fingers

Returns the numbers of fingers for a particular hand.

syntax

num_fingers = gh_leap.get_num_fingers (
hand_index
)

parameters

hand_index INTEGER hand index

return values

num_fingers INTEGER number of fingers

code sample

fingers = gh_leap.get_num_fingers(hand)

get_num_hands

Returns the numbers of hands.

syntax

num_hands = gh_leap.get_num_hands()

parameters

none

return values

num_hands INTEGER number of hands

code sample

hands = gh_leap.get_num_hands()

is_connected

Checks if a LeapMotion device is connected.

syntax

ret = gh_leap.is_connected()

parameters

none

return values

ret BOOLEAN connected: 1 (true) or 0 (false)

code sample

state = gh_leap.is_connected()

update

Updates the Leap Motion engine.
Call it once per frame.

syntax

gh_leap.update()

parameters

none

return values

none

code sample

gh_leap.update()

gh_logiled

Logitech LED module

gh_logiled is the module that allows to control RGB LED lighting of some Logitech products (gaming keyboard for example).

set_flash_lighting

Sets a flash lighting effect.

syntax

gh_logiled.set_flash_lighting (
r,
g,
b,
duration_ms,
interval_ms
)

parameters

r INTEGER red channel (0 to 100)
g INTEGER green channel (0 to 100)
b INTEGER blue channel (0 to 100)
duration_ms INTEGER duration of the effect in milliseconds
interval_ms INTEGER interval in milliseconds

return values

none

code sample

gh_logiled.set_flash_lighting(255, 255, 0,  3.0, 2.0)

set_key_lighting

Sets the color of a particular key.

syntax

gh_logiled.set_key_lighting (
keycode,
r, g, b
)

parameters

keycode ENUM( logiled_kbd ) code of the key (see code sample)
r, g, b INTEGER red, green, blue color channels (0 to 100)

return values

none

code sample

LOGILED_ESC                     = 0x01
LOGILED_F1                      = 0x3b
LOGILED_F2                      = 0x3c
LOGILED_F3                      = 0x3d
LOGILED_F4                      = 0x3e
LOGILED_F5                      = 0x3f
LOGILED_F6                      = 0x40
LOGILED_F7                      = 0x41
LOGILED_F8                      = 0x42
LOGILED_F9                      = 0x43
LOGILED_F10                     = 0x44
LOGILED_F11                     = 0x57
LOGILED_F12                     = 0x58
LOGILED_PRINT_SCREEN            = 0x137
LOGILED_SCROLL_LOCK             = 0x46
LOGILED_PAUSE_BREAK             = 0x145
LOGILED_TILDE                   = 0x29
LOGILED_ONE                     = 0x02
LOGILED_TWO                     = 0x03
LOGILED_THREE                   = 0x04
LOGILED_FOUR                    = 0x05
LOGILED_FIVE                    = 0x06
LOGILED_SIX                     = 0x07
LOGILED_SEVEN                   = 0x08
LOGILED_EIGHT                   = 0x09
LOGILED_NINE                    = 0x0A
LOGILED_ZERO                    = 0x0B
LOGILED_MINUS                   = 0x0C
LOGILED_EQUALS                  = 0x0D
LOGILED_BACKSPACE               = 0x0E
LOGILED_INSERT                  = 0x152
LOGILED_HOME                    = 0x147
LOGILED_PAGE_UP                 = 0x149
LOGILED_NUM_LOCK                = 0x45
LOGILED_NUM_SLASH               = 0x135
LOGILED_NUM_ASTERISK            = 0x37
LOGILED_NUM_MINUS               = 0x4A
LOGILED_TAB                     = 0x0F
LOGILED_Q                       = 0x10
LOGILED_W                       = 0x11
LOGILED_E                       = 0x12
LOGILED_R                       = 0x13
LOGILED_T                       = 0x14
LOGILED_Y                       = 0x15
LOGILED_U                       = 0x16
LOGILED_I                       = 0x17
LOGILED_O                       = 0x18
LOGILED_P                       = 0x19
LOGILED_OPEN_BRACKET            = 0x1A
LOGILED_CLOSE_BRACKET           = 0x1B
LOGILED_BACKSLASH               = 0x2B
LOGILED_KEYBOARD_DELETE         = 0x153
LOGILED_END                     = 0x14F
LOGILED_PAGE_DOWN               = 0x151
LOGILED_NUM_SEVEN               = 0x47
LOGILED_NUM_EIGHT               = 0x48
LOGILED_NUM_NINE                = 0x49
LOGILED_NUM_PLUS                = 0x4E
LOGILED_CAPS_LOCK               = 0x3A
LOGILED_A                       = 0x1E
LOGILED_S                       = 0x1F
LOGILED_D                       = 0x20
LOGILED_F                       = 0x21
LOGILED_G                       = 0x22
LOGILED_H                       = 0x23
LOGILED_J                       = 0x24
LOGILED_K                       = 0x25
LOGILED_L                       = 0x26
LOGILED_SEMICOLON               = 0x27
LOGILED_APOSTROPHE              = 0x28
LOGILED_ENTER                   = 0x1C
LOGILED_NUM_FOUR                = 0x4B
LOGILED_NUM_FIVE                = 0x4C
LOGILED_NUM_SIX                 = 0x4D
LOGILED_LEFT_SHIFT              = 0x2A
LOGILED_Z                       = 0x2C
LOGILED_X                       = 0x2D
LOGILED_C                       = 0x2E
LOGILED_V                       = 0x2F
LOGILED_B                       = 0x30
LOGILED_N                       = 0x31
LOGILED_M                       = 0x32
LOGILED_COMMA                   = 0x33
LOGILED_PERIOD                  = 0x34
LOGILED_FORWARD_SLASH           = 0x35
LOGILED_RIGHT_SHIFT             = 0x36
LOGILED_ARROW_UP                = 0x148
LOGILED_NUM_ONE                 = 0x4F
LOGILED_NUM_TWO                 = 0x50
LOGILED_NUM_THREE               = 0x51
LOGILED_NUM_ENTER               = 0x11C
LOGILED_LEFT_CONTROL            = 0x1D
LOGILED_LEFT_WINDOWS            = 0x15B
LOGILED_LEFT_ALT                = 0x38
LOGILED_SPACE                   = 0x39
LOGILED_RIGHT_ALT               = 0x138
LOGILED_RIGHT_WINDOWS           = 0x15C
LOGILED_APPLICATION_SELECT      = 0x15D
LOGILED_RIGHT_CONTROL           = 0x11D
LOGILED_ARROW_LEFT              = 0x14B
LOGILED_ARROW_DOWN              = 0x150
LOGILED_ARROW_RIGHT             = 0x14D
LOGILED_NUM_ZERO                = 0x52
LOGILED_NUM_PERIOD              = 0x53
LOGILED_G_1                     = 0xFFF1
LOGILED_G_2                     = 0xFFF2
LOGILED_G_3                     = 0xFFF3
LOGILED_G_4                     = 0xFFF4
LOGILED_G_5                     = 0xFFF5
LOGILED_G_6                     = 0xFFF6
LOGILED_G_7                     = 0xFFF7
LOGILED_G_8                     = 0xFFF8
LOGILED_G_9                     = 0xFFF9
LOGILED_G_LOGO                  = 0xFFFF1
LOGILED_G_BADGE                 = 0xFFFF2

gh_logiled.set_key_lighting(LOGILED_F1, 255, 255, 0)

set_lighting

Sets the same color to all LEDs.

syntax

gh_logiled.set_lighting (
r, g, b
)

parameters

r, g, b INTEGER red, green, blue color channels (0 to 100)

return values

none

code sample

gh_logiled.set_lighting(255, 255, 0)

set_pulse_lighting

Sets a pluse lighting effect.

syntax

gh_logiled.set_pulse_lighting (
r, g, b,
duration_ms,
interval_ms
)

parameters

r, g, b INTEGER red, green, blue color channels (0 to 100)
duration_ms INTEGER duration of the effect in milliseconds
interval_ms INTEGER interval in milliseconds

return values

none

code sample

gh_logiled.set_pulse_lighting(255, 255, 0,  3.0, 2.0)

set_target

Sets the device target.

syntax

gh_logiled.set_target (
target
)

parameters

target ENUM( target_type ) the type of target: 'monochrome', 'perkey_rgb' or 'rgb'

return values

none

code sample

gh_logiled.set_target("perkey_rgb")

stop_effects

Stops all effects.

syntax

gh_logiled.stop_effects()

parameters

none

return values

none

code sample

gh_logiled.stop_effects()

gh_material

Material module

gh_material is the module that manages materials: creation, destruction, parameters setting.
The fundamental goal of material is to define the final appearence of an object surface.
A material is made up of one or several textures and a GPU program.

add_texture

Adds a texture to the material.

syntax

gh_material.add_texture (
mat_id,
tex_id
)

parameters

mat_id ID material identifier
tex_id ID texture identifier

return values

none

code sample

gh_material.add_texture(mat_id, tex_id)

bind

Bind the material to the renderer: textures and GPU programs are bound.

syntax

gh_material.bind (
mat_id
)

parameters

mat_id ID material identifier

return values

none

code sample

gh_material.bind(mat_id)

create

Creates a material.

syntax

mat_id = gh_material.create()

parameters

none

return values

mat_id ID material identifier

code sample

mat_id = gh_material.create()

get_ambient

Get the ambiant reflection factor of the material.

syntax

r, g, b, a = gh_material.get_ambient (
mat_name
)

parameters

mat_name ID material identifier

return values

r, g, b, a REAL RGBA value

code sample

r, g, b, a = gh_material.get_ambient(mat_id)

get_diffuse

Get the diffuse reflection factor of the material.

syntax

r, g, b, a = gh_material.get_diffuse (
mat_name
)

parameters

mat_name ID material identifier

return values

r, g, b, a REAL RGBA value

code sample

r, g, b, a = gh_material.get_diffuse(mat_id)

get_gpu_program

Gets the GPU program of the material.

syntax

gpuprog_id = gh_material.get_gpu_program (
mat_id
)

parameters

mat_id ID material identifier

return values

gpuprog_id ID gpu program identifier

code sample

gpuprog_id = gh_material.get_gpu_program(mat_id)

get_num_textures

Gets the number of textures of the material.

syntax

n = gh_material.get_num_textures (
mat_id
)

parameters

mat_id ID material identifier

return values

n INTEGER number of textures

code sample

n = gh_material.get_num_textures(mat_id)

get_opacity

Get the opacity of the material.

syntax

opacity = gh_material.get_opacity (
mat_name
)

parameters

mat_name ID material identifier

return values

opacity REAL opacity value (range: 0.0 - 1.0)

code sample

opacity = gh_material.get_opacity(mat_id)

get_shininess

Get the shininess of the material.

syntax

shininess = gh_material.get_shininess (
mat_name
)

parameters

mat_name ID material identifier

return values

shininess REAL shininess value

code sample

shininess = gh_material.get_shininess(mat_id)

get_specular

Get the specular reflection factor of the material.

syntax

r, g, b, a = gh_material.get_specular (
mat_name
)

parameters

mat_name ID material identifier

return values

r, g, b, a REAL RGBA value

code sample

r, g, b, a = gh_material.get_specular(mat_id)

get_texture

Gets a particular texture of the material.

syntax

tid = gh_material.get_texture (
mat_id,
texture_index
)

parameters

mat_id ID material identifier
texture_index INTEGER texture index from 0 to get_num_textures()-1

return values

tid ID texture identifier

code sample

n = gh_material.get_num_textures(mat_id)
for i=0, n-1 do
	tid = gh_material.get_texture(mat_id, i)
	DoSomething(tid)
end

remove_texture

Removes a texture from the material.

syntax

gh_material.remove_texture (
mat_id,
tex_id
)

parameters

mat_id ID material identifier
tex_id ID texture identifier

return values

none

code sample

gh_material.remove_texture(mat_id, tex_id)

set_ambient

Set the ambiant reflection factor of the material.

syntax

gh_material.set_ambient (
mat_name,
r, g, b, a
)

parameters

mat_name ID material identifier
r, g, b, a REAL RGBA value

return values

none

code sample

gh_material.set_ambient(mat_id, r, g, b, a)

set_diffuse

Set the diffuse reflection factor of the material.

syntax

gh_material.set_diffuse (
mat_name,
r, g, b, a
)

parameters

mat_name ID material identifier
r, g, b, a REAL RGBA value

return values

none

code sample

gh_material.set_diffuse(mat_id, r, g, b, a)

set_gpu_program

Sets the GPU program of the material.

syntax

gh_material.set_gpu_program (
mat_id,
gpuprog_id
)

parameters

mat_id ID material identifier
gpuprog_id ID gpu program identifier

return values

none

code sample

gh_material.set_gpu_program(mat_id, gpuprog_id)

set_opacity

Set the opacity of the material.

syntax

gh_material.set_opacity (
mat_name,
opacity
)

parameters

mat_name ID material identifier
opacity REAL opacity value (range: 0.0 - 1.0)

return values

none

code sample

gh_material.set_opacity(mat_id, opacity)

set_shininess

Set the shininess of the material.

syntax

gh_material.set_shininess (
mat_name,
shininess
)

parameters

mat_name ID material identifier
shininess REAL shininess value

return values

none

code sample

shininess = 24.0			
gh_material.set_shininess(mat_id, shininess)

set_specular

Set the specular reflection factor of the material.

syntax

gh_material.set_specular (
mat_name,
r, g, b, a
)

parameters

mat_name ID material identifier
r, g, b, a REAL RGBA value

return values

none

code sample

gh_material.set_specular(mat_id, r, g, b, a)

vk_descriptorset_add_all_textures

Vulkan only - Adds all textures of a material to a vulkan descriptor set.

syntax

gh_material.vk_descriptorset_add_all_textures (
mat_id,
descriptorset_id,
binding_point_start,
shader_stages,
sampler_id
)

parameters

mat_id ID material identifier
descriptorset_id ID descriptor set identifier
binding_point_start INTEGER binding point start
shader_stages INTEGER shader stages: SHADER_STAGE_VERTEX, SHADER_STAGE_FRAGMENT, ... All shader stages values are in the vk.lua file
sampler_id ID texture sampler identifier

return values

none

code sample

binding_point_start = 1			
shader_stages = SHADER_STAGE_FRAGMENT
gh_material.vk_descriptorset_add_all_textures(mat_id, descriptorset_id, binding_point_start, shader_stages, sampler)

vk_descriptorset_add_texture

Vulkan only - Adds a texture of a material to a vulkan descriptor set.

syntax

resource_index = gh_material.vk_descriptorset_add_texture (
mat_id,
descriptorset_id,
texture_index,
binding_point,
shader_stages,
sampler_id
)

parameters

mat_id ID material identifier
descriptorset_id ID descriptor set identifier
texture_index INTEGER texture index: from 0 to get_num_textures()-1
binding_point INTEGER binding point
shader_stages INTEGER shader stages: SHADER_STAGE_VERTEX, SHADER_STAGE_FRAGMENT, ... All shader stages values are in the vk.lua file
sampler_id ID texture sampler identifier

return values

resource_index INTEGER resource index in the descriptor set. This index can be used with gh_vk.descriptorset_update_resource_texture().

code sample

binding_point = 1			
texture_index = 0
shader_stages = SHADER_STAGE_FRAGMENT
resource_index = gh_material.vk_descriptorset_add_texture(mat_id, descriptorset_id, texture_index, binding_point, shader_stages, sampler)

binding_point = 2			
texture_index = 1
shader_stages = SHADER_STAGE_FRAGMENT
resource_index = gh_material.vk_descriptorset_add_texture(mat_id, descriptorset_id, texture_index, binding_point, shader_stages, sampler)

vk_descriptorset_copy

Vulkan only - copies the information of a vulkan descriptor set from a source material to a destination material.
This function does not update the Vulkan descriptor set referenced by the source material.
This function is useful if you have several materials with same texture layout (same number and type of textures) that have to share the same descriptor set.

syntax

gh_material.vk_descriptorset_copy (
material_src_id,
material_dst_id
)

parameters

material_src_id ID source material identifier
material_dst_id ID destination material identifier

return values

none

code sample

gh_material.vk_descriptorset_copy(material_src_id, material_dst_id)

vk_descriptorset_update_all_textures

Vulkan only - updates a vulkan descriptor set with the textures of a material.
This function is automatically called when a model is rendered.

syntax

gh_material.vk_descriptorset_update_all_textures (
material_id
)

parameters

material_id ID material identifier

return values

none

code sample

gh_material.vk_descriptorset_update_all_textures(material_id)

gh_mesh

Mesh module

gh_mesh is the module that manages the meshes.
A mesh is a set of triangular faces that can be used to represent any type of 3D shape: starting from the basic built-in shapes (plane, torus, sphere) to complex shapes created with modeling softwares such as 3D Studio Max or Blender.

alloc_mesh_data

Allocates memory for mesh data (vertices and faces lists).

syntax

gh_mesh.alloc_mesh_data (
mesh_id,
num_vertices,
num_faces
)

parameters

mesh_id ID mesh identifier
num_vertices INTEGER number of vertices
num_faces INTEGER number of faces

return values

none

code sample

mesh_triangle = gh_mesh.create()

gh_mesh.alloc_mesh_data(mesh_triangle, 3, 1)

create_box

Creates a mesh box.

syntax

mesh_id = gh_mesh.create_box (
width, height, depth,
wsegs, hsegs, dsegs
)

parameters

width, height, depth REAL size of the box
wsegs, hsegs, dsegs INTEGER number of subdivisions along X, Y and Z axis

return values

mesh_id ID mesh identifier

code sample

mesh_box = gh_mesh.create_box(10.0, 10.0, 10.0, 4, 4, 4)

create_box_8v

Creates a mesh box with 8 vertices.

syntax

mesh_id = gh_mesh.create_box_8v (
width, height, depth
)

parameters

width, height, depth REAL size of the box

return values

mesh_id ID mesh identifier

code sample

mesh_box = gh_mesh.create_box_8v(10.0, 10.0, 10.0)

create_cylinder

Creates a mesh cylinder.

syntax

mesh_id = gh_mesh.create_cylinder (
radius,
height,
stacks,
slices
)

parameters

radius REAL radius of the cylinder
height REAL height of the cylinder
stacks INTEGER number of subdivisions along the height
slices INTEGER number of subdivisions along the perimeter

return values

mesh_id ID mesh identifier

code sample

mesh_cyl = gh_mesh.create_cylinder(radius, height, stacks, slices)

create_cylinder_xyz

Creates a mesh cylinder.

syntax

mesh_id = gh_mesh.create_cylinder_xyz (
central_axis,
radius,
height,
stacks,
slices
)

parameters

central_axis ENUM( along_axis ) direction of the central axis: 0 (along X axis), 1 (along Y axis) or 2 (along Z axis)
radius REAL radius of the cylinder
height REAL height of the cylinder
stacks INTEGER number of subdivisions along the height
slices INTEGER number of subdivisions along the perimeter

return values

mesh_id ID mesh identifier

code sample

central_axis = 1 -- a Y-axis oriented cylinder

mesh_cyl = gh_mesh.create_cylinder_xyz(central_axis, radius, height, stacks, slices)

create_disc

Creates a mesh disc.

syntax

mesh_id = gh_mesh.create_disc (
radius,
thickness,
slices
)

parameters

radius REAL radius of the disc
thickness REAL thickness of the disc
slices INTEGER number of subdivisions along the perimeter

return values

mesh_id ID mesh identifier

code sample

mesh_disc = gh_mesh.create_disc(radius, thickness, slices)

create_ellipse

Creates a mesh ellipse.

syntax

mesh_id = gh_mesh.create_ellipse (
major_radius,
minor_radius,
slices,
radius_segments,
opening_angle
)

parameters

major_radius REAL major radius of the ellipse
minor_radius REAL minor radius of the ellipse
slices INTEGER number of subdivisions along the perimeter
radius_segments INTEGER number of subdivisions along the radius
opening_angle REAL opening angle. If 0, the ellipse is close

return values

mesh_id ID mesh identifier

code sample

mesh_ellipse = gh_mesh.create_ellipse(major_radius, minor_radius, slices, radius_segments, opening_angle)

mesh_disc = gh_mesh.create_ellipse(radius, radius, 20, 20, 0)

create_gear

Creates a mesh gear.

syntax

mesh_id = gh_mesh.create_gear (
inner_radius,
outer_radius,
tooth_depth,
num_teeth,
width
)

parameters

inner_radius REAL inner radius
outer_radius REAL outer radius
tooth_depth REAL depth of a tooth
num_teeth INTEGER number of teeth of the gear
width REAL width of the gear

return values

mesh_id ID mesh identifier

code sample

mesh_gear = gh_mesh.create_gear(1.0, 4.0,  1.0, 10,  2.0)

create_icosphere

Creates an ico-sphere mesh.

syntax

mesh_id = gh_mesh.create_icosphere (
radius,
recursion_level
)

parameters

radius REAL sphere radius
recursion_level INTEGER level of detail

return values

mesh_id ID mesh identifier

code sample

mesh_icosphere = gh_mesh.create_icosphere(10.0, 2)

create_plane

Creates a mesh plane.

syntax

mesh_id = gh_mesh.create_plane (
width, height,
wsegs, hsegs
)

parameters

width, height REAL size of the plane in the XZ plane
wsegs, hsegs INTEGER number of subdivisions along the X and Z axis

return values

mesh_id ID mesh identifier

code sample

mesh_plane = gh_mesh.create_plane(20.0, 10.0, 4, 4)

create_plane_v3

Creates a mesh plane with an initial rotation.

syntax

mesh_id = gh_mesh.create_plane_v3 (
width, height,
wsegs, hsegs,
pitch, yaw, roll
)

parameters

width, height REAL size of the plane in the XZ plane
wsegs, hsegs INTEGER number of subdivisions along the X and Z axis
pitch, yaw, roll REAL initial orientation of the vertices using Euler's angles

return values

mesh_id ID mesh identifier

code sample

mesh_plane = gh_mesh.create_plane_v3(20.0, 10.0, 4, 4, 45.0, 0, 0)

create_quad

Creates a mesh quad.
A quad is a mesh plane with only 4 vertices.

syntax

mesh_id = gh_mesh.create_quad (
width, height
)

parameters

width, height REAL size of the quad in the XY plane

return values

mesh_id ID mesh identifier

code sample

mesh_quad = gh_mesh.create_quad(20.0, 10.0)

create_sphere

Creates a mesh sphere.

syntax

mesh_id = gh_mesh.create_sphere (
radius,
stacks, slices
)

parameters

radius REAL radius of the sphere
stacks, slices INTEGER number of subdivisions along the X and Y axis.

return values

mesh_id ID mesh identifier

code sample

mesh_sphere = gh_mesh.create_sphere(10.0, 20, 20)

create_terrain

Creates a mesh terrain from a height map.

syntax

mesh_id = gh_mesh.create_terrain (
tex_id,
num_subdivisions,
vertical_scale,
terrain_size,
height_threshold
)

parameters

tex_id ID terrain texture identifier (height map)
num_subdivisions INTEGER number of subdivisions
vertical_scale REAL vertical scale factor
terrain_size REAL size of the terrain (the terrain is a square patch)
height_threshold REAL height threshold

return values

mesh_id ID mesh identifier

code sample

mesh_terrain = gh_mesh.create_terrain(tex_id, num_subdivisions, vertical_scale, terrain_size, height_threshold)

create_torus

Creates a mesh torus.

syntax

mesh_id = gh_mesh.create_torus (
outer_radius,
inner_radius,
slices
)

parameters

outer_radius REAL outer radius of the torus
inner_radius REAL inner radius of the torus
slices INTEGER number of subdivisions or sections

return values

mesh_id ID mesh identifier

code sample

mesh_torus = gh_mesh.create_torus(10.0, 4.0, 20)

create_triangle

Creates a mesh triangle.
Vertices are positioned in the range [-1.0;+1.0].

syntax

mesh_id = gh_mesh.create_triangle()

parameters

none

return values

mesh_id ID mesh identifier

code sample

mesh_triangle = gh_mesh.create_triangle()

create_v2

Creates a mesh.

syntax

mesh_id = gh_mesh.create_v2()

parameters

none

return values

mesh_id ID mesh identifier

code sample

mesh_id = gh_mesh.create_v2()

get_face_normal

Gets the normal vector of a face.
Be sure that gh_object.compute_faces_normal() has been called before.

syntax

x, y, z = gh_mesh.get_face_normal (
mesh_id,
face_index
)

parameters

mesh_id ID mesh identifier
face_index INTEGER index of the face between 0 and gh_object.get_num_faces()-1

return values

x, y, z REAL normal vector

code sample

x, y, z = gh_mesh.get_face_normal(mesh_id, face_index)

get_face_vertex_indices

Gets the vertex indices of a particular face.

syntax

a, b, c = gh_mesh.get_face_vertex_indices (
mesh_id,
face_index
)

parameters

mesh_id ID mesh identifier
face_index INTEGER index of the face between 0 and gh_object.get_num_faces()-1

return values

a, b, c INTEGER vertex indices

code sample

a, b, c = gh_mesh.get_face_vertex_indices(mesh_id, face_index)

get_vertex_absolute_position

Gets the absolute position of a particular vertex.

syntax

x, y, z = gh_mesh.get_vertex_absolute_position (
mesh_id,
vertex_index
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1

return values

x, y, z REAL 3D position

code sample

vertex_index = 0
x, y, z = gh_mesh.get_vertex_absolute_position(mesh_id, vertex_index)

get_vertex_color

Gets the RGBA color of a particular vertex.

syntax

r, g, b, a = gh_mesh.get_vertex_color (
mesh_id,
vertex_index
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1

return values

r, g, b, a REAL RGBA color of the vertex

code sample

vertex_index = 0
r, g, b, a = gh_mesh.get_vertex_color(mesh_id, vertex_index)

get_vertex_normal

Gets the normal vector of a particular vertex.

syntax

x, y, z = gh_mesh.get_vertex_normal (
mesh_id,
vertex_index
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1

return values

x, y, z REAL normal vector

code sample

vertex_index = 0
x, y, z = gh_mesh.get_vertex_normal(mesh_id, vertex_index)

get_vertex_position

Gets the relative position of a particular vertex.

syntax

x, y, z, w = gh_mesh.get_vertex_position (
mesh_id,
vertex_index
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1

return values

x, y, z, w REAL 4D position

code sample

vertex_index = 0
x, y, z, w = gh_mesh.get_vertex_position(mesh_id, vertex_index)

get_vertex_tangent

Gets the tangent vector of a particular vertex.

syntax

x, y, z, w = gh_mesh.get_vertex_tangent (
mesh_id,
vertex_index
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1

return values

x, y, z, w REAL tangent vector

code sample

vertex_index = 0
x, y, z, w = gh_mesh.get_vertex_tangent(mesh_id, vertex_index)

get_vertex_uv

Gets the texcoord of a particular vertex.

syntax

x, y, z, w = gh_mesh.get_vertex_uv (
mesh_id,
vertex_index,
tex_unit
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1
tex_unit INTEGER texture unit of the texcoord set. Only two sets are supported

return values

x, y, z, w REAL tangent vector

code sample

vertex_index = 0
tex_unit = 0

x, y, z, w = gh_mesh.get_vertex_uv(mesh_id, vertex_index, tex_unit)

instancing_attrib_buffer_get

Returns the memory buffer of a particular vertex attrib.
The pointer returned can be used with gh_utils.buffer_read_xxx() and gh_utils.buffer_write_xxx() functions.

syntax

buff_ptr, buff_size = gh_mesh.instancing_attrib_buffer_get (
mesh_id,
va_index
)

parameters

mesh_id ID mesh identifier
va_index INTEGER vertex attrib index

return values

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

code sample

va_index = 0
position_ptr, size = gh_mesh.instancing_attrib_buffer_get(mesh_id, va_index)

instancing_attrib_buffer_update_needed

Notifies GeeXLab that a vertex attrib buffer has been updated and needs to be uploaded on the GPU.

syntax

gh_mesh.instancing_attrib_buffer_update_needed (
mesh_id,
va_index
)

parameters

mesh_id ID mesh identifier
va_index INTEGER vertex attrib index

return values

none

code sample

va_index = 0
gh_mesh.instancing_attrib_buffer_update_needed(mesh_id, va_index)

instancing_get_color

Gets the color of a particular instance.

syntax

r, g, b, a = gh_mesh.instancing_get_color (
mesh_id,
index
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1

return values

r, g, b, a REAL RGBA color of the instance

code sample

r, g, b, a = gh_mesh.instancing_get_color(mesh_id, instance)

instancing_get_orientation

Gets the orientation of a particular instance.

syntax

x, y, z, w = gh_mesh.instancing_get_orientation (
mesh_id,
index
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1

return values

x, y, z, w REAL orientation of the instance (quaternion)

code sample

x, y, z, w = gh_mesh.instancing_get_orientation(mesh_id, instance)

instancing_get_position

Gets the position of a particular instance.

syntax

x, y, z, w = gh_mesh.instancing_get_position (
mesh_id,
index
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1

return values

x, y, z, w REAL position of the instance

code sample

x, y, z, w = gh_mesh.instancing_get_position(mesh_id, instance)

instancing_get_scale

Gets the scale of a particular instance.

syntax

x, y, z, w = gh_mesh.instancing_get_scale (
mesh_id,
index
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1

return values

x, y, z, w REAL scale of the instance

code sample

x, y, z, w = gh_mesh.instancing_get_scale(mesh_id, instance)

instancing_init

Initializes the geometry instancing rendering.

syntax

gh_mesh.instancing_init (
mesh_id,
num_instances
)

parameters

mesh_id ID mesh identifier
num_instances INTEGER number of instances

return values

none

code sample

-- mesh instancing requires separate vertex arrays.
separate_vertex_arrays = 1
gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances-1 do
    x = math.random(-100, 100)
    y = math.random(-50, 50)
    z = 0.0
    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)

    x = math.random(-60, 60)
    y = math.random(-60, 60)
    z = math.random(-60, 60)
    gh_mesh.instancing_set_orientation(mesh_id, i, x, y, z)
end

instancing_set_axis_angle

Sets the rotation axis and the angle of rotation around this axis for a particular instance.

syntax

gh_mesh.instancing_set_axis_angle (
mesh_id,
index,
x, y, z,
angle
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
x, y, z REAL rotation axis
angle REAL rotation angle

return values

none

code sample

-- mesh instancing requires separate vertex arrays.

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

local num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)

    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)
    gh_mesh.instancing_set_axis_angle(mesh_id, i, 0.0, 0.0, 1.0, 60.0)
    gh_mesh.instancing_set_color(mesh_id, i, 1.0, 1.0, 1.0, 1.0)
end

instancing_set_color

Sets the color of a particular instance.

syntax

gh_mesh.instancing_set_color (
mesh_id,
index,
r, g, b, a
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
r, g, b, a REAL RGBA color of the instance

return values

none

code sample

-- mesh instancing requires separate vertex arrays.

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

local num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)

    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)
    gh_mesh.instancing_set_color(mesh_id, i, 1.0, 1.0, 1.0, 1.0)
end

instancing_set_orientation

Sets the orientation of a particular instance using Euler's angles.

syntax

gh_mesh.instancing_set_orientation (
mesh_id,
index,
pitch, yaw, roll
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
pitch, yaw, roll REAL angles of rotation around X, Y and Z axis

return values

none

code sample

-- mesh instancing requires separate vertex arrays.

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

local num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)
    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)

    x = math.random(-60, 60)
    y = math.random(-60, 60)
    z = math.random(-60, 60)
    gh_mesh.instancing_set_orientation(mesh_id, i, x, y, z)
end

instancing_set_orientation_v2

Sets the orientation of a particular instance with a quaternion.

syntax

gh_mesh.instancing_set_orientation_v2 (
mesh_id,
index,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
x, y, z, w REAL rotation quaternion

return values

none

code sample

local num_instances = 1000
gh_mesh.instancing_init(mesh, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)
    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)

    qx = ...
    qy = ...
    qz = ...
    qw = ...
    gh_mesh.instancing_set_orientation_v2(mesh_id, i, qx, qy, qz, qw)
end

instancing_set_position

Sets the position of a particular instance.

syntax

gh_mesh.instancing_set_position (
mesh_id,
index,
x, y, z
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
x, y, z REAL position of the instance

return values

none

code sample

-- mesh instancing requires separate vertex arrays.

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

local num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)
    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)

    x = math.random(-60, 60)
    y = math.random(-60, 60)
    z = math.random(-60, 60)
    gh_mesh.instancing_set_orientation(mesh_id, i, x, y, z)
end

instancing_set_position_v2

Sets the position of a particular instance.

syntax

gh_mesh.instancing_set_position_v2 (
mesh_id,
index,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
x, y, z, w REAL position of the instance

return values

none

code sample

-- mesh instancing requires separate vertex arrays.

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

local num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)

    gh_mesh.instancing_set_position_v2(mesh_id, i, x, y, z, 1.0)
end

instancing_set_scale

Sets the scaling factor of a particular instance.

syntax

gh_mesh.instancing_set_scale (
mesh_id,
index,
x, y, z
)

parameters

mesh_id ID mesh identifier
index INTEGER index of the instance from 0 to num_instances-1
x, y, z REAL scaling factors along the 3 axis

return values

none

code sample

-- mesh instancing requires separate vertex arrays.

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(separate_vertex_arrays)

local num_instances = 1000
gh_mesh.instancing_init(mesh_id, num_instances)

local i
for i=0, num_instances do
    x = math.random(-10, 10)
    y = math.random(-10, 10)
    z = math.random(-10, 10)

    gh_mesh.instancing_set_position(mesh_id, i, x, y, z)
    gh_mesh.instancing_set_scale(mesh_id, i, 1.0, 1.0, 1.0)
end

meshlet_generate

Meshletizes (generates meshlets from) a regular mesh.
Useful with mesh shaders.

syntax

ret = gh_mesh.meshlet_generate (
mesh_id,
max_vertices,
max_indices
)

parameters

mesh_id ID mesh identifier
max_vertices INTEGER max vertices of a meshlet
max_indices INTEGER max indices of a meshlet. 3 indices make a triangular face.

return values

ret INTEGER 1 if ok, 0 if error.

code sample

ret = gh_mesh.meshlet_generate(mesh_id, 64, 126)

meshlet_get_count

Returns the number of meshlets of a mesh.

syntax

n = gh_mesh.meshlet_get_count (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

n INTEGER number of meshlets

code sample

n = gh_mesh.meshlet_get_count(mesh_id)

meshlet_get_index

Returns a index relative to the meshlet (yes meshlet) indices list.
This index is usually used to fill a GPU buffer for rendering with mesh shaders.

syntax

mesh_face_index = gh_mesh.meshlet_get_index (
mesh_id,
meshlet_index,
meshlet_primitive_index
)

parameters

mesh_id ID mesh identifier
meshlet_index INTEGER meshlet index (0 to num_meshlets-1)
meshlet_primitive_index INTEGER index in the meshlet indices list (0 to num_meshlet_indices-1)

return values

mesh_face_index INTEGER index relative to the meshlet indices list

code sample

mesh_face_index = gh_mesh.meshlet_get_index(mesh_id, meshlet_index, meshlet_primitive_index)

meshlet_get_index_count

Returns the number of indices of a particular meshlet.

syntax

num_meshlet_indices = gh_mesh.meshlet_get_index_count (
mesh_id,
meshlet_index
)

parameters

mesh_id ID mesh identifier
meshlet_index INTEGER meshlet index (0 to num_meshlets-1)

return values

num_meshlet_indices INTEGER number of indices

code sample

num_meshlet_indices = gh_mesh.meshlet_get_index_count(mesh_id)

meshlet_get_vertex

Returns a index relative to the mesh (yes mesh) vertices list.
This index is usually used to fill a GPU buffer for rendering with mesh shaders

syntax

mesh_vertex_index = gh_mesh.meshlet_get_vertex (
mesh_id,
meshlet_index,
meshlet_vertex_index
)

parameters

mesh_id ID mesh identifier
meshlet_index INTEGER meshlet index (0 to num_meshlets-1)
meshlet_vertex_index INTEGER vertex in the meshlet vertices list (0 to num_meshlet_vertices-1)

return values

mesh_vertex_index INTEGER index relative to the mesh vertices list

code sample

mesh_vertex_index = gh_mesh.meshlet_get_vertex(mesh_id, meshlet_index, meshlet_vertex_index)

meshlet_get_vertex_count

Returns the number of vertices of a particular meshlet.

syntax

num_meshlet_vertices = gh_mesh.meshlet_get_vertex_count (
mesh_id,
meshlet_index
)

parameters

mesh_id ID mesh identifier
meshlet_index INTEGER meshlet index (0 to num_meshlets-1)

return values

num_meshlet_vertices INTEGER number of vertices

code sample

num_meshlet_vertices = gh_mesh.meshlet_get_vertex_count(mesh_id)

resize_box

Updates the size of the mesh box (update the position of all vertices).

syntax

gh_mesh.resize_box (
width, height, depth,
mesh_id
)

parameters

width, height, depth REAL size of the box
mesh_id ID mesh identifier

return values

none

code sample

gh_mesh.resize_box(mesh_id, 10.0, 10.0, 10.0)

resize_plane

Updates the width and height of a mesh plane.

syntax

gh_mesh.resize_plane (
mesh_id,
width, height
)

parameters

mesh_id ID mesh identifier
width, height REAL size of the quad in the XY plane

return values

none

code sample

gh_mesh.resize_plane(mesh_id, 20.0, 15.0)

resize_quad

Updates the width and height of a mesh quad.

syntax

gh_mesh.resize_quad (
mesh_id,
width, height
)

parameters

mesh_id ID mesh identifier
width, height REAL size of the quad in the XY plane

return values

none

code sample

gh_mesh.resize_quad(mesh_id, 20.0, 15.0)

ribbon_add_point

Adds a new point to the ribbon.
Each new point will generate the real geometry.

syntax

gh_mesh.ribbon_add_point (
mesh_id,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
x, y, z, w REAL position of the new point

return values

none

code sample

gh_mesh.ribbon_add_point(mesh_id, x, y, z, 1.0)

ribbon_create

Creates a mesh ribbon.
Once the ribbon object is created you need to call ribbon_add_point() to create vertices.

syntax

mesh_id = gh_mesh.ribbon_create (
thickness
)

parameters

thickness REAL thickness of ribbon

return values

mesh_id ID mesh identifier

code sample

mesh_id = gh_mesh.ribbon_create(2.0)

ribbon_set_cross_vector

Sets the cross vector that tunes the orientation of the ribbon.

syntax

gh_mesh.ribbon_set_cross_vector (
mesh_id,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
x, y, z, w REAL vector coordinates

return values

none

code sample

gh_mesh.ribbon_set_cross_vector(mesh_id, x, y, z)

set_face_vertex_indices

Sets the vertex indices of a particular face.

syntax

gh_mesh.set_face_vertex_indices (
mesh_id,
face_index,
a, b, c
)

parameters

mesh_id ID mesh identifier
face_index INTEGER index of the face
a, b, c INTEGER vertex indices

return values

none

code sample

gh_mesh.set_face_vertex_indices(mesh_id, face_index, a, b, c)

set_vertex_alloc_params_separate_vertex_arrays

Tells GeeXLab to create the next meshes with separate vertex arrays (state=1) or with an interleaved vertex array (state=0).

syntax

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays (
state
)

parameters

state INTEGER 1 (separate vertex arrays) or 0 (interleaved vertex array) - Default is separate vertex arrays.

return values

none

code sample

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0)
...
mesh = gh_mesh.create_plane(128, 128, 10, 10)
...
gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(1)

set_vertex_color

Sets the RGBA color of a particular vertex.

syntax

gh_mesh.set_vertex_color (
mesh_id,
vertex_index,
r, g, b, a
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1
r, g, b, a REAL RGBA color of the vertex

return values

none

code sample

vertex_index = 0
gh_mesh.set_vertex_color(mesh_id, vertex_index, r, g, b, a)

set_vertex_normal

Sets the normal vector of a particular vertex.

syntax

gh_mesh.set_vertex_normal (
mesh_id,
vertex_index,
x, y, z
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1
x, y, z REAL normal vector

return values

none

code sample

vertex_index = 0
gh_mesh.set_vertex_normal(mesh_id, vertex_index, x, y, z)

set_vertex_position

Sets the relative position of a particular vertex.

syntax

gh_mesh.set_vertex_position (
mesh_id,
vertex_index,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1
x, y, z, w REAL 3D position

return values

none

code sample

vertex_index = 0
gh_mesh.set_vertex_position(mesh_id, vertex_index, x, y, z, 1.0)

set_vertex_source

Sets a GPU buffer as the source of vertices for a mesh.
The mesh must have been created with an interleaved vertex array.
Call gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0) before creating the mesh.
The GPU buffer must use a an interleaved vertex structure too.

syntax

gh_mesh.set_vertex_source (
mesh_id,
gpu_buffer_id
)

parameters

mesh_id ID mesh identifier
gpu_buffer_id ID gpu buffer identifier

return values

none

code sample

gh_mesh.set_vertex_source(mesh_id, gpu_buffer_id)

set_vertex_tangent

Sets the tangent vector of a particular vertex.

syntax

gh_mesh.set_vertex_tangent (
mesh_id,
vertex_index,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1
x, y, z, w REAL tangent vector

return values

none

code sample

vertex_index = 0
gh_mesh.set_vertex_tangent(mesh_id, vertex_index, x, y, z, w)

set_vertex_uv

Sets the texcoord of a particular vertex.

syntax

gh_mesh.set_vertex_uv (
mesh_id,
vertex_index,
x, y, z, w,
tex_unit
)

parameters

mesh_id ID mesh identifier
vertex_index INTEGER index of the vertex between 0 and gh_object.get_num_vertices()-1
x, y, z, w REAL texcoord
tex_unit INTEGER texture unit of the texcoord set. Only two sets are supported

return values

none

code sample

vertex_index = 0
tex_unit = 0

gh_mesh.set_vertex_uv(mesh_id, vertex_index, x, y, z, w, tex_unit)

set_vertices_color

Sets the RGBA color of all vertices.

syntax

gh_mesh.set_vertices_color (
mesh_id,
r, g, b, a
)

parameters

mesh_id ID mesh identifier
r, g, b, a REAL RGBA color of the vertex

return values

none

code sample

gh_mesh.set_vertices_color(mesh_id, r, g, b, a)

vertices_from_gpu_buffer

Copies the vertex array from a GPU buffer to the mesh.
The mesh must have been created with an interleaved vertex array.
Call gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0) before creating the mesh.
The GPU buffer must use a an interleaved vertex structure too.

syntax

gh_mesh.vertices_from_gpu_buffer (
mesh_id,
gpu_buffer_id,
gpu_buffer_offset,
size,
update_cpu,
update_gpu
)

parameters

mesh_id ID mesh identifier
gpu_buffer_id ID gpu buffer identifier
gpu_buffer_offset INTEGER offset in the gpu buffer in bytes
size INTEGER size of the copy in bytes
update_cpu BOOLEAN update the mesh vertex array in CPU memory: 1 (YES) or 0 (NO)
update_gpu BOOLEAN update the mesh vertex array in GPU memory: 1 (YES) or 0 (NO)

return values

none

code sample

gh_mesh.vertices_from_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset, size, update_cpu, update_gpu)

vertices_position_from_gpu_buffer

Updates the position attribute of the mesh from a GPU buffer.
The mesh can have an interleaved vertex array or separate vertex arrays.

syntax

gh_mesh.vertices_position_from_gpu_buffer (
mesh_id,
gpu_buffer_id,
gpu_buffer_offset,
gpu_buffer_stride,
size,
update_cpu,
update_gpu
)

parameters

mesh_id ID mesh identifier
gpu_buffer_id ID gpu buffer identifier
gpu_buffer_offset INTEGER offset in the gpu buffer in bytes
gpu_buffer_stride INTEGER stride value: size in bytes between to consecutive positions in the gpu buffer
size INTEGER size of the copy in bytes
update_cpu BOOLEAN update the mesh vertex array in CPU memory: 1 (YES) or 0 (NO)
update_gpu BOOLEAN update the mesh vertex array in GPU memory: 1 (YES) or 0 (NO)

return values

none

code sample

gpu_buffer_stride = 16   # 16 bytes = size of a vec4. 			
gpu_buffer_offset = 0
gh_mesh.vertices_position_from_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset, gpu_buffer_stride, size, update_cpu, update_gpu)

vertices_position_to_gpu_buffer

Copies the position of all vertices to a GPU buffer.
The mesh can have an interleaved vertex array or separate vertex arrays.

syntax

gh_mesh.vertices_position_to_gpu_buffer (
mesh_id,
gpu_buffer_id,
gpu_buffer_offset,
gpu_buffer_stride
)

parameters

mesh_id ID mesh identifier
gpu_buffer_id ID gpu buffer identifier
gpu_buffer_offset INTEGER offset in the gpu buffer in bytes
gpu_buffer_stride INTEGER stride value: size in bytes between to consecutive positions in the gpu buffer

return values

none

code sample

gpu_buffer_stride = 16   # 16 bytes = size of a vec4. 			
gpu_buffer_offset = 0
gh_mesh.vertices_position_to_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset, gpu_buffer_stride)

vertices_to_gpu_buffer

Copies the whole vertex array of a mesh to a GPU buffer.
The mesh must have been created with an interleaved vertex array.
Call gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0) before creating the mesh.
The GPU buffer must use a an interleaved vertex structure too.

syntax

gh_mesh.vertices_to_gpu_buffer (
mesh_id,
gpu_buffer_id,
gpu_buffer_offset
)

parameters

mesh_id ID mesh identifier
gpu_buffer_id ID gpu buffer identifier
gpu_buffer_offset INTEGER offset in the gpu buffer in bytes

return values

none

code sample

gh_mesh.vertices_to_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset)

voxelize

Voxelizes a mesh.

syntax

gh_mesh.voxelize (
mesh_id,
voxelsizex,
voxelsizey,
voxelsizez
)

parameters

mesh_id ID mesh identifier
voxelsizex REAL width of a voxel
voxelsizey REAL height of a voxel
voxelsizez REAL depth of a voxel

return values

none

code sample

gh_mesh.voxelize(mesh_id, 4, 4, 4)

gh_model

Model module

gh_model is the module that manages models.
A model node allows to define a 3d model.
A model is a hierarchy of objects mainly made out of meshes.
Some objects like gizmos (a very simple object node) may belong to this hierarchy to act as a pivot point on which more complex structures can be built.
To keep it simple let's say a model is a kind of interface for easily modifying the properties of a number of meshes (children).
GeeXLab can load directly many 3D models formats such as *.3ds, *.obj, *.glTF, *.x, etc.

create_from_file

Loads a 3d object filename and creates a model.

syntax

model_id = gh_model.create_from_file (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "wheel.3ds"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file(model_filename, model_directory, resource_directory)

create_from_file_loader_3ds

Loads a *.3ds object filename and creates a model.

syntax

model_id = gh_model.create_from_file_loader_3ds (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "wheel.3ds"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file_loader_3ds(model_filename, model_directory, resource_directory)

create_from_file_loader_assimp

Loads a 3D object filename using ASSIMP (many 3D formats are supported) plugin and creates a model.

syntax

model_id = gh_model.create_from_file_loader_assimp (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "wheel.stl"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file_loader_assimp(model_filename, model_directory, resource_directory)

create_from_file_loader_assimp_v2

Loads a 3D object filename using ASSIMP (many 3D formats are supported) plugin and creates a model.

syntax

model_id = gh_model.create_from_file_loader_assimp_v2 (
model_filename,
model_directory,
resource_directory,
pp_options
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)
pp_options ENUM( assimp_options ) post processing options for ASSIMP

return values

model_id ID model identifier

code sample

model_filename = "wheel.stl"
model_directory = "data/"
resource_directory = "data/"

pp_options = ""

model_id = gh_model.create_from_file_loader_assimp_v2(model_filename, model_directory, resource_directory, pp_options)

create_from_file_loader_fbx

Loads a *.fbx, *.3ds or *.obj object filename and creates a model.

syntax

model_id = gh_model.create_from_file_loader_fbx (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "wheel.fbx"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file_loader_fbx(model_filename, model_directory, resource_directory)

create_from_file_loader_gltf

Loads a *.gltf object filename and creates a model.

syntax

model_id = gh_model.create_from_file_loader_gltf (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "scene.gltf"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file_loader_gltf(model_filename, model_directory, resource_directory)

create_from_file_loader_obj

Loads a *.obj object filename and creates a model.

syntax

model_id = gh_model.create_from_file_loader_obj (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "wheel.obj"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file_loader_obj(model_filename, model_directory, resource_directory)

create_from_file_loader_stl

Loads a binary *.stl object filename and creates a model.

syntax

model_id = gh_model.create_from_file_loader_stl (
model_filename,
model_directory,
resource_directory
)

parameters

model_filename STRING 3d object filename
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)

return values

model_id ID model identifier

code sample

model_filename = "wheel.stl"
model_directory = "data/"
resource_directory = "data/"

model_id = gh_model.create_from_file_loader_stl(model_filename, model_directory, resource_directory)

create_from_zip_file_loader_assimp

Loads a 3D object file using ASSIMP plugin (many 3D formats are supported) from a zip archive and creates a model.

syntax

model_id = gh_model.create_from_zip_file_loader_assimp (
zip_filename,
model_filename,
model_directory,
resource_directory,
pp_options
)

parameters

zip_filename STRING absolute path of the zip file
model_filename STRING 3d object filename in the zip file
model_directory STRING directory of the model filename
resource_directory STRING directory of the resources used by the model (usually textures)
pp_options ENUM( assimp_options ) post processing options for ASSIMP

return values

model_id ID model identifier

code sample

zip_filename = gh_utils.get_demo_dir() .. "demo.zip"
model_filename = "wheel.stl"
model_directory = "data/"
resource_directory = "data/"

pp_options = ""

model_id = gh_model.create_from_zip_file_loader_assimp(zip_filename, model_filename, model_directory, resource_directory, pp_options)

get_num_opaque_meshes

Returns the number of opaque meshes.
Call update_meshes_lists() before (in INIT script for example).

syntax

num_opaque_meshes = gh_model.get_num_opaque_meshes (
model_id
)

parameters

model_id ID model identifier

return values

num_opaque_meshes INTEGER number of opaque meshes

code sample

num_opaque_meshes = gh_model.get_num_opaque_meshes(model_id)

get_num_transparent_meshes

Returns the number of transparent meshes.
Call update_meshes_lists() before (in INIT script for example).

syntax

num_transparent_meshes = gh_model.get_num_transparent_meshes (
model_id
)

parameters

model_id ID model identifier

return values

num_transparent_meshes INTEGER number of transparent meshes

code sample

num_transparent_meshes = gh_model.get_num_transparent_meshes(model_id)

load_textures

Loads all textures associated with the model.
Once the model is loaded, you can load all textures using this function.

syntax

num_textures = gh_model.load_textures (
model_id,
texture_directory
)

parameters

model_id ID model identifier
texture_directory STRING specifies the textures directory

return values

num_textures INTEGER number of loaded textures

code sample

num_textures = gh_model.load_textures(model_id, "data/")

load_textures_from_zip

Loads all textures associated with the model from a zip file.
Once the model is loaded, you can load all textures using this function.

syntax

num_textures = gh_model.load_textures_from_zip (
model_id,
zip_filename,
texture_directory
)

parameters

model_id ID model identifier
zip_filename STRING absolute path of the zip file
texture_directory STRING specifies the textures directory

return values

num_textures INTEGER number of loaded textures

code sample

num_textures = gh_model.load_textures_from_zip(model_id, zip_filename, "data/")

render_opaque_meshes

Renders opaque meshes only.
Call update_meshes_lists() before (in INIT script for example).

syntax

gh_model.render_opaque_meshes (
model_id
)

parameters

model_id ID model identifier

return values

none

code sample

gh_model.render_opaque_meshes(model_id)

render_transparent_meshes

Renders transparent meshes only.
Call update_meshes_lists() once before.

syntax

gh_model.render_transparent_meshes (
model_id
)

parameters

model_id ID model identifier

return values

none

code sample

gh_model.render_transparent_meshes(model_id)

update_meshes_lists

Updates internal lists with opaque ans transparent meshes based on the opacity of the material.

syntax

gh_model.update_meshes_lists (
model_id,
opacity_threshold
)

parameters

model_id ID model identifier
opacity_threshold REAL values less than threshold define transparent surfaces

return values

none

code sample

opacity_threshold = 1.0
gh_model.update_meshes_lists(model_id, opacity_threshold)

gh_node

Node module

gh_node is the module that manages all kind of nodes in the scene.
Every object, gpu program, texture, material in the scene is derived from the node.
A scene can be seen as a tree of nodes.

add_child

Adds a child to a parent.

syntax

gh_node.add_child (
parent_id,
child_id
)

parameters

parent_id ID parent node identifier
child_id ID child node identifier

return values

none

code sample

gh_node.add_child(parent_id, child_id)

get_child_by_index

Returns the node identifier of a child.

syntax

child_id = gh_node.get_child_by_index (
node_id,
index
)

parameters

node_id ID node identifier
index INTEGER index of a children from 0 to gh_node.get_num_children()-1

return values

child_id ID child identifier

code sample

-- Gets the first child.
child = gh_node.get_child_by_index(node_id, 0)

get_children_render_state

Gets the children render state of a particular node.

syntax

state = gh_node.get_children_render_state (
node_id
)

parameters

node_id ID node identifier

return values

state INTEGER state: enabled (1) or disabled (0)

code sample

state = gh_node.get_children_render_state(node_id)

get_name

Sets the name of a node.

syntax

name = gh_node.get_name (
node_id
)

parameters

node_id ID node identifier

return values

name STRING Node name

code sample

name = gh_node.getname(node_id)

get_num_children

Gets the number of children of a particular node.

syntax

num_children = gh_node.get_num_children (
node_id
)

parameters

node_id ID node identifier

return values

num_children INTEGER number of children

code sample

num_children = gh_node.get_num_children(node_id)

getid

Gets the identifier of a node from its name.

syntax

node_id = gh_node.getid (
name
)

parameters

name STRING name of node

return values

node_id ID node identifier

code sample

node_id = gh_node.getid("PhongShader")

kill

Kills (cleanup and free resources) a node.

syntax

gh_node.kill (
node_id
)

parameters

node_id ID node identifier

return values

none

code sample

gh_node.kill(node_id)

remove_child

Removes a child from a parent.

syntax

gh_node.remove_child (
parent_id,
child_id
)

parameters

parent_id ID parent node identifier
child_id ID child node identifier

return values

none

code sample

gh_node.remove_child(parent_id, child_id)

set_children_render_state

Sets the children render state of a particular node.

syntax

gh_node.set_children_render_state (
node_id,
state,
children
)

parameters

node_id ID node identifier
state INTEGER state: enabled (1) or disabled (0)
children INTEGER apply this state to all children: yes (1) or no (0)

return values

none

code sample

gh_node.set_children_render_state(node_id, 0, 0)

set_name

Sets the name of a node.

syntax

gh_node.set_name (
node_id,
name
)

parameters

node_id ID node identifier
name STRING name of the node

return values

none

code sample

gh_node.setname(node_id, "myKoolNodeName")

gh_nvg private

NanoVG module

gh_nvg is the module that manages NanoVG functions.
NanoVG is a small library that allows to draw widgets.
Please look at the code samples in the /gl-32/nanovg/ folder of the code sample pack.

gh_object

Object module

gh_object is the module that manages all renderable nodes, in other terms the objects.
A mesh or a camera is an object while a texture is not an object (it's a resource).

add_material

Adds a material to a mesh.

syntax

gh_object.add_material (
mesh_id,
mat_id
)

parameters

mesh_id ID mesh identifier
mat_id ID material identifier

return values

none

code sample

gh_object.add_material(mesh_id, mat_id)

average_vertices_normal

lua

alias → lua

Average the normal vector of all vertices.

syntax

gh_object.average_vertices_normal (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.average_vertices_normal(mesh_id)

compute_faces_normal

Computes the normal vector of all faces.

syntax

gh_object.compute_faces_normal (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.compute_faces_normal(mesh_id)

compute_vertices_normal

lua

Computes the normal vector of all vertices.

syntax

gh_object.compute_vertices_normal (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.compute_vertices_normal(mesh_id)

copy_transform

Copies the local transformation from one object to another one.

syntax

gh_object.copy_transform (
dst_obj_id,
src_obj_id
)

parameters

dst_obj_id ID destination object identifier
src_obj_id ID source object identifier

return values

none

code sample

gh_object.copy_transform(dst, src)

create

Create a minimal object that can be rendered with a tripod (its local space).

syntax

object_id = gh_object.create()

parameters

none

return values

object_id ID object identifier

code sample

gizmo = gh_object.create()

flip_faces

Flip the faces of a triangular object (a mesh).

syntax

gh_object.flip_faces (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.flip_faces(mesh_id)

flip_vertex_normals

Flip the normals of all vertices.

syntax

gh_object.flip_vertex_normals (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.flip_vertex_normals(mesh_id)

get_absolute_orientation

Gets the quaternion that represents the absolute orientation of an object.

syntax

x, y, z, w = gh_object.get_absolute_orientation (
obj_id
)

parameters

obj_id ID object identifier

return values

x, y, z, w REAL absolute orientation quaternion

code sample

x, y, z, w = gh_object.get_absolute_orientation(obj_id)

get_absolute_orientation_euler_angles

Gets the absolute orientation of an object using the Euler's angles.

syntax

pitch, yaw, roll = gh_object.get_absolute_orientation_euler_angles (
obj_id
)

parameters

obj_id ID object identifier

return values

pitch, yaw, roll REAL Euler's angles

code sample

pitch, yaw, roll = gh_object.get_absolute_orientation_euler_angles(obj_id)

get_absolute_orientation_vector_z

Gets the Z axis of the absolute orientation of an object.

syntax

x,y,z = gh_object.get_absolute_orientation_vector_z (
obj_id
)

parameters

obj_id ID object identifier

return values

x,y,z REAL Z axis of the absolute orientation

code sample

x,y,z = gh_object.get_absolute_orientation_vector_z(obj_id)

get_absolute_orientation_vectors

Gets the 3 axis that describe the absolute orientation of an object.

syntax

x0,y0,z0,  x1,y1,z1,  x2,y2,z2 = gh_object.get_absolute_orientation_vectors (
obj_id
)

parameters

obj_id ID object identifier

return values

x0,y0,z0,  x1,y1,z1,  x2,y2,z2 REAL Axis of the absolute orientation

code sample

x0,y0,z0,  x1,y1,z1,  x2,y2,z2 = gh_object.get_absolute_orientation_vectors(obj_id)

get_absolute_position

Gets the absolute position of an object.

syntax

x, y, z = gh_object.get_absolute_position (
obj_id
)

parameters

obj_id ID object identifier

return values

x, y, z REAL 3D position

code sample

x, y, z = gh_object.get_absolute_position(obj_id)

get_distance

Returns the distance between two objects.

syntax

dist = gh_object.get_distance (
obj1_id,
obj2_id
)

parameters

obj1_id ID object 1 identifier
obj2_id ID object 2 identifier

return values

dist REAL distance

code sample

dist = gh_object.get_distance(object1_id, object2_id)

get_material

Gets a material from its index (0 ; get_num_materials()-1).

syntax

mat_id = gh_object.get_material (
mesh_id,
material_index
)

parameters

mesh_id ID mesh identifier
material_index INTEGER material index

return values

mat_id ID material identifier

code sample

mat_id = gh_object.get_material(mesh_id, 0)

get_num_faces

Gets the number of triangular faces of an object.

syntax

num_faces = gh_object.get_num_faces (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

num_faces INTEGER number of faces

code sample

num_faces = gh_object.get_num_faces(mesh_id)

get_num_faces_v2

Gets the number of triangular faces of an object and its whole hierarchy.

syntax

num_faces = gh_object.get_num_faces_v2 (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

num_faces INTEGER number of faces

code sample

num_faces = gh_object.get_num_faces_v2(mesh_id)

get_num_materials

Gets the number of materials of an object.

syntax

num_materials = gh_object.get_num_materials (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

num_materials INTEGER number of materials

code sample

num_materials = gh_object.get_num_materials(mesh_id)

get_num_vertices

Gets the number of vertices of an object.

syntax

num_vertices = gh_object.get_num_vertices (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

num_vertices INTEGER number of vertices

code sample

num_vertices = gh_object.get_num_vertices(mesh_id)

get_num_vertices_v2

Gets the number of vertices of an object and its whole hierarchy.

syntax

num_vertices = gh_object.get_num_vertices_v2 (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

num_vertices INTEGER number of vertices

code sample

num_vertices = gh_object.get_num_vertices_v2(mesh_id)

get_orientation

Gets the relative orientation quaternion of an object.

syntax

x, y, z, w = gh_object.get_orientation (
obj_id
)

parameters

obj_id ID object identifier

return values

x, y, z, w REAL absolute orientation quaternion

code sample

x, y, z, w = gh_object.get_orientation(obj_id)

get_orientation_euler_angles

Gets the relative orientation of an object using the Euler's angles.

syntax

pitch, yaw, roll = gh_object.get_orientation_euler_angles (
obj_id
)

parameters

obj_id ID object identifier

return values

pitch, yaw, roll REAL Euler's angles

code sample

pitch, yaw, roll = gh_object.get_orientation_euler_angles(obj_id)

get_orientation_vector_z

Gets the Z axis of the relative orientation of an object.

syntax

x,y,z = gh_object.get_orientation_vector_z (
obj_id
)

parameters

obj_id ID object identifier

return values

x,y,z REAL Z axis of the relative orientation

code sample

x,y,z = gh_object.get_orientation_vector_z(obj_id)

get_orientation_vectors

Gets the 3 axis that describe the relative orientation of an object.

syntax

x0,y0,z0,  x1,y1,z1,  x2,y2,z2 = gh_object.get_orientation_vectors (
obj_id
)

parameters

obj_id ID object identifier

return values

x0,y0,z0,  x1,y1,z1,  x2,y2,z2 REAL Axis of the relative orientation

code sample

x0,y0,z0,  x1,y1,z1,  x2,y2,z2 = gh_object.get_orientation_vectors(obj_id)

get_plane_equation

Gets the plane equation related to the object orientation.

syntax

a, b, c, d = gh_object.get_plane_equation (
obj_id
)

parameters

obj_id ID object identifier

return values

a, b, c, d REAL plane equation

code sample

a, b, c, d = gh_object.get_plane_equation(obj_id)

get_position

Gets the relative position of an object.

syntax

x, y, z = gh_object.get_position (
obj_id
)

parameters

obj_id ID object identifier

return values

x, y, z REAL 3D position

code sample

x, y, z = gh_object.get_position(obj_id)

get_transform

Gets the relative transformation matrix of an object.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_object.get_transform (
obj_id
)

parameters

obj_id ID object identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the transformation matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_object.get_transform(obj_id)

remove_all_materials

Removes all materials from an object.

syntax

gh_object.remove_all_materials (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.remove_all_materials(mesh_id)

remove_material

Removes a material from an object.

syntax

gh_object.remove_material (
mesh_id,
mat_id
)

parameters

mesh_id ID mesh identifier
mat_id ID material identifier

return values

none

code sample

gh_object.remove_material(mesh_id, mat_id)

render

Renders an object.

syntax

gh_object.render (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_camera.bind(cam_id)
gh_gpu_program.bind(gpuprog_id)

gh_object.render(mesh_id)

render_geometry

Renders only the object geometry.
Automatic uniforms are not updated and you have to call gh_object.update_automatic_uniforms() before calling render_geometry().

syntax

gh_object.render_geometry (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_texture.bind(tex_id, 0)

gh_object.update_automatic_uniforms(mesh_plane)

gh_object.render_geometry(mesh_plane)

render_geometry_draw

Draws the geometry.

syntax

gh_object.render_geometry_draw (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_texture.bind(tex_id, 0)

gh_object.update_automatic_uniforms(mesh_plane)

gh_object.render_geometry_prepare(mesh_plane)
gh_object.render_geometry_draw(mesh_plane)
gh_object.render_geometry_finish(mesh_plane)

render_geometry_finish

Finishes the geometry drawing.

syntax

gh_object.render_geometry_finish (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_texture.bind(tex_id, 0)

gh_object.update_automatic_uniforms(mesh_plane)

gh_object.render_geometry_prepare(mesh_plane)
gh_object.render_geometry_draw(mesh_plane)
gh_object.render_geometry_finish(mesh_plane)

render_geometry_prepare

Prepares the geometry drawing.

syntax

gh_object.render_geometry_prepare (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_texture.bind(tex_id, 0)

gh_object.update_automatic_uniforms(mesh_plane)

gh_object.render_geometry_prepare(mesh_plane)
gh_object.render_geometry_draw(mesh_plane)
gh_object.render_geometry_finish(mesh_plane)

rotate_vertices_position

Rotates the position of all vertices by a rotation quaternion.

syntax

gh_object.rotate_vertices_position (
mesh_id,
x, y, z, w
)

parameters

mesh_id ID mesh identifier
x, y, z, w REAL quaternion

return values

none

code sample

gh_object.rotate_vertices_position(mesh_id, x, y, z, w)

rotate_vertices_position_euler_xyz

Rotates the position of all vertices using Euler's angles.

syntax

gh_object.rotate_vertices_position_euler_xyz (
mesh_id,
pitch, yaw, roll
)

parameters

mesh_id ID mesh identifier
pitch, yaw, roll REAL Euler's angles

return values

none

code sample

gh_object.rotate_vertices_position_euler_xyz(mesh_id, pitch, yaw, roll)

scale_vertices_position

Scales the position of all vertices by a scaling vector.

syntax

gh_object.scale_vertices_position (
mesh_id,
x, y, z
)

parameters

mesh_id ID mesh identifier
x, y, z REAL scaling vector

return values

none

code sample

gh_object.scale_vertices_position(mesh_id, x, y, z)

set_absolute_transform_update_mode

Sets the transformation mode (or order) to build the absolute transformation matrix: 0 (parent * object) or 1 (object * parent).

syntax

gh_object.set_absolute_transform_update_mode (
obj_id,
transform_mode
)

parameters

obj_id ID object identifier
transform_mode ENUM( transform_mode ) order of internal transformation: default 0 (parent * object) or 1 (object * parent)

return values

none

code sample

-- transform_mode
parent_object = 0 -- default: parent * object
object_parent = 1 -- object * parent

mode = object_parent

gh_object.set_absolute_transform_update_mode(obj_id, mode)

set_automatic_uniform_state

Set the state (enabled or disabled) of automatic uniforms.
If state is 0, the automatic uniforms specified by the mask are no longer send to the current GPU program.

syntax

gh_object.set_automatic_uniform_state (
obj_id,
state,
uniform_type
)

parameters

obj_id ID object identifier
state BOOLEAN 1 (enabled) or 0 (disabled)
uniform_type STRING currently only 'camera'

return values

none

code sample

gh_object.set_automatic_uniform_state(obj_id, state, "camera")

set_euler_angles

Sets the relative orientation of an object using the Euler's angles.

syntax

gh_object.set_euler_angles (
obj_id,
pitch, yaw, roll
)

parameters

obj_id ID object identifier
pitch, yaw, roll REAL Euler's angles

return values

none

code sample

gh_object.set_euler_angles(obj_id, pitch, yaw, roll)

set_materials_texture_unit_offset

Specifies an offset to apply to material texture units.
Useful with shadow mapping for example.

syntax

gh_object.set_materials_texture_unit_offset (
mesh_id,
offset
)

parameters

mesh_id ID mesh identifier
offset INTEGER texture unit offset

return values

none

code sample

offset = 1
gh_object.set_materials_texture_unit_offset(mesh_id, offset)

set_orientation

Sets the relative orientation of an object using a quaternion.

syntax

gh_object.set_orientation (
obj_id,
x, y, z, w
)

parameters

obj_id ID object identifier
x, y, z, w REAL orientation quaternion

return values

none

code sample

q = {x=0, y=0, z=0, w=1}

gh_object.set_orientation(obj_id, q.x, q.y, q.z, q.w)

set_position

Sets the relative position of an object.

syntax

gh_object.set_position (
obj_id,
x, y, z
)

parameters

obj_id ID object identifier
x, y, z REAL 3D position

return values

none

code sample

gh_object.set_position(obj_id, x, y, z)

set_scale

Sets the relative scale of an object.

syntax

gh_object.set_scale (
obj_id,
x, y, z
)

parameters

obj_id ID object identifier
x, y, z REAL 3D scaling factors

return values

none

code sample

gh_object.set_scale(obj_id, x, y, z)

set_tessellation_state

Enables the rendering with hardware tessellation (OpenGL 4+).
A tessellation GPU program is also required.
This function works with meshes and models.

syntax

gh_object.set_tessellation_state (
mesh_id,
tessellation
)

parameters

mesh_id ID mesh identifier
tessellation BOOLEAN tessellation enabled: 1 (true) or 0 (false)

return values

none

code sample

gh_object.set_tessellation_state(mesh_id, 1)

set_transform

Sets the relative transformation matrix of an object.

syntax

gh_object.set_transform (
obj_id,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

obj_id ID object identifier
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the transformation matrix

return values

none

code sample

gh_object.set_transform(obj_id, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

set_transform_order

Sets the transformation order to build the internal transformation matrix.

syntax

gh_object.set_transform_order (
obj_id,
transform_order
)

parameters

obj_id ID object identifier
transform_order ENUM( transform_order ) order of internal transformation: default 0 (translation, rotation, scale), 1 (rotation, translation, scale), 2 and 3

return values

none

code sample

gh_object.set_transform_order(obj_id, 1)

set_vertices_color

Sets the color of all vertices.

syntax

gh_object.set_vertices_color (
mesh_id,
r, g, b, a
)

parameters

mesh_id ID mesh identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_object.set_vertices_color(mesh_id, r, g, b, a)

smooth_vertices_normal

lua

alias → lua

Average the normal vector of all vertices.

syntax

gh_object.smooth_vertices_normal (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_object.smooth_vertices_normal(mesh_id)

transform_update_scale

Handy function to update the scale of the relative transformation matrix.
Position is also updated.

syntax

gh_object.transform_update_scale (
obj_id,
x, y, z
)

parameters

obj_id ID object identifier
x, y, z REAL 3D scaling factors.

return values

none

code sample

gh_object.transform_update_scale(obj_id, x, y, z)

translate_vertices_position

Translates the position of all vertices by a translation vector.

syntax

gh_object.translate_vertices_position (
mesh_id,
x, y, z
)

parameters

mesh_id ID mesh identifier
x, y, z REAL translation vector

return values

none

code sample

gh_object.translate_vertices_position(mesh_id, x, y, z)

update_automatic_uniforms

Updates automatic uniforms that are sent to any GLSL program.
These uniforms include: gxl3d_ProjectionMatrix, gxl3d_ViewMatrix, gxl3d_ViewProjectionMatrix, gxl3d_ModelProjectionMatrix and gxl3d_Viewport.
This function can be used with render_geometry() and render_geometry_xxx() functions.

syntax

gh_object.update_automatic_uniforms (
mesh_id
)

parameters

mesh_id ID mesh identifier

return values

none

code sample

gh_gpu_program.bind(gpuprog_id)
gh_texture.bind(tex_id, 0)

gh_object.update_automatic_uniforms(mesh_id)

gh_object.render_geometry(mesh_id)

gh_opencl

OpenCL module

gh_opencl is the module that manages OpenCL functions.
Currently OpenCL functions only covers simple API queries.

get_device_compute_units_info

Returns the information about a the compute units of an OpenCL device.

syntax

max_compute_units, clock_freq, flops = gh_opencl.get_device_compute_units_info (
pla_index,
dev_index
)

parameters

pla_index INTEGER platform index
dev_index INTEGER device index

return values

max_compute_units, clock_freq, flops INTEGER max compute units, clock frequency in MHz, and FLOPS

code sample

max_compute_units, clock_freq, flops = gh_opencl.get_device_compute_units_info(0, 0)

get_device_info

Returns the identification information about an OpenCL device.

syntax

vendor, name, version, driver = gh_opencl.get_device_info (
pla_index,
dev_index
)

parameters

pla_index INTEGER platform index
dev_index INTEGER device index

return values

vendor, name, version, driver STRING vendor, name, version and driver of the OpenCL device

code sample

vendor, name, version = gh_opencl.get_device_info(0, 0)

get_device_type

Returns the type (GPU or CPU) of an OpenCL device.

syntax

type = gh_opencl.get_device_type (
pla_index,
dev_index
)

parameters

pla_index INTEGER platform index
dev_index INTEGER device index

return values

type ENUM( opencl_device_type ) type: 1 (GPU) or 2 (CPU)

code sample

type = gh_opencl.get_device_type(0, 0)

get_num_devices

Returns the number of OpenCL devices of a particular platform.

syntax

num_devices = gh_opencl.get_num_devices (
pla_index
)

parameters

pla_index INTEGER platform index

return values

num_devices INTEGER number of OpenCL devices

code sample

num_devices = gh_opencl.get_num_devices(0)

get_num_platforms

Returns the number of OpenCL platforms.

syntax

num_platforms = gh_opencl.get_num_platforms()

parameters

none

return values

num_platforms INTEGER number of OpenCL platforms

code sample

num_platforms = gh_opencl.get_num_platforms()

get_platform_info

Returns the main information about an OpenCL platform.

syntax

vendor, name, version = gh_opencl.get_platform_info (
pla_index
)

parameters

pla_index INTEGER platform index

return values

vendor, name, version STRING vendor, name and version of the OpenCL platform

code sample

vendor, name, version = gh_opencl.get_platform_info(0)

gh_physx3 windowslinuxmacos

NVIDIA PhysX 3 module

gh_physx3 is the module that manages NVIDIA PhysX 3 engine.
Thanks to gh_physx3, you will be able to create rigid bodies and do collisions, create particles and fluids, creates clothes and joints.

actor_add_force

Adds a force to an actor.

syntax

gh_physx3.actor_add_force (
actor_id,
fx, fy, fz
)

parameters

actor_id ID PhysX actor identifier
fx, fy, fz REAL force

return values

none

code sample

gh_physx3.actor_add_force(actor_id, fx, fy, fz)

actor_add_force_at_position

Adds a force to an actor at a particular position.

syntax

gh_physx3.actor_add_force_at_position (
actor_id,
fx, fy, fz,
px, py, pz
)

parameters

actor_id ID PhysX actor identifier
fx, fy, fz REAL force
px, py, pz REAL position

return values

none

code sample

gh_physx3.actor_add_force_at_position(actor_id, fx, fy, fz, px, py, pz)

actor_apply_transform

Applies the transformation (position + orientation) of an PhysX actor to a regular 3D object (a mesh for example).

syntax

gh_physx3.actor_apply_transform (
actor_id,
obj_id
)

parameters

actor_id ID PhysX actor identifier
obj_id ID object identifier

return values

none

code sample

gh_physx3.actor_apply_transform(actor_id, object)

actor_clear_forces

Clears (resets) all forces that act on an actor.

syntax

gh_physx3.actor_clear_forces (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_physx3.actor_clear_forces(actor_id)

actor_get_angular_speed2

Gets the squared angular speed of an actor.

syntax

s = gh_physx3.actor_get_angular_speed2 (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

s REAL squared speed

code sample

s = gh_physx3.actor_get_angular_speed2(actor_id)

actor_get_angular_velocity

Gets the angular velocity of an actor.

syntax

x, y, z = gh_physx3.actor_get_angular_velocity (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z = gh_physx3.actor_get_angular_velocity(actor_id)

actor_get_linear_speed2

Gets the squared linear speed of an actor.

syntax

s = gh_physx3.actor_get_linear_speed2 (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

s REAL squared speed

code sample

s = gh_physx3.actor_get_linear_speed2(actor_id)

actor_get_linear_velocity

Gets the linear velocity of an actor.

syntax

x, y, z = gh_physx3.actor_get_linear_velocity (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z = ggh_physx3.actor_get_linear_velocity(actor_id)

actor_get_orientation

Gets the orientation of an actor (a quaternion).

syntax

x, y, z, w = gh_physx3.actor_get_orientation (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z, w REAL orientation

code sample

x, y, z, w = gh_physx3.actor_get_orientation(actor_id)

actor_get_position

Gets the global position of an actor.

syntax

x, y, z = gh_physx3.actor_get_position (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z REAL position

code sample

x, y, z = gh_physx3.actor_get_position(actor_id)

actor_get_sleep_threshold

Gets the sleep threshold.

syntax

thres = gh_physx3.actor_get_sleep_threshold (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

thres REAL threshold

code sample

t = gh_physx3.actor_get_sleep_threshold(actor_id)

actor_get_transform_mat16

Returns the transformation matrix of a physics actor.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_physx3.actor_get_transform_mat16 (
actor_id
)

parameters

actor_id ID actor identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_physx3.actor_get_transform_mat16(actor_id)

actor_get_transform_pos_qrot

Returns the position and orientation (quaternion) of a physics actor.

syntax

px, py, pz, qx, qy, qz, qw = gh_physx3.actor_get_transform_pos_qrot (
actor_id
)

parameters

actor_id ID actor identifier

return values

px, py, pz REAL position
qx, qy, qz, qw REAL rotation quaternion

code sample

px, py, pz, qx, qy, qz, qw = gh_physx3.actor_get_transform_pos_qrot(actor_id)

actor_is_sleeping

Gets the sleeping state of an actor.

syntax

state = gh_physx3.actor_is_sleeping (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

state BOOLEAN state (0 or 1)

code sample

is_sleeping = gh_physx3.actor_is_sleeping(actor_id)

actor_kill

Destroys an actor.

syntax

gh_physx3.actor_kill (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_physx3.actor_kill(actor_id)

actor_put_to_sleep

Forces an actor to sleep.

syntax

gh_physx3.actor_put_to_sleep (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_physx3.actor_put_to_sleep(actor_id)

actor_set_3d_object

Allows to associate a physics actor and a 3D object.
Useful for the scene_sync_3d_objects() function.

syntax

gh_physx3.actor_set_3d_object (
actor_id,
o3d_id
)

parameters

actor_id ID PhysX actor identifier
o3d_id ID 3d object identifier

return values

none

code sample

gh_physx3.actor_set_3d_object(actor_id, oid)

actor_set_angular_damping

Sets the angular damping of an actor.

syntax

gh_physx3.actor_set_angular_damping (
actor_id,
damping
)

parameters

actor_id ID PhysX actor identifier
damping REAL damping

return values

none

code sample

gh_physx3.actor_set_angular_damping(actor_id, 0.2)

actor_set_angular_velocity

Sets the angular velocity of an actor.

syntax

gh_physx3.actor_set_angular_velocity (
actor_id,
vx, vy, vz
)

parameters

actor_id ID PhysX actor identifier
vx, vy, vz REAL 3D velocity vector

return values

none

code sample

gh_physx3.actor_set_angular_velocity(actor_id, 0.8, 12, 1.6)

actor_set_euler_angles

Sets the orientation of an actor using Euler's angles.

syntax

gh_physx3.actor_set_euler_angles (
actor_id,
pitch, yaw, roll
)

parameters

actor_id ID PhysX actor identifier
pitch, yaw, roll REAL Eurler's angles in degrees

return values

none

code sample

gh_physx3.actor_set_euler_angles(actor_id, 90, 0, 0)

actor_set_gravity_state

Sets the gravity state of an actor.

syntax

gh_physx3.actor_set_gravity_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_physx3.actor_set_gravity_state(actor_id, 1)

actor_set_kinematic_state

Sets the kinematic state of an actor.

syntax

gh_physx3.actor_set_kinematic_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_physx3.actor_set_kinematic_state(actor_id, 1)

actor_set_kinematic_target

Moves kinematically controlled dynamic actors through the 3d world.

syntax

gh_physx3.actor_set_kinematic_target (
actor_id,
px, py, pz,
pitch, yaw, roll
)

parameters

actor_id ID PhysX actor identifier
px, py, pz REAL destination position
pitch, yaw, roll REAL destination orientation

return values

none

code sample

gh_physx3.actor_set_kinematic_target(actor_id, px, py, pz, pitch, yaw, roll)

actor_set_linear_damping

Sets the linear damping of an actor.

syntax

gh_physx3.actor_set_linear_damping (
actor_id,
damping
)

parameters

actor_id ID PhysX actor identifier
damping REAL damping

return values

none

code sample

gh_physx3.actor_set_linear_damping(actor_id, 0.2)

actor_set_linear_velocity

Sets the linear velocity of an actor.

syntax

gh_physx3.actor_set_linear_velocity (
actor_id,
vx, vy, vz
)

parameters

actor_id ID PhysX actor identifier
vx, vy, vz REAL 3D velocity vector

return values

none

code sample

gh_physx3.actor_set_linear_velocity(actor_id, 10, 10, 10)

actor_set_material

Sets a material to an actor.

syntax

gh_physx3.actor_set_material (
actor_id,
mat_id
)

parameters

actor_id ID PhysX actor identifier
mat_id ID material identifier

return values

none

code sample

gh_physx3.actor_set_material(actor_id, mat_id)

actor_set_orientation

Sets the orientation of an actor (a quaternion).

syntax

gh_physx3.actor_set_orientation (
actor_id,
x, y, z, w
)

parameters

actor_id ID PhysX actor identifier
x, y, z, w REAL orientation quaternion

return values

none

code sample

gh_physx3.actor_set_orientation(actor_id, x, y, z, w)

actor_set_position

Sets the global position of an actor.

syntax

gh_physx3.actor_set_position (
actor_id,
x, y, z
)

parameters

actor_id ID PhysX actor identifier
x, y, z REAL position

return values

none

code sample

gh_physx3.actor_set_position(actor_id, x, y, z)

actor_set_sleep_threshold

Sets the sleep threshold.

syntax

gh_physx3.actor_set_sleep_threshold (
actor_id,
thres
)

parameters

actor_id ID PhysX actor identifier
thres REAL threshold

return values

none

code sample

gh_physx3.actor_set_sleep_threshold(actor_id, 0.2)

actor_set_solver_iterations

Sets the number of solver iterations for an actor.

syntax

gh_physx3.actor_set_solver_iterations (
actor_id,
position_iterations,
velocity_iterations
)

parameters

actor_id ID PhysX actor identifier
position_iterations INTEGER number of position iterations
velocity_iterations INTEGER number of velocity iterations

return values

none

code sample

position_iterations = 4
velocity_iterations = 1

gh_physx3.actor_set_solver_iterations(actor_id, position_iterations, velocity_iterations)

actor_update_mass

Update the mass of an actor from the density.

syntax

gh_physx3.actor_update_mass (
actor_id,
density
)

parameters

actor_id ID PhysX actor identifier
density REAL density

return values

none

code sample

gh_physx3.actor_update_mass(actor_id, density)

actor_wake_up

Wakes up an actor.

syntax

gh_physx3.actor_wake_up (
actor_id,
sleep_counter
)

parameters

actor_id ID PhysX actor identifier
sleep_counter REAL sleep counter

return values

none

code sample

gh_physx3.actor_wake_up(actor_id, 1)

check_results

Checks if results of a simulation step are available.

syntax

ret = gh_physx3.check_results (
scene_id
)

parameters

scene_id ID PhysX scene identifier

return values

ret BOOLEAN available: 1 (true) or 0 (false)

code sample

if (can_run_sim) then
    gh_physx3.run_simulation_step(scene_id, time_step)
    can_run_sim = false
end

if (gh_physx3.check_results(scene_id) == 1) then
    gh_physx3.fetch_results(scene_id)
    can_run_sim = true
end

cloth_create_from_mesh

Creates a PhysX cloth from a mesh.

syntax

actor_id = gh_physx3.cloth_create_from_mesh (
scene_id,
mesh_id,
gpu_cloth,
x, y, z,
pitch, yaw, roll,
gx, gy, gz
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
gpu_cloth BOOLEAN run on GPU: 1 (true) or 0 (false)
x, y, z REAL position
pitch, yaw, roll REAL Euler's angles
gx, gy, gz REAL gravity vector

return values

actor_id ID identifier of the cloth actor

code sample

actor_id = gh_physx3.cloth_create_from_mesh(scene_id, mesh_id, gpu_cloth, x, y, z, pitch. yaw, roll, gravity_x, gravity_y, gravity_z)

cloth_is_running_on_gpu

Gets the GPU state of a cloth actor.

syntax

state = gh_physx3.cloth_is_running_on_gpu (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

state BOOLEAN state (0 or 1)

code sample

state = gh_physx3.cloth_is_running_on_gpu(actor_id)

cloth_set_external_acceleration

Sets the external acceleration to a PhysX cloth actor.

syntax

gh_physx3.cloth_set_external_acceleration (
actor_id,
x, y, z
)

parameters

actor_id ID PhysX actor identifier
x, y, z REAL acceleration vector

return values

none

code sample

gh_physx3.cloth_set_external_acceleration(actor_id, x, y, z)

cloth_set_gpu_state

Sets the GPU state of a cloth actor.

syntax

gh_physx3.cloth_set_gpu_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_physx3.cloth_set_gpu_state(actor_id, state)

cloth_set_stiffness

Sets the cloth stiffness.

syntax

gh_physx3.cloth_set_stiffness (
actor_id,
stiffness
)

parameters

actor_id ID PhysX actor identifier
stiffness REAL stiffness

return values

none

code sample

gh_physx3.cloth_set_stiffness(actor_id, stiffness)

cloth_update_mesh_vertex_data

Updates a mesh data (positions + normals ) from a PhysX cloth actor.

syntax

gh_physx3.cloth_update_mesh_vertex_data (
actor_id,
mesh_id,
update_position,
update_normals
)

parameters

actor_id ID PhysX actor identifier
mesh_id ID mesh identifier
update_position BOOLEAN updates positions: 1 (true) or 0 (false)
update_normals BOOLEAN updates normals: 1 (true) or 0 (false)

return values

none

code sample

gh_physx3.cloth_update_mesh_vertex_data(actor_id, mesh_id, 1, 0)

cloth_update_particles_from_mesh_particles

Updates a PhysX cloth actor from a mesh.

syntax

gh_physx3.cloth_update_particles_from_mesh_particles (
actor_id,
mesh_id
)

parameters

actor_id ID PhysX actor identifier
mesh_id ID mesh identifier

return values

none

code sample

gh_physx3.cloth_update_particles_from_mesh_particles(actor_id, mesh_id)

create_actor_box

Creates a box actor.

syntax

actor_id = gh_physx3.create_actor_box (
scene_id,
w, h, d,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
w, h, d REAL width, height and depth
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_id_box = gh_physx3.create_actor_box(scene_id, 4, 4, 4, 0, 0, 0, density, mat_id)

create_actor_capsule

Creates a capsule actor.

syntax

actor_id = gh_physx3.create_actor_capsule (
scene_id,
radius,
half_height,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
radius REAL radius of the capsule (actually the cylinder)
half_height REAL half height of the cylinder
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_id_capsule = gh_physx3.create_actor_capsule(scene_id, radius, half_height, 0, 0, 0, density, mat_id)

create_actor_mesh

Creates an actor from a mesh.

syntax

actor_id = gh_physx3.create_actor_mesh (
scene_id,
mesh_id,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_id_mesh = gh_physx3.create_actor_mesh(scene_id, mesh_id, 0, 0, 0, density, mat_id)

create_actor_mesh_v2

Creates an actor from a mesh.
You can specify if the mesh is convex or not.
Only vertices of a convex mesh are used by PhysX.
To be GPU friendly, the number of vertices must not exceed 64.

syntax

actor_id = gh_physx3.create_actor_mesh_v2 (
scene_id,
mesh_id,
px, py, pz,
density,
mat_id,
convex
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
px, py, pz REAL position
density REAL density
mat_id ID material identifier
convex BOOLEAN convex state: 1 (yes) or 0 (no)

return values

actor_id ID PhysX actor identifier

code sample

convex = 1
actor_id_mesh = gh_physx3.create_actor_mesh_v2(scene_id, mesh_id, 0, 0, 0, density, mat_id, convex)

create_actor_plane

Creates a plane actor.

syntax

actor_id = gh_physx3.create_actor_plane (
scene_id,
nx, ny, nz, d,
mat_id
)

parameters

scene_id ID PhysX scene identifier
nx, ny, nz, d REAL plane equation
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_id_plane = gh_physx3.create_actor_plane(scene_id, 0, 1, 0, 0, mat_id)

create_actor_sphere

Creates a sphere actor.

syntax

actor_id = gh_physx3.create_actor_sphere (
scene_id,
radius,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
radius REAL radius
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_id_plane = gh_physx3.create_actor_sphere(scene_id, 10, 0, 0, 0, density, mat_id)

create_material

Creates a PhysX material.

syntax

mat_id = gh_physx3.create_material (
static_friction,
dynamic_friction,
resilience
)

parameters

static_friction REAL static friction
dynamic_friction REAL dynamic friction
resilience REAL resilience

return values

mat_id ID PhysX material identifier

code sample

mat_id = gh_physx3.create_material(0.5, 0.5, 0.5)

create_scene

Creates a PhysX scene - DEPRECATED

syntax

scene_id = gh_physx3.create_scene (
gpu_physx,
bounce_threshold_velocity
)

parameters

gpu_physx BOOLEAN 1 (GPU) or 0 (CPU)
bounce_threshold_velocity REAL bounce threshold velocity

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
scene_id = gh_physx3.create_scene(1, bounce_threshold_velocity)

create_scene_broadphase_gpu

Creates a GPU PhysX scene.

syntax

scene_id = gh_physx3.create_scene_broadphase_gpu (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_physx3.create_scene_broadphase_gpu(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_broadphase_mbp

Creates a CPU PhysX scene with MBP (Multi-Box Pruning) broadphase algorithm.

syntax

scene_id = gh_physx3.create_scene_broadphase_mbp (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization,
minX, minY, minZ,
maxX, maxY, maxZ
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)
minX, minY, minZ REAL world minimal dimension
maxX, maxY, maxZ REAL world maximal dimension

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

minX = -100
minY = 0
minZ = -100
maxX = 100,
maxY = 100
maxZ = 100

scene_id = gh_physx3.create_scene_broadphase_mbp(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization, minX, minY, minZ, maxX, maxY, maxZ)

create_scene_broadphase_sap

Creates a CPU PhysX scene with SAP (Multi-Box Pruning) broadphase algorithm.

syntax

scene_id = gh_physx3.create_scene_broadphase_sap (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_physx3.create_scene_broadphase_sap(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

fetch_results

Fetches the results of a simulation step.

syntax

ret = gh_physx3.fetch_results (
scene_id
)

parameters

scene_id ID PhysX scene identifier

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_physx3.run_simulation_step(scene_id, time_step)
gh_physx3.fetch_results(scene_id)

gpu_get_clock_frequency_khz

Gets the clock speed of the PhysX GPU.

syntax

clock = gh_physx3.gpu_get_clock_frequency_khz()

parameters

none

return values

clock INTEGER clock speed in kHz

code sample

clock = gh_physx3.gpu_get_clock_frequency_khz()

gpu_get_name

Gets the name of the PhysX GPU.

syntax

name = gh_physx3.gpu_get_name()

parameters

none

return values

name STRING name of the GPU

code sample

gpu_name = gh_physx3.gpu_get_name()

gpu_get_num_multiprocessors

Gets the number of SMs of the PhysX GPU.

syntax

num_sm = gh_physx3.gpu_get_num_multiprocessors()

parameters

none

return values

num_sm INTEGER number of SMs

code sample

gpu_sm = gh_physx3.gpu_get_num_multiprocessors()

gpu_get_total_memory_size_mb

Gets the size of the PhysX GPU memory.

syntax

size = gh_physx3.gpu_get_total_memory_size_mb()

parameters

none

return values

size INTEGER size of the memory in MB

code sample

size = gh_physx3.gpu_get_total_memory_size_mb()

gpu_is_supported

windows

Checks for PhysX GPU support (Windows only).

syntax

ret = gh_physx3.gpu_is_supported()

parameters

none

return values

ret BOOLEAN supported: 1 (true) or 0 (false)

code sample

gpu_physx = gh_physx3.gpu_is_supported()

joint_create

Creates a PhysX joint between two PhysX actors.

syntax

joint_id = gh_physx3.joint_create (
scene_id,
joint_type,
actor_id1,
x1, y1, z1,
pitch1, yaw1, roll1,
actor_id2,
x2, y2, z2,
pitch2, yaw2, roll2
)

parameters

scene_id ID PhysX scene identifier
joint_type ENUM( physx_joint_type ) type of joint: SPHERICAL (0), REVOLUTE (1), FIXED (2), DISTANCE (3), PRISMATIC (4), D6 (5 not implemented)
actor_id1 ID PhysX first actor identifier
x1, y1, z1 REAL position of the joint related to the first actor
pitch1, yaw1, roll1 REAL orientation of the joint related to the first actor
actor_id2 ID PhysX second actor identifier
x2, y2, z2 REAL position of the joint related to the second actor
pitch2, yaw2, roll2 REAL orientation of the joint related to the second actor

return values

joint_id ID PhysX joint identifier

code sample

joint_id = gh_physx3.joint_create(scene_id, joint_type, actor_id1, x1, y1, z1, pitch1, yaw1, roll1, actor_id2, x2, y2, z2, pitch2, yaw2, roll2)

joint_distance_set_distances

Sets distance joint distance range.

syntax

gh_physx3.joint_distance_set_distances (
joint_id,
min_distance, max_distance
)

parameters

joint_id ID PhysX joint identifier
min_distance, max_distance REAL min / max distance of the joint

return values

none

code sample

gh_physx3.joint_distance_set_distances(joint_id, min_distance, max_distance)

joint_distance_set_spring

Sets distance joint spring parameters.

syntax

gh_physx3.joint_distance_set_spring (
joint_id,
spring_coef, damping_coef
)

parameters

joint_id ID PhysX joint identifier
spring_coef, damping_coef REAL spring parameters

return values

none

code sample

gh_physx3.joint_distance_set_spring(joint_id, spring_coef, damping_coef)

joint_kill

Kills a PhysX joint.

syntax

gh_physx3.joint_kill (
joint_id
)

parameters

joint_id ID PhysX joint identifier

return values

none

code sample

gh_physx3.joint_kill(joint_id)

joint_prismatic_set_limits

Sets prismatic joint parameters.

syntax

gh_physx3.joint_prismatic_set_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver

return values

none

code sample

gh_physx3.joint_prismatic_set_limits(joint_id, lower_limit, upper_limit, limit_contact_distance)

joint_revolute_set_angular_limits

Sets revolute joint angular limits.

syntax

gh_physx3.joint_revolute_set_angular_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance,
damping,
stiffness,
restitution,
bounce_threshold
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver
damping REAL damping of the limit spring
stiffness REAL if greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit
restitution REAL controls the amount of bounce when the joint hits a limit
bounce_threshold REAL determines the minimum impact velocity which will cause the joint to bounce

return values

none

code sample

gh_physx3.joint_revolute_set_angular_limits(joint_id, lower_limit, upper_limit, limit_contact_distance, damping, stiffness, restitution, bounce_threshold)

joint_revolute_set_rotational_limits

Sets revolute joint parameters.

syntax

gh_physx3.joint_revolute_set_rotational_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver

return values

none

code sample

gh_physx3.joint_revolute_set_rotational_limits(joint_id, lower_limit, upper_limit, limit_contact_distance)

joint_set_break_force

Set the breaking force of a PhysX joint.

syntax

gh_physx3.joint_set_break_force (
joint_id,
force, torque
)

parameters

joint_id ID PhysX joint identifier
force, torque REAL force and torque

return values

none

code sample

gh_physx3.joint_set_break_force(joint_id, force, torque)

joint_set_motor_params

Sets motor parameters of a revolute joint.

syntax

gh_physx3.joint_set_motor_params (
joint_id,
velocity, max_force,
drive_enabled, free_spin_enabled
)

parameters

joint_id ID PhysX joint identifier
velocity, max_force REAL parameters
drive_enabled, free_spin_enabled BOOLEAN drive and free spin parameters: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_physx3.joint_set_motor_params(px_joint, velocity, max_force, drive_enabled, free_spin_enabled)

joint_spherical_set_limit_cone

Sets parameters of a spherical joint.

syntax

gh_physx3.joint_spherical_set_limit_cone (
joint_id,
y_limit_angle, z_limit_angle, limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
y_limit_angle, z_limit_angle, limit_contact_distance REAL parameters

return values

none

code sample

gh_physx3.joint_spherical_set_limit_cone(joint_id, y_limit_angle, z_limit_angle, limit_contact_distance)

kill_material

Destroys a material.

syntax

gh_physx3.kill_material (
mat_id
)

parameters

mat_id ID material identifier

return values

none

code sample

gh_physx3.kill_material(mat_id)

particle_system_create

Creates a particle system.
A PhysX particle system must run with a regular gxl3d particle system.

syntax

px_ps_id = gh_physx3.particle_system_create (
scene_id,
max_particles,
run_on_gpu,
init_particles
)

parameters

scene_id ID PhysX scene identifier
max_particles INTEGER max number of particles
run_on_gpu BOOLEAN 1 (GPU) or 0 (CPU)
init_particles BOOLEAN initializes particles positions: 1 (true) or 0 (false)

return values

px_ps_id ID PhysX particle system actor identifier

code sample

px_ps_id = gh_physx3.particle_system_create(scene_id, max_particles, run_on_gpu, 0)

particle_system_create_fluid

Creates a PhysX fluid (particle system).
A PhysX particle system must run with a regular gxl3d particle system.

syntax

px_ps_id = gh_physx3.particle_system_create_fluid (
scene_id,
max_particles,
particle_size,
viscosity,
stiffness,
run_on_gpu,
init_particles
)

parameters

scene_id ID PhysX scene identifier
max_particles INTEGER max number of particles
particle_size REAL size of a particle
viscosity REAL fluid viscosity
stiffness REAL fluid stiffness
run_on_gpu BOOLEAN 1 (GPU) or 0 (CPU)
init_particles BOOLEAN initializes particles positions: 1 (true) or 0 (false)

return values

px_ps_id ID PhysX particle system actor identifier

code sample

px_ps_id = gh_physx3.particle_system_create_fluid(scene_id, max_particles, particle_size, viscosity, stiffness, run_on_gpu, 0)

particle_system_from_gxc_ps

Updates a PhysX particle system from a gxc particle system (gxc is the core 3D lib used by GeeXLab).

syntax

gh_physx3.particle_system_from_gxc_ps (
px_ps_id,
gxc_ps_id
)

parameters

px_ps_id ID PhysX particle system actor identifier
gxc_ps_id ID gxc particle system identifier

return values

none

code sample

gh_physx3.particle_system_from_gxc_ps(px_ps_id, gxc_ps_id)

particle_system_position_from_vertex_pool

Updates the positions of a PhysX particle system from a gxl3d vertex pool.

syntax

gh_physx3.particle_system_position_from_vertex_pool (
px_ps_id,
vp_id
)

parameters

px_ps_id ID PhysX particle system actor identifier
vp_id ID vertex pool identifier

return values

none

code sample

gh_physx3.particle_system_position_from_vertex_pool(px_ps_id, vp_id)

particle_system_position_to_vertex_pool

Updates the positions of a gxl3d vertex pool from a PhysX particle system.

syntax

gh_physx3.particle_system_position_to_vertex_pool (
px_ps_id,
vp_id
)

parameters

px_ps_id ID PhysX particle system actor identifier
vp_id ID vertex pool identifier

return values

none

code sample

gh_physx3.particle_system_position_to_vertex_pool(px_ps_id, vp_id)

particle_system_to_gxc_ps

Updates a gxc particle system from a PhysX particle system (gxc is the core 3D lib used by GeeXLab).

syntax

gh_physx3.particle_system_to_gxc_ps (
px_ps_id,
gxc_ps_id
)

parameters

px_ps_id ID PhysX particle system actor identifier
gxc_ps_id ID gxc particle system identifier

return values

none

code sample

gh_physx3.particle_system_to_gxc_ps(px_ps_id, gxc_ps_id)

run_simulation

Runs a simulation.

syntax

ret = gh_physx3.run_simulation (
scene_id,
dt,
time_step
)

parameters

scene_id ID PhysX scene identifier
dt REAL detla time
time_step REAL simulation time step

return values

ret BOOLEAN simulation done: 1 (true) or 0 (false)

code sample

ret = gh_physx3.run_simulation(scene_id, dt, time_step)

run_simulation_step

Runs a simulation step.

syntax

ret = gh_physx3.run_simulation_step (
scene_id,
time_step
)

parameters

scene_id ID PhysX scene identifier
time_step REAL simulation time step

return values

ret BOOLEAN simulation: 1 (started) or 0 (error)

code sample

ret = gh_physx3.run_simulation_step(scene_id, time_step)

scene_sync_3d_objects

Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.

syntax

gh_physx3.scene_sync_3d_objects (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_physx3.scene_sync_3d_objects(sid)

set_max_depenetration_velocity

Sets the max depenetration velocity.
This a global value applied to each new actor.

syntax

gh_physx3.set_max_depenetration_velocity (
velocity
)

parameters

velocity REAL depenetration velocity

return values

none

code sample

velocity = 3.0

gh_physx3.set_max_depenetration_velocity(velocity)
...
actor_id_box = gh_physx3.create_actor_box(scene_id, 4, 4, 4, 0, 0, 0, density, mat_id)

set_scene_gravity

Sets the scene gravity vector.

syntax

gh_physx3.set_scene_gravity (
scene_id,
x, y, z
)

parameters

scene_id ID PhysX scene identifier
x, y, z REAL gravity vector

return values

none

code sample

gh_physx3.set_scene_gravity(scene_id, 0, -9.81, 0)

set_simulation_scales

Sets the various scales to get realistic physics simulations (to avoid the famous Moon effect).

syntax

gh_physx3.set_simulation_scales (
size,
mass,
speed
)

parameters

size REAL the approximate size of objects in the simulation (default: 1.0)
mass REAL the approximate mass of a size * size * size block (default: 1000)
speed REAL the approximate velocities of objects in simulation (default: 10)

return values

none

code sample

gh_physx3.set_simulation_scales(1, 1000, 10)

set_solver_iteration_counts

Sets the number of solver iterations.
This a global value applied to each new actor.

syntax

gh_physx3.set_solver_iteration_counts (
position_iterations,
velocity_iterations
)

parameters

position_iterations INTEGER number of position iterations
velocity_iterations INTEGER number of velocity iterations

return values

none

code sample

position_iterations = 4
velocity_iterations = 1

gh_physx3.set_solver_iteration_counts(position_iterations, velocity_iterations)
...
actor_id_box = gh_physx3.create_actor_box(scene_id, 4, 4, 4, 0, 0, 0, density, mat_id)

start

Starts the PhysX engine.

syntax

ret = gh_physx3.start()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_physx3.start()

stop

Stops the PhysX engine.

syntax

ret = gh_physx3.stop()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_physx3.stop()

update_material

Updates the properties of a material.

syntax

gh_physx3.update_material (
mat_id,
static_friction,
dynamic_friction,
resilience
)

parameters

mat_id ID material identifier
static_friction REAL static friction
dynamic_friction REAL dynamic friction
resilience REAL resilience / restitution

return values

none

code sample

static_friction = 0.5
dynamic_friction = 0.5
resilience = 0.9

gh_physx3.update_material(mat_id, static_friction, dynamic_friction, resilience)

gh_physx4 windowslinuxmacos

NVIDIA PhysX 4 module

gh_physx4 is the module that manages NVIDIA PhysX 4 engine.
Thanks to gh_physx4, you will be able to play with rigid body collisions, and handling joints.
Clothes and particles are no longer part of PhysX 4.

actor_add_force

Adds a force to an actor.

syntax

gh_physx4.actor_add_force (
actor_id,
fx, fy, fz
)

parameters

actor_id ID PhysX actor identifier
fx, fy, fz REAL force

return values

none

code sample

gh_physx4.actor_add_force(actor_id, fx, fy, fz)

actor_add_force_at_position

Adds a force to an actor at a particular position.

syntax

gh_physx4.actor_add_force_at_position (
actor_id,
fx, fy, fz,
px, py, pz
)

parameters

actor_id ID PhysX actor identifier
fx, fy, fz REAL force
px, py, pz REAL position

return values

none

code sample

gh_physx4.actor_add_force_at_position(actor_id, fx, fy, fz, px, py, pz)

actor_apply_transform

Applies the transformation (position + orientation) of an PhysX actor to a regular 3D object (a mesh for example).

syntax

gh_physx4.actor_apply_transform (
actor_id,
obj_id
)

parameters

actor_id ID PhysX actor identifier
obj_id ID object identifier

return values

none

code sample

gh_physx4.actor_apply_transform(actor_id, obj_id)

actor_clear_forces

Clears (resets) all forces that act on an actor.

syntax

gh_physx4.actor_clear_forces (
actor_id
)

parameters

actor_id ID actor identifier

return values

none

code sample

gh_physx4.actor_clear_forces(actor_id)

actor_get_angular_speed2

Gets the squared angular speed of an actor.

syntax

s = gh_physx4.actor_get_angular_speed2 (
actor_id
)

parameters

actor_id ID actor identifier

return values

s REAL squared speed

code sample

s = gh_physx4.actor_get_angular_speed2(actor_id)

actor_get_angular_velocity

Gets the angular velocity of an actor.

syntax

x, y, z = gh_physx4.actor_get_angular_velocity (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z = gh_physx4.actor_get_angular_velocity(actor_id)

actor_get_linear_speed2

Gets the squared linear speed of an actor.

syntax

speed = gh_physx4.actor_get_linear_speed2 (
actor_id
)

parameters

actor_id ID actor identifier

return values

speed REAL squared speed

code sample

speed = gh_physx4.actor_get_linear_speed2(actor_id)

actor_get_linear_velocity

Gets the linear velocity of an actor.

syntax

x, y, z = gh_physx4.actor_get_linear_velocity (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z = ggh_physx4.actor_get_linear_velocity(actor_id)

actor_get_orientation

Gets the orientation of an actor (a quaternion).

syntax

x, y, z, w = gh_physx4.actor_get_orientation (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z, w REAL orientation

code sample

x, y, z, w = gh_physx4.actor_get_orientation(actor_id)

actor_get_position

Gets the global position of an actor.

syntax

x, y, z = gh_physx4.actor_get_position (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z REAL position

code sample

x, y, z = gh_physx4.actor_get_position(actor_id)

actor_get_sleep_threshold

Gets the sleep threshold.

syntax

thres = gh_physx4.actor_get_sleep_threshold (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

thres REAL threshold

code sample

thres = gh_physx4.actor_get_sleep_threshold(actor_id)

actor_get_transform_mat16

Returns the transformation matrix of a physics actor.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_physx4.actor_get_transform_mat16 (
actor_id
)

parameters

actor_id ID actor identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_physx4.actor_get_transform_mat16(actor_id)

actor_get_transform_pos_qrot

Returns the position and orientation (quaternion) of a physics actor.

syntax

px, py, pz, qx, qy, qz, qw = gh_physx4.actor_get_transform_pos_qrot (
actor_id
)

parameters

actor_id ID actor identifier

return values

px, py, pz REAL position
qx, qy, qz, qw REAL rotation quaternion

code sample

px, py, pz, qx, qy, qz, qw = gh_physx4.actor_get_transform_pos_qrot(actor_id)

actor_is_sleeping

Gets the sleeping state of an actor.

syntax

state = gh_physx4.actor_is_sleeping (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

state BOOLEAN state (0 or 1)

code sample

is_sleeping = gh_physx4.actor_is_sleeping(actor_id)

actor_kill

Destroys an actor.

syntax

gh_physx4.actor_kill (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_physx4.actor_kill(actor_id)

actor_put_to_sleep

Forces an actor to sleep.

syntax

gh_physx4.actor_put_to_sleep (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_physx4.actor_put_to_sleep(actor_id)

actor_set_3d_object

Allows to associate a physics actor and a 3D object.
Useful for the scene_sync_3d_objects() function.

syntax

gh_physx4.actor_set_3d_object (
actor_id,
o3d_id
)

parameters

actor_id ID actor identifier
o3d_id ID 3d object identifier

return values

none

code sample

gh_physx4.actor_set_3d_object(actor_id, o3d_id)

actor_set_angular_damping

Sets the angular damping of an actor.

syntax

gh_physx4.actor_set_angular_damping (
actor_id,
damping
)

parameters

actor_id ID PhysX actor identifier
damping REAL damping

return values

none

code sample

gh_physx4.actor_set_angular_damping(actor_id, 0.2)

actor_set_angular_velocity

Sets the angular velocity of an actor.

syntax

gh_physx4.actor_set_angular_velocity (
actor_id,
vx, vy, vz
)

parameters

actor_id ID PhysX actor identifier
vx, vy, vz REAL 3D velocity vector

return values

none

code sample

gh_physx4.actor_set_angular_velocity(actor_id, 0.8, 12, 1.6)

actor_set_euler_angles

Sets the orientation of an actor using Euler's angles.

syntax

gh_physx4.actor_set_euler_angles (
actor_id,
pitch, yaw, roll
)

parameters

actor_id ID PhysX actor identifier
pitch, yaw, roll REAL Eurler's angles in degrees

return values

none

code sample

gh_physx4.actor_set_euler_angles(actor_id, 90, 0, 0)

actor_set_gravity_state

Sets the gravity state of an actor.

syntax

gh_physx4.actor_set_gravity_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_physx4.actor_set_gravity_state(actor_id, 1)

actor_set_kinematic_state

Sets the kinematic state of an actor.

syntax

gh_physx4.actor_set_kinematic_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_physx4.actor_set_kinematic_state(actor_id, 1)

actor_set_kinematic_target

Moves kinematically controlled dynamic actors through the 3d world.

syntax

gh_physx4.actor_set_kinematic_target (
actor_id,
px, py, pz,
pitch, yaw, roll
)

parameters

actor_id ID PhysX actor identifier
px, py, pz REAL destination position
pitch, yaw, roll REAL destination orientation

return values

none

code sample

gh_physx4.actor_set_kinematic_target(actor_id, px, py, pz, pitch, yaw, roll)

actor_set_linear_damping

Sets the linear damping of an actor.

syntax

gh_physx4.actor_set_linear_damping (
actor_id,
damping
)

parameters

actor_id ID PhysX actor identifier
damping REAL damping

return values

none

code sample

gh_physx4.actor_set_linear_damping(actor_id, 0.2)

actor_set_linear_velocity

Sets the linear velocity of an actor.

syntax

gh_physx4.actor_set_linear_velocity (
actor_id,
vx, vy, vz
)

parameters

actor_id ID PhysX actor identifier
vx, vy, vz REAL 3D velocity vector

return values

none

code sample

gh_physx4.actor_set_linear_velocity(actor_id, 10, 10, 10)

actor_set_material

Sets a material to an actor.

syntax

gh_physx4.actor_set_material (
actor_id,
mat_id
)

parameters

actor_id ID actor identifier
mat_id ID material identifier

return values

none

code sample

gh_physx4.actor_set_material(actor_id, mat_id)

actor_set_orientation

Sets the orientation of an actor (a quaternion).

syntax

gh_physx4.actor_set_orientation (
actor_id,
x, y, z, w
)

parameters

actor_id ID PhysX actor identifier
x, y, z, w REAL orientation quaternion

return values

none

code sample

gh_physx4.actor_set_orientation(actor_id, x, y, z, w)

actor_set_position

Sets the global position of an actor.

syntax

gh_physx4.actor_set_position (
actor_id,
x, y, z
)

parameters

actor_id ID PhysX actor identifier
x, y, z REAL position

return values

none

code sample

gh_physx4.actor_set_position(actor_id, x, y, z)

actor_set_sleep_threshold

Sets the sleep threshold.

syntax

gh_physx4.actor_set_sleep_threshold (
actor_id,
thres
)

parameters

actor_id ID PhysX actor identifier
thres REAL threshold

return values

none

code sample

gh_physx4.actor_set_sleep_threshold(actor_id, 0.2)

actor_set_solver_iterations

Sets the number of solver iterations for an actor.

syntax

gh_physx4.actor_set_solver_iterations (
actor_id,
position_iterations,
velocity_iterations
)

parameters

actor_id ID PhysX actor identifier
position_iterations INTEGER number of position iterations
velocity_iterations INTEGER number of velocity iterations

return values

none

code sample

position_iterations = 4
velocity_iterations = 1

gh_physx4.actor_set_solver_iterations(actor_id, position_iterations, velocity_iterations)

actor_update_mass

Update the mass of an actor from the density.

syntax

gh_physx4.actor_update_mass (
actor_id,
density
)

parameters

actor_id ID actor identifier
density REAL density

return values

none

code sample

gh_physx4.actor_update_mass(actor_id, density)

actor_wake_up

Wakes up an actor.

syntax

gh_physx4.actor_wake_up (
actor_id,
sleep_counter
)

parameters

actor_id ID PhysX actor identifier
sleep_counter REAL sleep counter

return values

none

code sample

gh_physx4.actor_wake_up(actor_id, 1)

check_results

Checks if results of a simulation step are available.

syntax

ret = gh_physx4.check_results (
scene_id
)

parameters

scene_id ID PhysX scene identifier

return values

ret BOOLEAN available: 1 (true) or 0 (false)

code sample

if (can_run_sim) then
    gh_physx4.run_simulation_step(scene_id, time_step)
    can_run_sim = false
end

if (gh_physx4.check_results(scene_id) == 1) then
    gh_physx4.fetch_results(scene_id)
    can_run_sim = true
end

create_actor_box

Creates a box actor.

syntax

actor_id = gh_physx4.create_actor_box (
scene_id,
w, h, d,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
w, h, d REAL width, height and depth
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_box = gh_physx4.create_actor_box(scene_id, 4, 4, 4, 0, 0, 0, density, mat_id)

create_actor_capsule

Creates a capsule actor.

syntax

actor_id = gh_physx4.create_actor_capsule (
scene_id,
radius,
half_height,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
radius REAL radius of the capsule (actually the cylinder)
half_height REAL half height of the cylinder
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_capsule = gh_physx4.create_actor_capsule(scene_id, radius, half_height, 0, 0, 0, density, mat_id)

create_actor_mesh

Creates an actor from a mesh.

syntax

actor_id = gh_physx4.create_actor_mesh (
scene_id,
mesh_id,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_mesh = gh_physx4.create_actor_mesh(scene_id, mesh_id, 0, 0, 0, density, mat_id)

create_actor_mesh_v2

Creates an actor from a mesh.
You can specify if the mesh is convex or not.
Only vertices of a convex mesh are used by PhysX.
To be GPU friendly, the number of vertices must not exceed 64.

syntax

actor_id = gh_physx4.create_actor_mesh_v2 (
scene_id,
mesh_id,
px, py, pz,
density,
mat_id,
convex
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
px, py, pz REAL position
density REAL density
mat_id ID material identifier
convex BOOLEAN convex state: 1 (yes) or 0 (no)

return values

actor_id ID PhysX actor identifier

code sample

convex = 1
actor_mesh = gh_physx4.create_actor_mesh_v2(scene_id, mesh_id, 0, 0, 0, density, mat_id, convex)

create_actor_plane

Creates a plane actor.

syntax

actor_id = gh_physx4.create_actor_plane (
scene_id,
nx, ny, nz, d,
mat_id
)

parameters

scene_id ID PhysX scene identifier
nx, ny, nz, d REAL plane equation
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_plane = gh_physx4.create_actor_plane(scene_id, 0, 1, 0, 0, mat_id)

create_actor_sphere

Creates a sphere actor.

syntax

actor_id = gh_physx4.create_actor_sphere (
scene_id,
radius,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
radius REAL radius
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_sphere = gh_physx4.create_actor_sphere(scene_id, 10, 0, 0, 0, density, mat_id)

create_material

Creates a PhysX material.

syntax

mat_id = gh_physx4.create_material (
static_friction,
dynamic_friction,
resilience
)

parameters

static_friction REAL static friction
dynamic_friction REAL dynamic friction
resilience REAL resilience

return values

mat_id ID PhysX material identifier

code sample

mat_id = gh_physx4.create_material(0.5, 0.5, 0.5)

create_scene

Creates a PhysX scene - DEPRECATED

syntax

scene_id = gh_physx4.create_scene (
gpu_physx,
bounce_threshold_velocity
)

parameters

gpu_physx BOOLEAN 1 (GPU) or 0 (CPU)
bounce_threshold_velocity REAL bounce threshold velocity

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2

scene_id = gh_physx4.create_scene(1, bounce_threshold_velocity)

create_scene_broadphase_abp

Creates a CPU PhysX scene with ABP (revisited implementation of MBP, new in PhysX 4) broadphase algorithm.

syntax

scene_id = gh_physx4.create_scene_broadphase_abp (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_physx4.create_scene_broadphase_abp(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_broadphase_gpu

Creates a GPU PhysX scene.

syntax

scene_id = gh_physx4.create_scene_broadphase_gpu (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_physx4.create_scene_broadphase_gpu(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_broadphase_mbp

Creates a CPU PhysX scene with MBP (Multi-Box Pruning) broadphase algorithm.

syntax

scene_id = gh_physx4.create_scene_broadphase_mbp (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization,
minX, minY, minZ,
maxX, maxY, maxZ
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)
minX, minY, minZ REAL world minimal dimension
maxX, maxY, maxZ REAL world maximal dimension

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

minX = -100
minY = 0
minZ = -100
maxX = 100,
maxY = 100
maxZ = 100

scene_id = gh_physx4.create_scene_broadphase_mbp(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization, minX, minY, minZ, maxX, maxY, maxZ)

create_scene_broadphase_sap

Creates a CPU PhysX scene with SAP (Multi-Box Pruning) broadphase algorithm.

syntax

scene_id = gh_physx4.create_scene_broadphase_sap (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_physx4.create_scene_broadphase_sap(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_set_solver_type

Set the solver that will be used to create a PhysX scene.Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.
Compared to scene_sync_3d_objects(), this function synchronizes only PhysX active actors (actors that have been updated by the PhysX engine).
If used, create_scene_set_solver_type() must be called before any scene creation function.

syntax

gh_physx4.create_scene_set_solver_type (
solver_type
)

parameters

solver_type ENUM( physx_solver_type ) solver type

return values

none

code sample

gh_physx4.create_scene_set_solver_type(solver_type)

fetch_results

Fetches the results of a simulation step.

syntax

ret = gh_physx4.fetch_results (
scene_id
)

parameters

scene_id ID PhysX scene identifier

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_physx4.run_simulation_step(scene_id, time_step)

ret = gh_physx4.fetch_results(scene_id)

gpu_get_clock_frequency_khz

Gets the clock speed of the PhysX GPU.

syntax

clock = gh_physx4.gpu_get_clock_frequency_khz()

parameters

none

return values

clock INTEGER clock speed in kHz

code sample

clock = gh_physx4.gpu_get_clock_frequency_khz()

gpu_get_name

Gets the name of the PhysX GPU.

syntax

name = gh_physx4.gpu_get_name()

parameters

none

return values

name STRING name of the GPU

code sample

gpu_name = gh_physx4.gpu_get_name()

gpu_get_num_multiprocessors

Gets the number of SMs of the PhysX GPU.

syntax

num_sm = gh_physx4.gpu_get_num_multiprocessors()

parameters

none

return values

num_sm INTEGER number of SMs

code sample

gpu_sm = gh_physx4.gpu_get_num_multiprocessors()

gpu_get_total_memory_size_mb

Gets the size of the PhysX GPU memory.

syntax

size = gh_physx4.gpu_get_total_memory_size_mb()

parameters

none

return values

size INTEGER size of the memory in MB

code sample

size = gh_physx4.gpu_get_total_memory_size_mb()

gpu_is_supported

windows

Checks for PhysX GPU support (Windows only).

syntax

ret = gh_physx4.gpu_is_supported()

parameters

none

return values

ret BOOLEAN supported: 1 (true) or 0 (false)

code sample

gpu_physx = gh_physx4.gpu_is_supported()

joint_create

Creates a PhysX joint between two PhysX actors.

syntax

joint_id = gh_physx4.joint_create (
scene_id,
joint_type,
actor1_id,
x1, y1, z1,
pitch1, yaw1, roll1,
actor2_id,
x2, y2, z2,
pitch2, yaw2, roll2
)

parameters

scene_id ID PhysX scene identifier
joint_type ENUM( physx_joint_type ) type of joint: SPHERICAL (0), REVOLUTE (1), FIXED (2), DISTANCE (3), PRISMATIC (4), D6 (5 not implemented)
actor1_id ID PhysX first actor identifier
x1, y1, z1 REAL position of the joint related to the first actor
pitch1, yaw1, roll1 REAL orientation of the joint related to the first actor
actor2_id ID PhysX second actor identifier
x2, y2, z2 REAL position of the joint related to the second actor
pitch2, yaw2, roll2 REAL orientation of the joint related to the second actor

return values

joint_id ID PhysX joint identifier

code sample

joint_id = gh_physx4.joint_create(scene_id, joint_type, actor1, x1, y1, z1, pitch1, yaw1, roll1, actor2, x2, y2, z2, pitch2, yaw2, roll2)

joint_distance_set_distances

Sets distance joint distance range.

syntax

gh_physx4.joint_distance_set_distances (
joint_id,
min_distance, max_distance
)

parameters

joint_id ID PhysX joint identifier
min_distance, max_distance REAL min / max distance of the joint

return values

none

code sample

gh_physx4.joint_distance_set_distances(joint_id, min_distance, max_distance)

joint_distance_set_spring

Sets distance joint spring parameters.

syntax

gh_physx4.joint_distance_set_spring (
joint_id,
spring_coef, damping_coef
)

parameters

joint_id ID PhysX joint identifier
spring_coef, damping_coef REAL spring parameters

return values

none

code sample

gh_physx4.joint_distance_set_spring(joint_id, spring_coef, damping_coef)

joint_kill

Kills a PhysX joint.

syntax

gh_physx4.joint_kill (
joint_id
)

parameters

joint_id ID PhysX joint identifier

return values

none

code sample

gh_physx4.joint_kill(joint_id)

joint_prismatic_set_limits

Sets prismatic joint parameters.

syntax

gh_physx4.joint_prismatic_set_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver

return values

none

code sample

gh_physx4.joint_prismatic_set_limits(joint_id, lower_limit, upper_limit, limit_contact_distance)

joint_revolute_set_angular_limits

Sets revolute joint angular limits.

syntax

gh_physx4.joint_revolute_set_angular_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance,
damping,
stiffness,
restitution,
bounce_threshold
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver
damping REAL damping of the limit spring
stiffness REAL if greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit
restitution REAL controls the amount of bounce when the joint hits a limit
bounce_threshold REAL determines the minimum impact velocity which will cause the joint to bounce

return values

none

code sample

gh_physx4.joint_revolute_set_angular_limits(joint_id, lower_limit, upper_limit, limit_contact_distance, damping, stiffness, restitution, bounce_threshold)

joint_revolute_set_rotational_limits

Sets revolute joint parameters.

syntax

gh_physx4.joint_revolute_set_rotational_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver

return values

none

code sample

gh_physx4.joint_revolute_set_rotational_limits(joint_id, lower_limit, upper_limit, limit_contact_distance)

joint_set_break_force

Set the breaking force of a PhysX joint.

syntax

gh_physx4.joint_set_break_force (
joint_id,
force, torque
)

parameters

joint_id ID PhysX joint identifier
force, torque REAL force and torque

return values

none

code sample

gh_physx4.joint_set_break_force(joint_id, force, torque)

joint_set_motor_params

Sets motor parameters of a revolute joint.

syntax

gh_physx4.joint_set_motor_params (
joint_id,
velocity, max_force,
drive_enabled, free_spin_enabled
)

parameters

joint_id ID PhysX joint identifier
velocity, max_force REAL parameters
drive_enabled, free_spin_enabled BOOLEAN drive and free spin parameters: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_physx4.joint_set_motor_params(joint_id, velocity, max_force, drive_enabled, free_spin_enabled)

joint_spherical_set_limit_cone

Sets parameters of a spherical joint.

syntax

gh_physx4.joint_spherical_set_limit_cone (
joint_id,
y_limit_angle, z_limit_angle, limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
y_limit_angle, z_limit_angle, limit_contact_distance REAL parameters

return values

none

code sample

gh_physx4.joint_spherical_set_limit_cone(joint_id, y_limit_angle, z_limit_angle, limit_contact_distance)

kill_material

Destroys a material.

syntax

gh_physx4.kill_material (
mat_id
)

parameters

mat_id ID material identifier

return values

none

code sample

gh_physx4.kill_material(mat_id)

run_simulation

Runs a complete simulation (step + fetch).

syntax

ret = gh_physx4.run_simulation (
scene_id,
dt,
time_step
)

parameters

scene_id ID PhysX scene identifier
dt REAL detla time
time_step REAL simulation time step

return values

ret BOOLEAN simulation done: 1 (true) or 0 (false)

code sample

ret = gh_physx4.run_simulation(scene_id, dt, time_step)

run_simulation_step

Runs a simulation step.

syntax

ret = gh_physx4.run_simulation_step (
scene_id,
time_step
)

parameters

scene_id ID PhysX scene identifier
time_step REAL simulation time step

return values

ret BOOLEAN simulation: 1 (started) or 0 (error)

code sample

ret = gh_physx4.run_simulation_step(scene_id, time_step)

scene_get_num_active_actors

Get the number of active PhysX actors.

syntax

n = gh_physx4.scene_get_num_active_actors (
scene_id
)

parameters

scene_id ID scene identifier

return values

n INTEGER number of active actors

code sample

n = gh_physx4.scene_get_num_active_actors(scene_id)

scene_sync_3d_objects

Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.

syntax

gh_physx4.scene_sync_3d_objects (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_physx4.scene_sync_3d_objects(scene_id)

scene_sync_3d_objects_v2

Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.
Compared to scene_sync_3d_objects(), this function synchronizes only PhysX active actors (actors that have been updated by the PhysX engine).

syntax

gh_physx4.scene_sync_3d_objects_v2 (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_physx4.scene_sync_3d_objects_v2(scene_id)

set_max_depenetration_velocity

Sets the max depenetration velocity.
This a global value applied to each new actor.

syntax

gh_physx4.set_max_depenetration_velocity (
velocity
)

parameters

velocity REAL depenetration velocity

return values

none

code sample

velocity = 3.0

gh_physx4.set_max_depenetration_velocity(velocity)
...
actor_box = gh_physx4.create_actor_box(scene, 4, 4, 4, 0, 0, 0, density, mat_id)

set_scene_gravity

Sets the scene gravity vector.

syntax

gh_physx4.set_scene_gravity (
scene_id,
x, y, z
)

parameters

scene_id ID PhysX scene identifier
x, y, z REAL gravity vector

return values

none

code sample

gh_physx4.set_scene_gravity(scene_id, 0, -9.81, 0)

set_simulation_scales

Sets the various scales to get realistic physics simulations (to avoid the famous Moon effect).

syntax

gh_physx4.set_simulation_scales (
size,
mass,
speed
)

parameters

size REAL the approximate size of objects in the simulation (default: 1.0)
mass REAL the approximate mass of a size * size * size block (default: 1000)
speed REAL the approximate velocities of objects in simulation (default: 10)

return values

none

code sample

gh_physx4.set_simulation_scales(1, 1000, 10)

set_solver_iteration_counts

Sets the number of solver iterations.
This a global value applied to each new actor.

syntax

gh_physx4.set_solver_iteration_counts (
position_iterations,
velocity_iterations
)

parameters

position_iterations INTEGER number of position iterations
velocity_iterations INTEGER number of velocity iterations

return values

none

code sample

position_iterations = 4
velocity_iterations = 1

gh_physx4.set_solver_iteration_counts(position_iterations, velocity_iterations)
...
actor_box = gh_physx4.create_actor_box(scene, 4, 4, 4, 0, 0, 0, density, mat_id)

start

Starts the PhysX engine.

syntax

ret = gh_physx4.start()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_physx4.start()

stop

Stops the PhysX engine.

syntax

ret = gh_physx4.stop()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_physx4.stop()

update_material

Updates the properties of a material.

syntax

gh_physx4.update_material (
mat_id,
static_friction,
dynamic_friction,
resilience
)

parameters

mat_id ID material identifier
static_friction REAL static friction
dynamic_friction REAL dynamic friction
resilience REAL resilience / restitution

return values

none

code sample

static_friction = 0.5
dynamic_friction = 0.5
resilience = 0.9

gh_physx4.update_material(mat_id, static_friction, dynamic_friction, resilience)

gh_physx5 windowslinuxmacos

NVIDIA PhysX 5 module

gh_physx5 is the module that manages NVIDIA PhysX 5 engine.
Thanks to gh_physx5, you will be able to play with rigid body collisions, joints and particles.

actor_add_force

Adds a force to an actor.

syntax

gh_physx5.actor_add_force (
actor_id,
fx, fy, fz
)

parameters

actor_id ID PhysX actor identifier
fx, fy, fz REAL force

return values

none

code sample

gh_phys5.actor_add_force(actor_id, fx, fy, fz)

actor_add_force_at_position

Adds a force to an actor at a particular position.

syntax

gh_physx5.actor_add_force_at_position (
actor_id,
fx, fy, fz,
px, py, pz
)

parameters

actor_id ID PhysX actor identifier
fx, fy, fz REAL force
px, py, pz REAL position

return values

none

code sample

gh_phys5.actor_add_force_at_position(actor_id, fx, fy, fz, px, py, pz)

actor_apply_transform

Applies the transformation (position + orientation) of an PhysX actor to a regular 3D object (a mesh for example).

syntax

gh_physx5.actor_apply_transform (
actor_id,
obj_id
)

parameters

actor_id ID PhysX actor identifier
obj_id ID object identifier

return values

none

code sample

gh_phys5.actor_apply_transform(actor_id, obj_id)

actor_clear_forces

Clears (resets) all forces that act on an actor.

syntax

gh_physx5.actor_clear_forces (
actor_id
)

parameters

actor_id ID actor identifier

return values

none

code sample

gh_phys5.actor_clear_forces(actor_id)

actor_get_angular_speed2

Gets the squared angular speed of an actor.

syntax

s = gh_physx5.actor_get_angular_speed2 (
actor_id
)

parameters

actor_id ID actor identifier

return values

s REAL squared speed

code sample

s = gh_phys5.actor_get_angular_speed2(actor_id)

actor_get_angular_velocity

Gets the angular velocity of an actor.

syntax

x, y, z = gh_physx5.actor_get_angular_velocity (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z = gh_phys5.actor_get_angular_velocity(actor_id)

actor_get_linear_speed2

Gets the squared linear speed of an actor.

syntax

speed = gh_physx5.actor_get_linear_speed2 (
actor_id
)

parameters

actor_id ID actor identifier

return values

speed REAL squared speed

code sample

speed = gh_phys5.actor_get_linear_speed2(actor_id)

actor_get_linear_velocity

Gets the linear velocity of an actor.

syntax

x, y, z = gh_physx5.actor_get_linear_velocity (
actor_id
)

parameters

actor_id ID actor identifier

return values

x, y, z REAL velocity vector

code sample

x, y, z = ggh_phys5.actor_get_linear_velocity(actor_id)

actor_get_orientation

Gets the orientation of an actor (a quaternion).

syntax

x, y, z, w = gh_physx5.actor_get_orientation (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z, w REAL orientation

code sample

x, y, z, w = gh_phys5.actor_get_orientation(actor_id)

actor_get_position

Gets the global position of an actor.

syntax

x, y, z = gh_physx5.actor_get_position (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

x, y, z REAL position

code sample

x, y, z = gh_phys5.actor_get_position(actor_id)

actor_get_sleep_threshold

Gets the sleep threshold.

syntax

thres = gh_physx5.actor_get_sleep_threshold (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

thres REAL threshold

code sample

thres = gh_phys5.actor_get_sleep_threshold(actor_id)

actor_get_transform_mat16

Returns the transformation matrix of a physics actor.

syntax

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_physx5.actor_get_transform_mat16 (
actor_id
)

parameters

actor_id ID actor identifier

return values

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 REAL the 16 floats that make the 4x4 matrix

code sample

m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 = gh_phys5.actor_get_transform_mat16(actor_id)

actor_get_transform_pos_qrot

Returns the position and orientation (quaternion) of a physics actor.

syntax

px, py, pz, qx, qy, qz, qw = gh_physx5.actor_get_transform_pos_qrot (
actor_id
)

parameters

actor_id ID actor identifier

return values

px, py, pz REAL position
qx, qy, qz, qw REAL rotation quaternion

code sample

px, py, pz, qx, qy, qz, qw = gh_phys5.actor_get_transform_pos_qrot(actor_id)

actor_is_sleeping

Gets the sleeping state of an actor.

syntax

state = gh_physx5.actor_is_sleeping (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

state BOOLEAN state (0 or 1)

code sample

is_sleeping = gh_phys5.actor_is_sleeping(actor_id)

actor_kill

Destroys an actor.

syntax

gh_physx5.actor_kill (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_phys5.actor_kill(actor_id)

actor_put_to_sleep

Forces an actor to sleep.

syntax

gh_physx5.actor_put_to_sleep (
actor_id
)

parameters

actor_id ID PhysX actor identifier

return values

none

code sample

gh_phys5.actor_put_to_sleep(actor_id)

actor_set_3d_object

Allows to associate a physics actor and a 3D object.
Useful for the scene_sync_3d_objects() function.

syntax

gh_physx5.actor_set_3d_object (
actor_id,
o3d_id
)

parameters

actor_id ID actor identifier
o3d_id ID 3d object identifier

return values

none

code sample

gh_phys5.actor_set_3d_object(actor_id, o3d_id)

actor_set_angular_damping

Sets the angular damping of an actor.

syntax

gh_physx5.actor_set_angular_damping (
actor_id,
damping
)

parameters

actor_id ID PhysX actor identifier
damping REAL damping

return values

none

code sample

gh_phys5.actor_set_angular_damping(actor_id, 0.2)

actor_set_angular_velocity

Sets the angular velocity of an actor.

syntax

gh_physx5.actor_set_angular_velocity (
actor_id,
vx, vy, vz
)

parameters

actor_id ID PhysX actor identifier
vx, vy, vz REAL 3D velocity vector

return values

none

code sample

gh_phys5.actor_set_angular_velocity(actor_id, 0.8, 12, 1.6)

actor_set_euler_angles

Sets the orientation of an actor using Euler's angles.

syntax

gh_physx5.actor_set_euler_angles (
actor_id,
pitch, yaw, roll
)

parameters

actor_id ID PhysX actor identifier
pitch, yaw, roll REAL Eurler's angles in degrees

return values

none

code sample

gh_phys5.actor_set_euler_angles(actor_id, 90, 0, 0)

actor_set_gravity_state

Sets the gravity state of an actor.

syntax

gh_physx5.actor_set_gravity_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_phys5.actor_set_gravity_state(actor_id, 1)

actor_set_kinematic_state

Sets the kinematic state of an actor.

syntax

gh_physx5.actor_set_kinematic_state (
actor_id,
state
)

parameters

actor_id ID PhysX actor identifier
state BOOLEAN state (0 or 1)

return values

none

code sample

gh_phys5.actor_set_kinematic_state(actor_id, 1)

actor_set_kinematic_target

Moves kinematically controlled dynamic actors through the 3d world.

syntax

gh_physx5.actor_set_kinematic_target (
actor_id,
px, py, pz,
pitch, yaw, roll
)

parameters

actor_id ID PhysX actor identifier
px, py, pz REAL destination position
pitch, yaw, roll REAL destination orientation

return values

none

code sample

gh_phys5.actor_set_kinematic_target(actor_id, px, py, pz, pitch, yaw, roll)

actor_set_linear_damping

Sets the linear damping of an actor.

syntax

gh_physx5.actor_set_linear_damping (
actor_id,
damping
)

parameters

actor_id ID PhysX actor identifier
damping REAL damping

return values

none

code sample

gh_phys5.actor_set_linear_damping(actor_id, 0.2)

actor_set_linear_velocity

Sets the linear velocity of an actor.

syntax

gh_physx5.actor_set_linear_velocity (
actor_id,
vx, vy, vz
)

parameters

actor_id ID PhysX actor identifier
vx, vy, vz REAL 3D velocity vector

return values

none

code sample

gh_phys5.actor_set_linear_velocity(actor_id, 10, 10, 10)

actor_set_material

Sets a material to an actor.

syntax

gh_physx5.actor_set_material (
actor_id,
mat_id
)

parameters

actor_id ID actor identifier
mat_id ID material identifier

return values

none

code sample

gh_phys5.actor_set_material(actor_id, mat_id)

actor_set_orientation

Sets the orientation of an actor (a quaternion).

syntax

gh_physx5.actor_set_orientation (
actor_id,
x, y, z, w
)

parameters

actor_id ID PhysX actor identifier
x, y, z, w REAL orientation quaternion

return values

none

code sample

gh_phys5.actor_set_orientation(actor_id, x, y, z, w)

actor_set_position

Sets the global position of an actor.

syntax

gh_physx5.actor_set_position (
actor_id,
x, y, z
)

parameters

actor_id ID PhysX actor identifier
x, y, z REAL position

return values

none

code sample

gh_phys5.actor_set_position(actor_id, x, y, z)

actor_set_sleep_threshold

Sets the sleep threshold.

syntax

gh_physx5.actor_set_sleep_threshold (
actor_id,
thres
)

parameters

actor_id ID PhysX actor identifier
thres REAL threshold

return values

none

code sample

gh_phys5.actor_set_sleep_threshold(actor_id, 0.2)

actor_set_solver_iterations

Sets the number of solver iterations for an actor.

syntax

gh_physx5.actor_set_solver_iterations (
actor_id,
position_iterations,
velocity_iterations
)

parameters

actor_id ID PhysX actor identifier
position_iterations INTEGER number of position iterations
velocity_iterations INTEGER number of velocity iterations

return values

none

code sample

position_iterations = 4
velocity_iterations = 1

gh_phys5.actor_set_solver_iterations(actor_id, position_iterations, velocity_iterations)

actor_update_mass

Update the mass of an actor from the density.

syntax

gh_physx5.actor_update_mass (
actor_id,
density
)

parameters

actor_id ID actor identifier
density REAL density

return values

none

code sample

gh_phys5.actor_update_mass(actor_id, density)

actor_wake_up

Wakes up an actor.

syntax

gh_physx5.actor_wake_up (
actor_id,
sleep_counter
)

parameters

actor_id ID PhysX actor identifier
sleep_counter REAL sleep counter

return values

none

code sample

gh_phys5.actor_wake_up(actor_id, 1)

check_results

Checks if results of a simulation step are available.

syntax

ret = gh_physx5.check_results (
scene_id
)

parameters

scene_id ID PhysX scene identifier

return values

ret BOOLEAN available: 1 (true) or 0 (false)

code sample

if (can_run_sim) then
    gh_phys5.run_simulation_step(scene_id, time_step)
    can_run_sim = false
end

if (gh_phys5.check_results(scene_id) == 1) then
    gh_phys5.fetch_results(scene_id)
    can_run_sim = true
end

create_actor_box

Creates a box actor.

syntax

actor_id = gh_physx5.create_actor_box (
scene_id,
w, h, d,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
w, h, d REAL width, height and depth
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_box = gh_phys5.create_actor_box(scene_id, 4, 4, 4, 0, 0, 0, density, mat_id)

create_actor_capsule

Creates a capsule actor.

syntax

actor_id = gh_physx5.create_actor_capsule (
scene_id,
radius,
half_height,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
radius REAL radius of the capsule (actually the cylinder)
half_height REAL half height of the cylinder
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_capsule = gh_phys5.create_actor_capsule(scene_id, radius, half_height, 0, 0, 0, density, mat_id)

create_actor_mesh

Creates an actor from a mesh.

syntax

actor_id = gh_physx5.create_actor_mesh (
scene_id,
mesh_id,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_mesh = gh_phys5.create_actor_mesh(scene_id, mesh_id, 0, 0, 0, density, mat_id)

create_actor_mesh_v2

Creates an actor from a mesh.
You can specify if the mesh is convex or not.
Only vertices of a convex mesh are used by PhysX.
To be GPU friendly, the number of vertices must not exceed 64.

syntax

actor_id = gh_physx5.create_actor_mesh_v2 (
scene_id,
mesh_id,
px, py, pz,
density,
mat_id,
convex
)

parameters

scene_id ID PhysX scene identifier
mesh_id ID mesh identifier
px, py, pz REAL position
density REAL density
mat_id ID material identifier
convex BOOLEAN convex state: 1 (yes) or 0 (no)

return values

actor_id ID PhysX actor identifier

code sample

convex = 1
actor_mesh = gh_phys5.create_actor_mesh_v2(scene_id, mesh_id, 0, 0, 0, density, mat_id, convex)

create_actor_plane

Creates a plane actor.

syntax

actor_id = gh_physx5.create_actor_plane (
scene_id,
nx, ny, nz, d,
mat_id
)

parameters

scene_id ID PhysX scene identifier
nx, ny, nz, d REAL plane equation
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_plane = gh_phys5.create_actor_plane(scene_id, 0, 1, 0, 0, mat_id)

create_actor_sphere

Creates a sphere actor.

syntax

actor_id = gh_physx5.create_actor_sphere (
scene_id,
radius,
px, py, pz,
density,
mat_id
)

parameters

scene_id ID PhysX scene identifier
radius REAL radius
px, py, pz REAL position
density REAL density
mat_id ID material identifier

return values

actor_id ID PhysX actor identifier

code sample

actor_sphere = gh_phys5.create_actor_sphere(scene_id, 10, 0, 0, 0, density, mat_id)

create_material

Creates a PhysX material.

syntax

mat_id = gh_physx5.create_material (
static_friction,
dynamic_friction,
resilience
)

parameters

static_friction REAL static friction
dynamic_friction REAL dynamic friction
resilience REAL resilience

return values

mat_id ID PhysX material identifier

code sample

mat_id = gh_phys5.create_material(0.5, 0.5, 0.5)

create_scene

Creates a PhysX scene - DEPRECATED

syntax

scene_id = gh_physx5.create_scene (
gpu_physx,
bounce_threshold_velocity
)

parameters

gpu_physx BOOLEAN 1 (GPU) or 0 (CPU)
bounce_threshold_velocity REAL bounce threshold velocity

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2

scene_id = gh_phys5.create_scene(1, bounce_threshold_velocity)

create_scene_broadphase_abp

Creates a CPU PhysX scene with ABP (revisited implementation of MBP, new in PhysX 4) broadphase algorithm.

syntax

scene_id = gh_physx5.create_scene_broadphase_abp (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_phys5.create_scene_broadphase_abp(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_broadphase_gpu

Creates a GPU PhysX scene.

syntax

scene_id = gh_physx5.create_scene_broadphase_gpu (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_phys5.create_scene_broadphase_gpu(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_broadphase_mbp

Creates a CPU PhysX scene with MBP (Multi-Box Pruning) broadphase algorithm.

syntax

scene_id = gh_physx5.create_scene_broadphase_mbp (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization,
minX, minY, minZ,
maxX, maxY, maxZ
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)
minX, minY, minZ REAL world minimal dimension
maxX, maxY, maxZ REAL world maximal dimension

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

minX = -100
minY = 0
minZ = -100
maxX = 100,
maxY = 100
maxZ = 100

scene_id = gh_phys5.create_scene_broadphase_mbp(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization, minX, minY, minZ, maxX, maxY, maxZ)

create_scene_broadphase_sap

Creates a CPU PhysX scene with SAP (Multi-Box Pruning) broadphase algorithm.

syntax

scene_id = gh_physx5.create_scene_broadphase_sap (
bounce_threshold_velocity,
enable_ccd,
enable_contact_reporting,
enable_stabilization
)

parameters

bounce_threshold_velocity REAL bounce threshold velocity
enable_ccd BOOLEAN CCD: 1 (enabled) or 0 (disabled)
enable_contact_reporting BOOLEAN contact reporting: 1 (enabled) or 0 (disabled)
enable_stabilization BOOLEAN stabilization: 1 (enabled) or 0 (disabled)

return values

scene_id ID PhysX scene identifier

code sample

bounce_threshold_velocity = 0.2
enable_ccd = 1
enable_contact_reporting = 0
enable_stabilization = 1

scene_id = gh_phys5.create_scene_broadphase_sap(bounce_threshold_velocity, enable_ccd, enable_contact_reporting, enable_stabilization)

create_scene_set_solver_type

Set the solver that will be used to create a PhysX scene.Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.
Compared to scene_sync_3d_objects(), this function synchronizes only PhysX active actors (actors that have been updated by the PhysX engine).
If used, create_scene_set_solver_type() must be called before any scene creation function.

syntax

gh_physx5.create_scene_set_solver_type (
solver_type
)

parameters

solver_type ENUM( physx_solver_type ) solver type

return values

none

code sample

gh_phys5.create_scene_set_solver_type(solver_type)

fetch_results

Fetches the results of a simulation step.

syntax

ret = gh_physx5.fetch_results (
scene_id
)

parameters

scene_id ID PhysX scene identifier

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_phys5.run_simulation_step(scene_id, time_step)

ret = gh_phys5.fetch_results(scene_id)

gpu_get_clock_frequency_khz

Gets the clock speed of the PhysX GPU.

syntax

clock = gh_physx5.gpu_get_clock_frequency_khz()

parameters

none

return values

clock INTEGER clock speed in kHz

code sample

clock = gh_phys5.gpu_get_clock_frequency_khz()

gpu_get_name

Gets the name of the PhysX GPU.

syntax

name = gh_physx5.gpu_get_name()

parameters

none

return values

name STRING name of the GPU

code sample

gpu_name = gh_phys5.gpu_get_name()

gpu_get_num_multiprocessors

Gets the number of SMs of the PhysX GPU.

syntax

num_sm = gh_physx5.gpu_get_num_multiprocessors()

parameters

none

return values

num_sm INTEGER number of SMs

code sample

gpu_sm = gh_phys5.gpu_get_num_multiprocessors()

gpu_get_total_memory_size_mb

Gets the size of the PhysX GPU memory.

syntax

size = gh_physx5.gpu_get_total_memory_size_mb()

parameters

none

return values

size INTEGER size of the memory in MB

code sample

size = gh_phys5.gpu_get_total_memory_size_mb()

gpu_is_supported

windows

Checks for PhysX GPU support (Windows only).

syntax

ret = gh_physx5.gpu_is_supported()

parameters

none

return values

ret BOOLEAN supported: 1 (true) or 0 (false)

code sample

gpu_physx = gh_phys5.gpu_is_supported()

joint_create

Creates a PhysX joint between two PhysX actors.

syntax

joint_id = gh_physx5.joint_create (
scene_id,
joint_type,
actor1_id,
x1, y1, z1,
pitch1, yaw1, roll1,
actor2_id,
x2, y2, z2,
pitch2, yaw2, roll2
)

parameters

scene_id ID PhysX scene identifier
joint_type ENUM( physx_joint_type ) type of joint: SPHERICAL (0), REVOLUTE (1), FIXED (2), DISTANCE (3), PRISMATIC (4), D6 (5 not implemented)
actor1_id ID PhysX first actor identifier
x1, y1, z1 REAL position of the joint related to the first actor
pitch1, yaw1, roll1 REAL orientation of the joint related to the first actor
actor2_id ID PhysX second actor identifier
x2, y2, z2 REAL position of the joint related to the second actor
pitch2, yaw2, roll2 REAL orientation of the joint related to the second actor

return values

joint_id ID PhysX joint identifier

code sample

joint_id = gh_phys5.joint_create(scene_id, joint_type, actor1, x1, y1, z1, pitch1, yaw1, roll1, actor2, x2, y2, z2, pitch2, yaw2, roll2)

joint_distance_set_distances

Sets distance joint distance range.

syntax

gh_physx5.joint_distance_set_distances (
joint_id,
min_distance, max_distance
)

parameters

joint_id ID PhysX joint identifier
min_distance, max_distance REAL min / max distance of the joint

return values

none

code sample

gh_phys5.joint_distance_set_distances(joint_id, min_distance, max_distance)

joint_distance_set_spring

Sets distance joint spring parameters.

syntax

gh_physx5.joint_distance_set_spring (
joint_id,
spring_coef, damping_coef
)

parameters

joint_id ID PhysX joint identifier
spring_coef, damping_coef REAL spring parameters

return values

none

code sample

gh_phys5.joint_distance_set_spring(joint_id, spring_coef, damping_coef)

joint_kill

Kills a PhysX joint.

syntax

gh_physx5.joint_kill (
joint_id
)

parameters

joint_id ID PhysX joint identifier

return values

none

code sample

gh_phys5.joint_kill(joint_id)

joint_prismatic_set_limits

Sets prismatic joint parameters.

syntax

gh_physx5.joint_prismatic_set_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver

return values

none

code sample

gh_phys5.joint_prismatic_set_limits(joint_id, lower_limit, upper_limit, limit_contact_distance)

joint_revolute_set_angular_limits

Sets revolute joint angular limits.

syntax

gh_physx5.joint_revolute_set_angular_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance,
damping,
stiffness,
restitution,
bounce_threshold
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver
damping REAL damping of the limit spring
stiffness REAL if greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit
restitution REAL controls the amount of bounce when the joint hits a limit
bounce_threshold REAL determines the minimum impact velocity which will cause the joint to bounce

return values

none

code sample

gh_phys5.joint_revolute_set_angular_limits(joint_id, lower_limit, upper_limit, limit_contact_distance, damping, stiffness, restitution, bounce_threshold)

joint_revolute_set_rotational_limits

Sets revolute joint parameters.

syntax

gh_physx5.joint_revolute_set_rotational_limits (
joint_id,
lower_limit, upper_limit,
limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
lower_limit, upper_limit REAL the range of the limit. The upper limit must be no lower than the lower limit.
limit_contact_distance REAL the distance inside the limit value at which the limit will be considered to be active by the solver

return values

none

code sample

gh_phys5.joint_revolute_set_rotational_limits(joint_id, lower_limit, upper_limit, limit_contact_distance)

joint_set_break_force

Set the breaking force of a PhysX joint.

syntax

gh_physx5.joint_set_break_force (
joint_id,
force, torque
)

parameters

joint_id ID PhysX joint identifier
force, torque REAL force and torque

return values

none

code sample

gh_phys5.joint_set_break_force(joint_id, force, torque)

joint_set_motor_params

Sets motor parameters of a revolute joint.

syntax

gh_physx5.joint_set_motor_params (
joint_id,
velocity, max_force,
drive_enabled, free_spin_enabled
)

parameters

joint_id ID PhysX joint identifier
velocity, max_force REAL parameters
drive_enabled, free_spin_enabled BOOLEAN drive and free spin parameters: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_phys5.joint_set_motor_params(joint_id, velocity, max_force, drive_enabled, free_spin_enabled)

joint_spherical_set_limit_cone

Sets parameters of a spherical joint.

syntax

gh_physx5.joint_spherical_set_limit_cone (
joint_id,
y_limit_angle, z_limit_angle, limit_contact_distance
)

parameters

joint_id ID PhysX joint identifier
y_limit_angle, z_limit_angle, limit_contact_distance REAL parameters

return values

none

code sample

gh_phys5.joint_spherical_set_limit_cone(joint_id, y_limit_angle, z_limit_angle, limit_contact_distance)

kill_material

Destroys a material.

syntax

gh_physx5.kill_material (
mat_id
)

parameters

mat_id ID material identifier

return values

none

code sample

gh_phys5.kill_material(mat_id)

run_simulation

Runs a complete simulation (step + fetch).

syntax

ret = gh_physx5.run_simulation (
scene_id,
dt,
time_step
)

parameters

scene_id ID PhysX scene identifier
dt REAL detla time
time_step REAL simulation time step

return values

ret BOOLEAN simulation done: 1 (true) or 0 (false)

code sample

ret = gh_phys5.run_simulation(scene_id, dt, time_step)

run_simulation_step

Runs a simulation step.

syntax

ret = gh_physx5.run_simulation_step (
scene_id,
time_step
)

parameters

scene_id ID PhysX scene identifier
time_step REAL simulation time step

return values

ret BOOLEAN simulation: 1 (started) or 0 (error)

code sample

ret = gh_phys5.run_simulation_step(scene_id, time_step)

scene_get_num_active_actors

Get the number of active PhysX actors.

syntax

n = gh_physx5.scene_get_num_active_actors (
scene_id
)

parameters

scene_id ID scene identifier

return values

n INTEGER number of active actors

code sample

n = gh_phys5.scene_get_num_active_actors(scene_id)

scene_sync_3d_objects

Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.

syntax

gh_physx5.scene_sync_3d_objects (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_phys5.scene_sync_3d_objects(scene_id)

scene_sync_3d_objects_v2

Synchronizes physics and graphics objects.
A physcis actor is associated to a 3D object using the actor_set_3d_object() function.
Compared to scene_sync_3d_objects(), this function synchronizes only PhysX active actors (actors that have been updated by the PhysX engine).

syntax

gh_physx5.scene_sync_3d_objects_v2 (
scene_id
)

parameters

scene_id ID scene identifier

return values

none

code sample

gh_phys5.scene_sync_3d_objects_v2(scene_id)

set_max_depenetration_velocity

Sets the max depenetration velocity.
This a global value applied to each new actor.

syntax

gh_physx5.set_max_depenetration_velocity (
velocity
)

parameters

velocity REAL depenetration velocity

return values

none

code sample

velocity = 3.0

gh_phys5.set_max_depenetration_velocity(velocity)
...
actor_box = gh_phys5.create_actor_box(scene, 4, 4, 4, 0, 0, 0, density, mat_id)

set_scene_gravity

Sets the scene gravity vector.

syntax

gh_physx5.set_scene_gravity (
scene_id,
x, y, z
)

parameters

scene_id ID PhysX scene identifier
x, y, z REAL gravity vector

return values

none

code sample

gh_phys5.set_scene_gravity(scene_id, 0, -9.81, 0)

set_simulation_scales

Sets the various scales to get realistic physics simulations (to avoid the famous Moon effect).

syntax

gh_physx5.set_simulation_scales (
size,
mass,
speed
)

parameters

size REAL the approximate size of objects in the simulation (default: 1.0)
mass REAL the approximate mass of a size * size * size block (default: 1000)
speed REAL the approximate velocities of objects in simulation (default: 10)

return values

none

code sample

gh_phys5.set_simulation_scales(1, 1000, 10)

set_solver_iteration_counts

Sets the number of solver iterations.
This a global value applied to each new actor.

syntax

gh_physx5.set_solver_iteration_counts (
position_iterations,
velocity_iterations
)

parameters

position_iterations INTEGER number of position iterations
velocity_iterations INTEGER number of velocity iterations

return values

none

code sample

position_iterations = 4
velocity_iterations = 1

gh_phys5.set_solver_iteration_counts(position_iterations, velocity_iterations)
...
actor_box = gh_phys5.create_actor_box(scene, 4, 4, 4, 0, 0, 0, density, mat_id)

start

Starts the PhysX engine.

syntax

ret = gh_physx5.start()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_phys5.start()

stop

Stops the PhysX engine.

syntax

ret = gh_physx5.stop()

parameters

none

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_phys5.stop()

update_material

Updates the properties of a material.

syntax

gh_physx5.update_material (
mat_id,
static_friction,
dynamic_friction,
resilience
)

parameters

mat_id ID material identifier
static_friction REAL static friction
dynamic_friction REAL dynamic friction
resilience REAL resilience / restitution

return values

none

code sample

static_friction = 0.5
dynamic_friction = 0.5
resilience = 0.9

gh_phys5.update_material(mat_id, static_friction, dynamic_friction, resilience)

gh_polyline

Polyline module

gh_polyline is the module that manages polylines (a set of non-connected lines).

create_v2

Creates a polyline.

syntax

pl_id = gh_polyline.create_v2 (
num_vertices,
line_mode
)

parameters

num_vertices INTEGER number of vertices
line_mode ENUM( line_mode ) line mode: DEFAULT (0), STRIP (1) or LOOP (2)

return values

pl_id ID polyline identifier

code sample

pl_id = gh_polyline.create_v2(num_vertices, line_mode)

get_vertex_color

Gets the color of a particular vertex.

syntax

r, g, b, a = gh_polyline.get_vertex_color (
pl_id,
vertex_index
)

parameters

pl_id ID polyline identifier
vertex_index INTEGER index of the vertex

return values

r, g, b, a REAL RGBA color of the vertex

code sample

r, g, b, a = gh_polyline.get_vertex_color(pl_id, vertex_index)

get_vertex_position

Gets the position of a particular vertex.

syntax

x, y, z, w = gh_polyline.get_vertex_position (
pl_id,
vertex_index
)

parameters

pl_id ID polyline identifier
vertex_index INTEGER index of the vertex

return values

x, y, z, w REAL 4D position of the vertex

code sample

x, y, z, w = gh_polyline.get_vertex_position(pl_id, vertex_index)

set_vertex_color

Sets the color of a particular vertex.

syntax

gh_polyline.set_vertex_color (
pl_id,
vertex_index,
r, g, b, a
)

parameters

pl_id ID polyline identifier
vertex_index INTEGER index of the vertex
r, g, b, a REAL RGBA color of the vertex

return values

none

code sample

gh_polyline.set_vertex_color(pl_id, vertex_index, r, g, b, a)

set_vertex_draw_range

Sets the start vertex index and the number of vertices to render.

syntax

gh_polyline.set_vertex_draw_range (
pl_id,
start_index,
num_vertices
)

parameters

pl_id ID polyline identifier
start_index INTEGER start offset. Default value is 0
num_vertices INTEGER number of vertices to render

return values

none

code sample

gh_polyline.set_vertex_draw_range(pl_id, 0, 2)

set_vertex_position

Sets the position of a particular vertex.

syntax

gh_polyline.set_vertex_position (
pl_id,
vertex_index,
x, y, z, w
)

parameters

pl_id ID polyline identifier
vertex_index INTEGER index of the vertex
x, y, z, w REAL 3D position of the vertex

return values

none

code sample

gh_polyline.set_vertex_position(pl_id, vertex_index, x0, y0, z0, 1.0)

set_vertex_position_color

Sets the position and the color of a particular vertex.

syntax

gh_polyline.set_vertex_position_color (
pl_id,
vertex_index,
x, y, z, w,
r, g, b, a
)

parameters

pl_id ID polyline identifier
vertex_index INTEGER index of the vertex
x, y, z, w REAL 3D position of the vertex
r, g, b, a REAL RGBA color of the vertex

return values

none

code sample

gh_polyline.set_vertex_position_color(pl_id, vertex_index, x, y, z, w, r, g, b, a)

set_vertices_color

lua

Sets the color of all vertices using a table as input

syntax

gh_polyline.set_vertices_color (
pl_id,
start_offset,
num_vertices,
vertices_list
)

parameters

pl_id ID polyline identifier
start_offset INTEGER index of the first vertex
num_vertices INTEGER number vertices that must be updated
vertices_list TABLE list of all colors, each element of the list must have the following format: {x=, y=, z=, w=}

return values

none

code sample

colors = {}
colors[1] = {x=1.0, y=1.0, z=0.0, w=1.0}
colors[2] = {x=0.0, y=1.0, z=1.0, w=1.0}

start_offset = 0
num_vertices = 2

gh_polyline.set_vertices_color(pl_id, start_offset, num_vertices, colors)

set_vertices_color_v2

Sets the color of all vertices using a single RGBA value.

syntax

gh_polyline.set_vertices_color_v2 (
pl_id,
r, g, b, a
)

parameters

pl_id ID polyline identifier
r, g, b, a REAL RGBA value

return values

none

code sample

gh_polyline.set_vertices_color_v2(pl_id, r, g, b, a)

set_vertices_position

lua

Sets the position of all vertices using a table as input

syntax

gh_polyline.set_vertices_position (
pl_id,
start_offset,
num_vertices,
vertices_list
)

parameters

pl_id ID polyline identifier
start_offset INTEGER index of the first vertex
num_vertices INTEGER number vertices that must be updated
vertices_list TABLE list of all positions, each element of the list must have the following format: {x=, y=, z=, w=}

return values

none

code sample

positions = {}
positions[1] = {x=-1.0, y=-1.0, z=0.0, w=1.0}
positions[2] = {x=1.0, y=1.0, z=0.0, w=1.0}

start_offset = 0
num_vertices = 2

gh_polyline.set_vertices_position(pl_id, start_offset, num_vertices, positions)

wideline_add_point

Adds a point to a wideline.

syntax

gh_polyline.wideline_add_point (
pl_id,
x, y, z, w,
r, g, b, a
)

parameters

pl_id ID polyline identifier
x, y, z, w REAL vec4 position of a point
r, g, b, a REAL RGBA color of the point

return values

none

code sample

gh_polyline.wideline_add_point(pl_id, x, y, z, w, r, g, b, a)

wideline_create

Creates a wideline polyline.

syntax

pl_id = gh_polyline.wideline_create (
num_vertices,
line_width
)

parameters

num_vertices INTEGER number of vertices
line_width REAL line width

return values

pl_id ID polyline identifier

code sample

pl_id = gh_polyline.wideline_create(num_vertices, 5.0)

wideline_reset_points

Resets (clears) all points of a wideline.

syntax

gh_polyline.wideline_reset_points (
pl_id
)

parameters

pl_id ID polyline identifier

return values

none

code sample

gh_polyline.wideline_reset_points(pl_id)

wideline_set_line_width

Adds a point to a wideline.

syntax

gh_polyline.wideline_set_line_width (
pl_id,
line_width
)

parameters

pl_id ID polyline identifier
line_width REAL width of the line

return values

none

code sample

gh_polyline.wideline_set_line_width(pl_id, line_width)

gh_ps

Particle System module

gh_ps is the module that manages particle systems.

action_set_gravity

Sets the gravity vector of an gravity action.

syntax

gh_ps.action_set_gravity (
action_id,
x, y, z
)

parameters

action_id ID action identifier
x, y, z REAL gravity vector

return values

none

code sample

gh_ps.action_set_gravity(action_id, 0, -9.81, 0)

create

Creates a particle system.

syntax

ps_id = gh_ps.create (
max_particles,
lifetime
)

parameters

max_particles INTEGER max number of particles
lifetime REAL max life time of particles

return values

ps_id ID particle system identifier

code sample

ps_id = gh_ps.create(1000, 2.0)

create_action_gravity

Creates a gravity action.

syntax

action_id = gh_ps.create_action_gravity (
ps_id
)

parameters

ps_id ID particle system identifier

return values

action_id ID action identifier

code sample

action_id = gh_ps.create_action_gravity(ps_id)

create_emitter_point

Creates a point emitter.

syntax

emitter_id = gh_ps.create_emitter_point (
ps_id
)

parameters

ps_id ID particle system identifier

return values

emitter_id ID emitter identifier

code sample

emitter_id = gh_ps.create_emitter_point(ps_id)

emitter_set_particle_rate_and_speed

Sets the particle rate and the particle speed for a particular emitter.

syntax

gh_ps.emitter_set_particle_rate_and_speed (
emitter_id,
rate, speed
)

parameters

emitter_id ID emitter identifier
rate, speed REAL rate and particle speed

return values

none

code sample

gh_ps.emitter_set_particle_rate_and_speed(emitter_id, 100, 4.0)

emitter_set_spawn_directions

Sets the particle spawn directions for a particular emitter.

syntax

gh_ps.emitter_set_spawn_directions (
emitter_id,
x1, y1, z1,
x2, y2, z2
)

parameters

emitter_id ID emitter identifier
x1, y1, z1 REAL first direction
x2, y2, z2 REAL second direction

return values

none

code sample

gh_ps.emitter_set_spawn_directions(emitter_id, -0.1, 0.5, -0.1, 0.1, 1.0, 0.1)

get_num_alive_particles

Returns the number of alive particles (with lifetime > 0).

syntax

num_alive = gh_ps.get_num_alive_particles (
ps_id
)

parameters

ps_id ID particle system identifier

return values

num_alive INTEGER number of alive particles

code sample

n = gh_ps.get_num_alive_particles(ps_id)

process_particle_actions

Processes all particles actions.

syntax

gh_ps.process_particle_actions (
ps_id,
dt
)

parameters

ps_id ID particle system identifier
dt REAL time step in seconds

return values

none

code sample

gh_ps.process_particle_actions(ps_id, 0.016)

process_particle_emitters

Processes all particles emitters.

syntax

gh_ps.process_particle_emitters (
ps_id,
dt
)

parameters

ps_id ID particle system identifier
dt REAL time step in seconds

return values

none

code sample

gh_ps.process_particle_emitters(ps_id, 0.016)

process_particles

Processes all particles (run simulation).

syntax

gh_ps.process_particles (
ps_id,
dt
)

parameters

ps_id ID particle system identifier
dt REAL time step in seconds

return values

none

code sample

gh_ps.process_particles(ps_id, 0.016)

update_particles_lifetime

Updates the particles life time.

syntax

gh_ps.update_particles_lifetime (
ps_id,
dt
)

parameters

ps_id ID particle system identifier
dt REAL time step in seconds

return values

none

code sample

gh_ps.update_particles_lifetime(ps_id, 0.016)

gh_render_target

Render target module

gh_render_target is the module that manages render targets.
A render target is used in render to texture and post processing effects.

bind

Binds the render target.

syntax

gh_render_target.bind (
rt_id
)

parameters

rt_id ID render target identifier

return values

none

code sample

gh_render_target.bind(rt_id)
...
gh_render_target.bind(0) -- unbinds

create

Creates a render target.

syntax

rt_id = gh_render_target.create (
width, height
)

parameters

width, height INTEGER size of the render target

return values

rt_id ID render target identifier

code sample

rt_id = gh_render_target.create(2048, 2048)

create_cubemap

Creates a depth only render target.

syntax

rt_id = gh_render_target.create_cubemap (
size,
create_color_cubemap,
depth_conf,
pf,
linear_filtering,
clamp_addressing
)

parameters

size INTEGER size of the cubemap faces
create_color_cubemap INTEGER specifies the creation of a color target
depth_conf ENUM( depth_buffer_config ) depth buffer configuration: 0 (no depth), 1 (depth_cubemap), 2 (depth_renderbuffer), 3 (depth_texture)
pf ENUM( pixel_format ) pixel format of color target
linear_filtering BOOLEAN performs linear filtering: 1 (true) or 0 (false)
clamp_addressing BOOLEAN clamps the texture to the borders: 1 (true) or 0 (false)

return values

rt_id ID render target identifier

code sample

PF_U8_RGBA = 3

rt_id = gh_render_target.create_cubemap(1024, 1, 1, PF_U8_RGBA, 1, 1)

create_depth

Creates a depth only render target.

syntax

rt_id = gh_render_target.create_depth (
width, height,
linear_filtering
)

parameters

width, height INTEGER size of the render target
linear_filtering BOOLEAN performs linear filtering: 1 (true) or 0 (false)

return values

rt_id ID render target identifier

code sample

rt_id = gh_render_target.create_depth(2048, 2048, 0)

create_ex

Creates a render target.

syntax

rt_id = gh_render_target.create_ex (
width, height,
pf,
linear_filtering,
msaa_samples
)

parameters

width, height INTEGER size of the render target
pf ENUM( pixel_format ) pixel format of color target
linear_filtering BOOLEAN performs linear filtering: 1 (true) or 0 (false)
msaa_samples INTEGER number of antialiasing samples

return values

rt_id ID render target identifier

code sample

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

linear_filtering = 1
msaa_samples = 4

rt_id = gh_render_target.create_ex(2048, 2048, PF_F32_RGBA, linear_filtering, msaa_samples)

create_ex_v3

Creates a render target with multiple render targets (MRTs).

syntax

rt_id = gh_render_target.create_ex_v3 (
width, height,
num_color_targets,
pf,
linear_filtering,
clamp_addressing,
msaa_samples
)

parameters

width, height INTEGER size of the render target
num_color_targets INTEGER number of color targets
pf ENUM( pixel_format ) pixel format of color target
linear_filtering BOOLEAN performs linear filtering: 1 (true) or 0 (false)
clamp_addressing BOOLEAN clamps the texture to the borders: 1 (true) or 0 (false)
msaa_samples INTEGER number of antialiasing samples

return values

rt_id ID render target identifier

code sample

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_F16_RGB = 8
PF_F16_RGBA = 9
PF_F16_R = 10
PF_U8_R = 11
PF_U8_RG = 12

num_color_targets = 4
linear_filtering = 1
clamp_addressing = 1
msaa_samples = 4

rt_id = gh_render_target.create_ex_v3(2048, 2048, num_color_targets, PF_F32_RGBA, linear_filtering, msaa_samples)

create_ex_v4

Creates a render target with multiple render targets (MRTs).

syntax

rt_id = gh_render_target.create_ex_v4 (
width, height,
num_color_targets,
pf,
linear_filtering,
clamp_addressing,
msaa_samples,
create_depth_texture
)

parameters

width, height INTEGER size of the render target
num_color_targets INTEGER number of color targets
pf ENUM( pixel_format ) pixel format of color target
linear_filtering BOOLEAN performs linear filtering: 1 (true) or 0 (false)
clamp_addressing BOOLEAN clamps the texture to the borders: 1 (true) or 0 (false)
msaa_samples INTEGER number of antialiasing samples
create_depth_texture BOOLEAN enable (1, default) or disable (0) the creation of a depth render target

return values

rt_id ID render target identifier

code sample

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_F16_RGB = 8
PF_F16_RGBA = 9
PF_F16_R = 10
PF_U8_R = 11
PF_U8_RG = 12

num_color_targets = 4
linear_filtering = 1
clamp_addressing = 1
msaa_samples = 4
create_depth_texture = 1

rt_id = gh_render_target.create_ex_v4(2048, 2048, num_color_targets, PF_F32_RGBA, linear_filtering, msaa_samples, create_depth_texture)

create_ex_v5

Creates a render target with multiple render targets (MRTs).

syntax

rt_id = gh_render_target.create_ex_v5 (
width, height,
num_color_targets,
pf,
linear_filtering,
clamp_addressing,
msaa_samples,
create_depth_texture,
gen_mipmaps
)

parameters

width, height INTEGER size of the render target
num_color_targets INTEGER number of color targets
pf ENUM( pixel_format ) pixel format of color target
linear_filtering BOOLEAN performs linear filtering: 1 (true) or 0 (false)
clamp_addressing BOOLEAN clamps the texture to the borders: 1 (true) or 0 (false)
msaa_samples INTEGER number of antialiasing samples
create_depth_texture BOOLEAN enable (1, default) or disable (0) the creation of a depth render target
gen_mipmaps BOOLEAN enable (1) or disable (0, default) generation of mipmaps

return values

rt_id ID render target identifier

code sample

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_F16_RGB = 8
PF_F16_RGBA = 9
PF_F16_R = 10
PF_U8_R = 11
PF_U8_RG = 12

num_color_targets = 4
linear_filtering = 1
clamp_addressing = 1
msaa_samples = 4
create_depth_texture = 1
gen_mipmaps = 0

rt_id = gh_render_target.create_ex_v5(2048, 2048, num_color_targets, PF_F32_RGBA, linear_filtering, msaa_samples, create_depth_texture, gen_mipmaps)

create_rb

Creates a color depth render buffer.

syntax

rt_id = gh_render_target.create_rb (
width, height,
pf,
msaa_samples
)

parameters

width, height INTEGER size of the render target
pf ENUM( pixel_format ) pixel format of color target
msaa_samples INTEGER number of antialiasing samples

return values

rt_id ID render target identifier

code sample

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_F16_RGB = 8
PF_F16_RGBA = 9
PF_F16_R = 10
PF_U8_R = 11
PF_U8_RG = 12

msaa_samples = 4

rt_id = gh_render_target.create_rb(2048, 2048, PF_F32_RGBA, msaa_samples)

create_v2

Creates a render target with multiple render targets (MRTs).

syntax

rt_id = gh_render_target.create_v2 (
width, height,
num_color_targets
)

parameters

width, height INTEGER size of the render target
num_color_targets INTEGER number of color targets

return values

rt_id ID render target identifier

code sample

rt_id = gh_render_target.create_v2(2048, 2048, 4)

cubemap_set_draw_face

Specifies the target of drawing commands for a cubemap render target.

syntax

gh_render_target.cubemap_set_draw_face (
rt_id,
face
)

parameters

rt_id ID render target identifier
face INTEGER face of the cubemap (0 to 5)

return values

none

code sample

gh_render_target.cubemap_set_draw_face(rt_id, face)

kill

Kills (cleanup + free resources) a render target.

syntax

gh_render_target.kill (
rt_id
)

parameters

rt_id ID render target identifier

return values

none

code sample

gh_render_target.kill(rt_id)

resize

Resizes a render target.

syntax

gh_render_target.resize (
rt_id,
width, height
)

parameters

rt_id ID render target identifier
width, height INTEGER size of the render target

return values

none

code sample

gh_render_target.resize(rt_id, new_width, new_height)

resolve_multisampling

Resolves multisampling.

syntax

gh_render_target.resolve_multisampling (
rt_src,
rt_dst
)

parameters

rt_src INTEGER multisampled source render target
rt_dst INTEGER regular destination render target

return values

none

code sample

gh_render_target.resolve_multisampling(rt_src, rt_dst)

use_with_syphon

macos

Specifies that this render target can be a source for Syphon (macOS only).

syntax

gh_render_target.use_with_syphon (
rt_id
)

parameters

rt_id ID render target identifier

return values

none

code sample

gh_render_target.use_with_syphon(rt_id)

gh_renderer

Renderer module

gh_renderer is the module that talks directly with the graphics hardware.

check_opengl_extension

Checks if a particular OpenGL extension is exposed.

syntax

name = gh_renderer.check_opengl_extension (
extension_name
)

parameters

extension_name STRING name of the extension

return values

name STRING OpenGL extension name

code sample

if (gh_renderer.check_opengl_extension("GL_ARB_compute_shader") == 1) then
    -- OpenGL 4.3 compute shaders are supported.
end

clear_color_buffer

Clear the color buffer with a RGBA color.

syntax

gh_renderer.clear_color_buffer (
r, g, b, a
)

parameters

r, g, b, a REAL RGBA clear color

return values

none

code sample

gh_renderer.clear_color_buffer(0, 0, 0, 1)

clear_color_depth_buffers

Clear the color and depth buffers in the same call.

syntax

gh_renderer.clear_color_depth_buffers (
r, g, b, a,
z
)

parameters

r, g, b, a REAL RGBA clear color
z REAL z buffer value

return values

none

code sample

gh_renderer.clear_color_depth_buffers(r, g, b, a, z)

clear_depth_buffer

Clear the depth buffer.

syntax

gh_renderer.clear_depth_buffer (
z
)

parameters

z REAL z buffer value

return values

none

code sample

z = 1.0
gh_renderer.clear_depth_buffer(z)

conservative_rasterization_get_properties_nv

OpenGL / NVIDIA GPUs - returns properties related to conservative rasterization.
See the GL_NV_conservative_raster extension for more details.

syntax

bias_xbits, bias_ybits, max_bias_bits = gh_renderer.conservative_rasterization_get_properties_nv()

parameters

none

return values

bias_xbits, bias_ybits, max_bias_bits INTEGER properties

code sample

bias_xbits, bias_ybits, max_bias_bits = gh_renderer.conservative_rasterization_get_properties_nv()

conservative_rasterization_set_sub_pixel_precision_bias_nv

OpenGL / NVIDIA GPUs - sets conservative rasterization params.
See the GL_NV_conservative_raster extension for more details.

syntax

gh_renderer.conservative_rasterization_set_sub_pixel_precision_bias_nv (
bias_xbits, bias_ybits
)

parameters

bias_xbits, bias_ybits INTEGER conservative rasterization params

return values

none

code sample

gh_renderer.conservative_rasterization_set_sub_pixel_precision_bias_nv(bias_xbits, bias_ybits)

disable_state

Disables a rendering state.

syntax

gh_renderer.disable_state (
state_name
)

parameters

state_name ENUM( gl_state ) name of the state

return values

none

code sample

--[[
States supported:
"GL_CLIP_DISTANCE0"
"GL_CLIP_DISTANCE1"
"GL_CLIP_DISTANCE2"
"GL_CLIP_DISTANCE3"
"GL_MULTISAMPLE"
"GL_CULL_FACE"
"GL_BLEND"
"GL_DEPTH_TEST"
"GL_SCISSOR_TEST"
"GL_TEXTURE_2D"
"GL_LIGHTING"
"GL_LIGHT0"
"GL_LIGHT1"
"GL_LIGHT2"
"GL_LIGHT3"
"GL_PROGRAM_POINT_SIZE"
"GL_CONSERVATIVE_RASTERIZATION_INTEL"
"GL_CONSERVATIVE_RASTERIZATION_NV"
"GL_MULTISAMPLE"
--]]

gh_renderer.disable_state("GL_CLIP_DISTANCE0")

display_progress_bar

Renders a progress bar.
The progress bar percent is set with gh_utils.set_progress_bar_percent().
Both functions can be used in an INIT script to draw a progress bar while loading data.

syntax

gh_renderer.display_progress_bar (
percent
)

parameters

percent REAL size of the progress bar: 100% means the window width

return values

none

code sample

gh_utils.set_progress_bar_percent(20)
gh_renderer.display_progress_bar()
...
... do some stuff
...

gh_utils.set_progress_bar_percent(60)
gh_renderer.display_progress_bar()
...
... do some stuff
...

gh_utils.set_progress_bar_percent(100)
gh_renderer.display_progress_bar()

draw_primitives

Draws primitives (POINTS, LINES, TRIANGLES, TRIANGLE_STRIP, etc.).
In GeeXLab this function is essentially used with attribute-less rendering.

syntax

gh_renderer.draw_primitives (
primitive_type,
count,
start
)

parameters

primitive_type ENUM( primitive_type ) type of primitive
count INTEGER number of primitives to draw
start INTEGER start index in the primitive buffer

return values

none

code sample

PRIMITIVE_TRIANGLE = 0
PRIMITIVE_TRIANGLE_STRIP = 1
PRIMITIVE_LINE = 2
PRIMITIVE_LINE_STRIP = 3
PRIMITIVE_LINE_LOOP = 4
PRIMITIVE_POINT = 8

primitive_type = PRIMITIVE_TRIANGLE_STRIP
count = 4
start = 0

gh_renderer.draw_primitives(primitive_type, count, start)

enable_state

Enables a rendering state.

syntax

gh_renderer.enable_state (
state_name
)

parameters

state_name ENUM( gl_state ) name of the state

return values

none

code sample

--[[
States supported:
"GL_CLIP_DISTANCE0"
"GL_CLIP_DISTANCE1"
"GL_CLIP_DISTANCE2"
"GL_CLIP_DISTANCE3"
"GL_MULTISAMPLE"
"GL_SAMPLE_ALPHA_TO_COVERAGE"
"GL_SAMPLE_ALPHA_TO_ONE"
"GL_CULL_FACE"
"GL_BLEND"
"GL_DEPTH_TEST"
"GL_SCISSOR_TEST"
"GL_DEPTH_BOUNDS_TEST_EXT"
"GL_POLYGON_OFFSET_FILL"
"GL_DITHER"
"GL_TEXTURE_2D"
"GL_LIGHTING"
"GL_LIGHT0"
"GL_LIGHT1"
"GL_LIGHT2"
"GL_LIGHT3"
"GL_PROGRAM_POINT_SIZE"
"GL_POINT_SPRITE"
"GL_CONSERVATIVE_RASTERIZATION_INTEL"
"GL_CONSERVATIVE_RASTERIZATION_NV"
"GL_TEXTURE_CUBE_MAP_SEAMLESS"
--]]

gh_renderer.enable_state("GL_CLIP_DISTANCE0")

get_api_version

Gets the OpenGL version.

syntax

version = gh_renderer.get_api_version()

parameters

none

return values

version STRING OpenGL version

code sample

glversion = gh_renderer.get_api_version()

get_api_version_major

Gets OpenGL major version number.

syntax

major = gh_renderer.get_api_version_major()

parameters

none

return values

major INTEGER major version

code sample

glmajor = gh_renderer.get_api_version_major()

if (glmajor < 4) then
    -- Tessellation not supported
end

get_api_version_minor

Gets OpenGL minor version number.

syntax

minor = gh_renderer.get_api_version_minor()

parameters

none

return values

minor INTEGER minor version

code sample

glminor = gh_renderer.get_api_version_minor()

get_capability_4i

Gets a hardware capability.

syntax

x, y, z, w = gh_renderer.get_capability_4i (
cap_name
)

parameters

cap_name ENUM( gl_capability ) name of the capability

return values

x, y, z, w INTEGER capability values (up to 4 values)

code sample

--[[
Capabilities supported:
"GL_MAX_SUBROUTINES"
"GL_MAX_SUBROUTINE_UNIFORM_LOCATIONS"
"GL_MAX_VERTEX_ATTRIBS"
"GL_MAX_TEXTURE_SIZE"
"GL_MAX_TEXTURE_IMAGE_UNITS"
"GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS"
"GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS"
"GL_MAX_COMPUTE_TEXTURE_IMAGE_UNITS"
"GL_MAX_ARRAY_TEXTURE_LAYERS"
"GL_MAX_COLOR_ATTACHMENTS"
"GL_MAX_DRAW_BUFFERS"
"GL_MAX_VIEWPORT_DIMS"
"GL_MAX_SAMPLES"
"GL_MAX_VERTEX_STREAMS"
"GL_MAX_GEOMETRY_SHADER_INVOCATIONS"
"GL_MAX_PATCH_VERTICES"
"GL_MAX_TESS_GEN_LEVEL"
"GL_MAX_TRANSFORM_FEEDBACK_BUFFERS"
"GL_MAX_COMPUTE_WORK_GROUP_COUNT"
"GL_MAX_COMPUTE_WORK_GROUP_SIZE"
"GL_MAX_COMPUTE_WORK_GROUP_INVOCATIONS"
"GL_MAX_COMPUTE_SHARED_MEMORY_SIZE"
"GL_MAX_FRAMEBUFFER_WIDTH"
"GL_MAX_FRAMEBUFFER_WIDTH"
"GL_MAX_FRAMEBUFFER_HEIGHT"
"GL_MAX_FRAMEBUFFER_LAYERS"
"GL_MAX_FRAMEBUFFER_SAMPLES"
"GL_MAX_WIDTH"
"GL_MAX_HEIGHT"
"GL_MAX_DEPTH"
"GL_MAX_LAYERS"
"GL_MAX_COMBINED_DIMENSIONS"
"GL_MAX_VERTEX_ATTRIB_STRIDE"
"GL_MIN_MAP_BUFFER_ALIGNMENT"
"GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT"
"GL_SHADER_STORAGE_BUFFER_OFFSET_ALIGNMENT"
"GL_TEXTURE_BUFFER_OFFSET_ALIGNMENT"
"GL_MAX_UNIFORM_BUFFER_BINDINGS"
"GL_MAX_UNIFORM_BLOCK_SIZE"
"GL_MAX_VERTEX_UNIFORM_BLOCKS"
"GL_MAX_FRAGMENT_UNIFORM_BLOCKS"
"GL_MAX_GEOMETRY_UNIFORM_BLOCKS"
"GL_MAX_TESS_CONTROL_UNIFORM_BLOCKS"
"GL_MAX_TESS_EVALUATION_UNIFORM_BLOCKS"
"GL_MAX_COMPUTE_UNIFORM_BLOCKS"
"GL_MAX_COMBINED_UNIFORM_BLOCKS"
"GL_SHADER_STORAGE_BUFFER_OFFSET_ALIGNMENT"
"GL_MAX_SHADER_STORAGE_BLOCK_SIZE"
"GL_MAX_SHADER_STORAGE_BUFFER_BINDINGS"
"GL_MAX_VERTEX_SHADER_STORAGE_BLOCKS"
"GL_MAX_FRAGMENT_SHADER_STORAGE_BLOCKS"
"GL_MAX_GEOMETRY_SHADER_STORAGE_BLOCKS"
"GL_MAX_TESS_CONTROL_SHADER_STORAGE_BLOCKS"
"GL_MAX_TESS_EVALUATION_SHADER_STORAGE_BLOCKS"
"GL_MAX_COMPUTE_SHADER_STORAGE_BLOCKS"
"GL_MAX_COMBINED_SHADER_STORAGE_BLOCKS"
"GL_MAX_ATOMIC_COUNTER_BUFFER_SIZE"
"GL_MAX_ATOMIC_COUNTER_BUFFER_BINDINGS"
"GL_MAX_COMBINED_ATOMIC_COUNTER_BUFFERS"
"GL_MAX_VERTEX_ATOMIC_COUNTERS"
"GL_MAX_FRAGMENT_ATOMIC_COUNTERS"
"GL_MAX_GEOMETRY_ATOMIC_COUNTERS"
"GL_MAX_TESS_CONTROL_ATOMIC_COUNTERS"
"GL_MAX_TESS_EVALUATION_ATOMIC_COUNTERS"
"GL_MAX_COMPUTE_ATOMIC_COUNTERS"
"GL_MAX_CULL_DISTANCES"
"GL_MAX_COMBINED_CLIP_AND_CULL_DISTANCES"
--]]

max_tex_size = gh_renderer.get_capability_4i("GL_MAX_TEXTURE_SIZE")

get_num_opengl_extensions

Returns the number of OpenGL extensions.

syntax

num_extensions = gh_renderer.get_num_opengl_extensions()

parameters

none

return values

num_extensions INTEGER number of OpenGL extensions

code sample

num_extensions = gh_renderer.get_num_opengl_extensions()

get_num_virtual_screens

macos

Gets the number of virtual screens (macOS only).

syntax

num_screens = gh_renderer.get_num_virtual_screens()

parameters

none

return values

num_screens INTEGER number of virtual screens

code sample

num_screens = gh_renderer.get_num_virtual_screens()

get_opengl_error

Returns the OpenGL error code or 0 if no error.

syntax

errcode = gh_renderer.get_opengl_error()

parameters

none

return values

errcode INTEGER error code

code sample

err_code = gh_renderer.get_opengl_error()

get_opengl_extension

Returns the name of a particular OpenGL extension.

syntax

name = gh_renderer.get_opengl_extension (
index
)

parameters

index INTEGER index of the OpenGL extension: from 0 to get_num_opengl_extensions()-1.

return values

name STRING OpenGL extension name

code sample

index = 0
gl_extension = gh_renderer.get_opengl_extension(index)

get_renderer_model

Gets the model of the renderer (the name of the graphics card).

syntax

model = gh_renderer.get_renderer_model()

parameters

none

return values

model STRING Renderer model

code sample

glrenderer = gh_renderer.get_renderer_model()

get_renderer_vendor

Gets the vendor of the renderer (the name of the graphics card GPU maker).

syntax

vendor = gh_renderer.get_renderer_vendor()

parameters

none

return values

vendor STRING Renderer vendor

code sample

glvendor = gh_renderer.get_renderer_vendor()

get_shading_language_version

Gets the GLSL version.

syntax

version = gh_renderer.get_shading_language_version()

parameters

none

return values

version STRING GLSL version

code sample

glsl_version = gh_renderer.get_shading_language_version()

get_virtual_screen

macos

Gets the current virtual screen (macOS only).

syntax

screen = gh_renderer.get_virtual_screen()

parameters

none

return values

screen INTEGER current virtual screen

code sample

screen = gh_renderer.get_virtual_screen(ac_buffer, index)

gl_get_integeri_1i

lua

OpenGL: gets a capability value by index.

syntax

x = gh_renderer.gl_get_integeri_1i (
capability,
index
)

parameters

capability INTEGER OpenGL capability. Example: 38203 (0x953b, GL_MAX_MESH_WORK_GROUP_SIZE_NV)...
index INTEGER index

return values

x INTEGER capability value

code sample

GL_MAX_MESH_WORK_GROUP_SIZE_NV = 38203		
capability = GL_MAX_MESH_WORK_GROUP_SIZE_NV
x = gh_renderer.gl_get_integeri_1i(capability, 0)
y = gh_renderer.gl_get_integeri_1i(capability, 1)
z = gh_renderer.gl_get_integeri_1i(capability, 2)

gl_get_integerv_1i

lua

OpenGL: gets a capability value

syntax

x = gh_renderer.gl_get_integerv_1i (
capability
)

parameters

capability INTEGER numeric value of an OpenGL capability. Example: 38203 (0x953b, GL_MAX_MESH_WORK_GROUP_SIZE_NV)...

return values

x INTEGER capability value

code sample

GL_MAX_MESH_TOTAL_MEMORY_SIZE_NV = 38198		
x = gh_renderer.gl_get_integerv_1i(GL_MAX_MESH_TOTAL_MEMORY_SIZE_NV)

gl_get_integerv_4i

lua

OpenGL: gets a capability value

syntax

x, y, z, w = gh_renderer.gl_get_integerv_4i (
capability
)

parameters

capability INTEGER numeric value of an OpenGL capability

return values

x, y, z, w INTEGER capability value

code sample

x, y, z, w = gh_renderer.gl_get_integerv_4i(capability)

glx_get_client_extension

OpenGL / Linux - gets the name of a particular GLX client extension.

syntax

name = gh_renderer.glx_get_client_extension (
index
)

parameters

index INTEGER index of extension in the range (0 … num_extensions - 1)

return values

name STRING extension name

code sample

name = gh_renderer.glx_get_client_extension(index)

glx_get_client_num_extensions

OpenGL / Linux - gets the number of GLX client extensions.

syntax

num_extensions = gh_renderer.glx_get_client_num_extensions()

parameters

none

return values

num_extensions INTEGER number of extensions

code sample

n = gh_renderer.glx_get_client_num_extensions()

glx_get_renderer_info_int

OpenGL / Linux - gets a GLX attribute value.

syntax

int_val = gh_renderer.glx_get_renderer_info_int (
attribute
)

parameters

attribute ENUM( renderer_info_int ) attribute type

return values

int_val INTEGER attribute value

code sample

-- Attribute types
GLX_RENDERER_ATTRIBUTE_INFO_GLX_VERSION_MAJOR = 5
GLX_RENDERER_ATTRIBUTE_INFO_GLX_VERSION_MINOR = 6
GLX_RENDERER_ATTRIBUTE_INFO_VENDOR_ID = 7
GLX_RENDERER_ATTRIBUTE_INFO_DEVICE_ID = 8
GLX_RENDERER_ATTRIBUTE_INFO_VERSION_MAJOR = 9
GLX_RENDERER_ATTRIBUTE_INFO_VERSION_MINOR = 10
GLX_RENDERER_ATTRIBUTE_INFO_VERSION_PATCH = 11
GLX_RENDERER_ATTRIBUTE_INFO_ACCELERATED = 12
GLX_RENDERER_ATTRIBUTE_INFO_VIDEO_MEMORY = 13
GLX_RENDERER_ATTRIBUTE_INFO_UMA = 14

attribute = GLX_RENDERER_ATTRIBUTE_INFO_VENDOR_ID

x = gh_renderer.glx_get_renderer_info_int(attribute)

glx_get_renderer_info_str

OpenGL / Linux - gets a GLX attribute value.

syntax

str_val = gh_renderer.glx_get_renderer_info_str (
attribute
)

parameters

attribute ENUM( renderer_info_str ) attribute type

return values

str_val STRING attribute value

code sample

-- Attribute types
GLX_RENDERER_ATTRIBUTE_INFO_SVR_VENDOR_STR = 1
GLX_RENDERER_ATTRIBUTE_INFO_SVR_VERSION_STR = 2
GLX_RENDERER_ATTRIBUTE_INFO_CLIENT_VENDOR_STR = 3
GLX_RENDERER_ATTRIBUTE_INFO_CLIENT_VERSION_STR = 4

attribute = GLX_RENDERER_ATTRIBUTE_INFO_SVR_VENDOR_STR

str = gh_renderer.glx_get_renderer_info_str(attribute)

glx_get_server_extension

OpenGL / Linux - gets the name of a particular GLX server extension.

syntax

name = gh_renderer.glx_get_server_extension (
index
)

parameters

index INTEGER index of extension in the range (0 … num_extensions - 1)

return values

name STRING extension name

code sample

name = gh_renderer.glx_get_server_extension(index)

glx_get_server_num_extensions

OpenGL / Linux - gets the number of GLX server extensions.

syntax

num_extensions = gh_renderer.glx_get_server_num_extensions()

parameters

none

return values

num_extensions INTEGER number of extensions

code sample

n = gh_renderer.glx_get_server_num_extensions()

is_opengl_es

Returns 1 if OpenGL ES is used.
Useful to handle shaders on different platforms.

syntax

gh_renderer.is_opengl_es()

parameters

none

return values

none

code sample

is_opengl_es = gh_renderer.is_opengl_es()

memory_barrier

Based on OpenGL glMemoryBarrier: defines a barrier ordering memory transactions.

syntax

gh_renderer.memory_barrier (
mask
)

parameters

mask ENUM( gl_memory_barrier_mask ) mask description

return values

none

code sample

mask = "GL_SHADER_STORAGE_BARRIER_BIT GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT"

gh_renderer.memory_barrier(mask)

point

Enables the POINT rendering mode.

syntax

gh_renderer.point()

parameters

none

return values

none

code sample

gh_renderer.point()

rasterizer_apply_states

Applies all states modified with gh_renderer.rasterizer_xxx() functions.

syntax

gh_renderer.rasterizer_apply_states()

parameters

none

return values

none

code sample

local BACK_FACE = 0

gh_renderer.rasterizer_set_cull_face(BACK_FACE)
gh_renderer.rasterizer_set_cull_state(0)

local BACK_FRONT_FACE = 2
local LINE = 1

gh_renderer.rasterizer_set_polygon_mode(BACK_FRONT_FACE, LINE)

gh_renderer.rasterizer_apply_states()

rasterizer_set_cull_face

Sets the face type to be culled.

syntax

gh_renderer.rasterizer_set_cull_face (
face
)

parameters

face ENUM( culling ) type of face: back (0), front (1) or back_and_front (2)

return values

none

code sample

local BACK_FACE = 0

gh_renderer.rasterizer_set_cull_face(BACK_FACE)
gh_renderer.rasterizer_set_cull_state(1)

rasterizer_set_cull_state

Enables or disable the face culling state.

syntax

gh_renderer.rasterizer_set_cull_state (
state
)

parameters

state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_renderer.rasterizer_set_cull_state(1)

rasterizer_set_polygon_mode

Sets the polygon rendering mode.

syntax

gh_renderer.rasterizer_set_polygon_mode (
face,
mode
)

parameters

face ENUM( culling ) type of face: back (0), front (1) or back_and_front (2)
mode ENUM( polygon_rendering_mode ) polygon rendering mode: point (0), line (1) or solid (2)

return values

none

code sample

local BACK_FRONT_FACE = 2
local LINE = 1

gh_renderer.rasterizer_set_polygon_mode(BACK_FRONT_FACE, LINE)

set_blending_color

Sets the blending color used with all CONSTANT_COLOR blending factors.

syntax

gh_renderer.set_blending_color (
r,
b,
g,
a
)

parameters

r REAL red value
b REAL blue value
g REAL green value
a REAL alpha value

return values

none

code sample

gh_renderer.set_blending_color(r, g, b, a)

set_blending_equation

Sets the blending equation type.

syntax

gh_renderer.set_blending_equation (
eq
)

parameters

eq ENUM( blend_equation ) type of the equation

return values

none

code sample

-- Possible values:
BLEND_EQUATION_ADD = 0
BLEND_EQUATION_SUBTRACT = 1
BLEND_EQUATION_REVERSE_SUBTRACT = 2
BLEND_EQUATION_MIN = 3
BLEND_EQUATION_MAX = 4

eq = BLEND_EQUATION_ADD -- ADD is the default value

gh_renderer.set_blending_equation(eq)

set_blending_factors

Sets the source and destination blending factors.

syntax

gh_renderer.set_blending_factors (
src,
dst
)

parameters

src ENUM( blend_factor ) source factor. See the code samples all values.
dst ENUM( blend_factor ) destination factor. See the code samples all values.

return values

none

code sample

BLEND_FACTOR_ZERO = 0
BLEND_FACTOR_ONE = 1
BLEND_FACTOR_SRC_ALPHA = 2
BLEND_FACTOR_ONE_MINUS_DST_ALPHA = 3
BLEND_FACTOR_ONE_MINUS_DST_COLOR = 4
BLEND_FACTOR_ONE_MINUS_SRC_ALPHA = 5
BLEND_FACTOR_DST_COLOR = 6
BLEND_FACTOR_DST_ALPHA = 7
BLEND_FACTOR_SRC_COLOR = 8
BLEND_FACTOR_ONE_MINUS_SRC_COLOR = 9
BLEND_FACTOR_CONSTANT_COLOR = 10
BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR = 11
BLEND_FACTOR_CONSTANT_ALPHA = 12
BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA = 13
BLEND_FACTOR_SRC_ALPHA_SATURATE = 14

local BLEND_FACTOR_ONE = 1

gh_renderer.set_blending_factors(BLEND_FACTOR_ONE, BLEND_FACTOR_ONE)
gh_renderer.set_blending_state(1)

set_blending_state

Enables or disables the color blending.

syntax

gh_renderer.set_blending_state (
state
)

parameters

state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_renderer.set_blending_state(1)

set_color_mask

Sets the mask for the color buffer (enables or disables writing to the color buffer).

syntax

gh_renderer.set_color_mask (
mr, mg, mb, ma
)

parameters

mr, mg, mb, ma INTEGER four masks for the four RGBA channels: 0 (writing disabled) or 1 (writing enabled)

return values

none

code sample

gh_renderer.set_color_mask(1, 0, 0, 1)
...
gh_renderer.set_color_mask(1, 1, 1, 1)

set_depth_mask

Sets the mask for the depth buffer (enables or disables writing to the depth buffer).

syntax

gh_renderer.set_depth_mask (
m
)

parameters

m INTEGER mask: 0 (writing disabled) or 1 (writing enabled)

return values

none

code sample

gh_renderer.set_depth_mask(0)
...
gh_renderer.set_depth_mask(1)

set_depth_test_func

Sets the depth test function.

syntax

gh_renderer.set_depth_test_func (
func_type
)

parameters

func_type ENUM( blend_cmp_func ) depth test comparison function

return values

none

code sample

CMP_FUNC_NEVER = 0
CMP_FUNC_LESS = 1
CMP_FUNC_LESS_OR_EQUAL = 2
CMP_FUNC_GREATER = 3
CMP_FUNC_GREATER_OR_EQUAL = 4
CMP_FUNC_EQUAL = 5
CMP_FUNC_NOT_EQUAL = 6
CMP_FUNC_ALWAYS = 7

local CMP_FUNC_LESS = 1

gh_renderer.set_depth_test_func(CMP_FUNC_LESS)

set_depth_test_state

Enables or disable the depth test.

syntax

gh_renderer.set_depth_test_state (
state
)

parameters

state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_renderer.set_depth_test_state(1)

set_line_stipple

Sets line stipple (OpenGL 2.1).

syntax

gh_renderer.set_line_stipple (
factor,
pattern
)

parameters

factor INTEGER factor
pattern INTEGER pattern

return values

none

code sample

gh_renderer.set_line_stipple(factor, pattern)

set_line_width

Sets the line width (OpenGL 2.1).

syntax

gh_renderer.set_line_width (
width
)

parameters

width REAL line width

return values

none

code sample

gh_renderer.set_line_width(2.0)

set_scissor

Sets the scissor rectangle.

syntax

gh_renderer.set_scissor (
x, y,
width, height
)

parameters

x, y INTEGER scissor rectangle offsets
width, height INTEGER scissor rectangle size

return values

none

code sample

gh_renderer.set_scissor(0, 0, width, height)

set_scissor_state

Enables or disable the scissor test.

syntax

gh_renderer.set_scissor_state (
state
)

parameters

state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_renderer.set_scissor_state(1)

set_texture2d_state

Enables or disable the texturing state of the fixed pipeline.

syntax

gh_renderer.set_texture2d_state (
state
)

parameters

state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_renderer.set_texture2d_state(state)

set_viewport

Sets the viewport.

syntax

gh_renderer.set_viewport (
x, y,
width, height
)

parameters

x, y INTEGER viewport offsets
width, height INTEGER viewport size

return values

none

code sample

gh_renderer.set_viewport(0, 0, width, height)

set_viewport_scissor

Sets the viewport and the scissor rectangle in the same call.

syntax

gh_renderer.set_viewport_scissor (
x, y,
width, height
)

parameters

x, y INTEGER offsets
width, height INTEGER viewport and scissor rectangle size

return values

none

code sample

gh_renderer.set_viewport_scissor(0, 0, width, height)

set_virtual_screen

macos

Sets the current virtual screen (macOS only).

syntax

gh_renderer.set_virtual_screen (
screen
)

parameters

screen INTEGER current virtual screen

return values

none

code sample

gh_renderer.set_virtual_screen(screen)

set_vsync

Enables or disables the vertical synchronization.

syntax

gh_renderer.set_vsync (
state
)

parameters

state BOOLEAN 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_renderer.set_vsync(0)

shader_thread_group_get_properties_nv

OpenGL / NVIDIA GPUs - returns GPU architecture details.
Based on OpenGL GL_NV_shader_thread_group extension.

syntax

num_sm, num_warps_per_sm, warp_size = gh_renderer.shader_thread_group_get_properties_nv()

parameters

none

return values

num_sm INTEGER number of SMs
num_warps_per_sm INTEGER number of warps per SM
warp_size INTEGER size of a warp

code sample

warp_size, warp_per_sm, sm_count = gh_renderer.shader_thread_group_get_properties_nv()

solid

Enables the SOLID rendering mode.

syntax

gh_renderer.solid()

parameters

none

return values

none

code sample

gh_renderer.solid()

update_fixed_mvp_matrices

Updates the fixed modelview and projection matrices from a camera and an object.
No GPU program is required for the rendering of the object.

syntax

gh_renderer.update_fixed_mvp_matrices (
cam_id,
obj_id
)

parameters

cam_id ID camera identifier
obj_id ID object identifier

return values

none

code sample

gh_renderer.update_fixed_mvp_matrices(cam_id, obj_id)

update_virtual_screen

macos

Updates the virtual screen.
Call this function after a change of virtual screen (macOS only).

syntax

gh_renderer.update_virtual_screen()

parameters

none

return values

none

code sample

gh_renderer.update_virtual_screen()

wireframe

Enables the WIREFRAME (or LINE) rendering mode.

syntax

gh_renderer.wireframe()

parameters

none

return values

none

code sample

gh_renderer.wireframe()

gh_rpi raspberry

Raspberry Pi module

gh_rpi is the module that manages the Raspberry Pi (RPi) GPIO and RGB LED matrix panel programming.

gpio_analog_read

Reads an analog value of a given pin.

syntax

value = gh_rpi.gpio_analog_read (
pin
)

parameters

pin INTEGER pin number

return values

value INTEGER analog value

code sample

value = gh_rpi.gpio_analog_read(pin)

gpio_analog_write

Writes the analog value to the given pin.

syntax

gh_rpi.gpio_analog_write (
pin,
value
)

parameters

pin INTEGER pin number
value INTEGER analog value

return values

none

code sample

gh_rpi.gpio_analog_write(pin, value)

gpio_digital_read

Reads the value of a given pin, returning 1 (HIGH) or 0 (LOW).

syntax

value = gh_rpi.gpio_digital_read (
pin
)

parameters

pin INTEGER pin number

return values

value BOOLEAN 1 (HIGH) or 0 (LOW)

code sample

pin = 23
value = gh_rpi.gpio_digital_read(pin)

gpio_digital_write

Writes an output bit.

syntax

gh_rpi.gpio_digital_write (
pin,
value
)

parameters

pin INTEGER pin number
value BOOLEAN 1 (HIGH) or 0 (LOW)

return values

none

code sample

pin = 23
state = 1

gh_rpi.gpio_digital_write(pin, state)

gpio_digital_write_byte

Writes an 8-bit byte to the first 8 GPIO pins.

syntax

gh_rpi.gpio_digital_write_byte (
value
)

parameters

value INTEGER 8-bit value

return values

none

code sample

gh_rpi.gpio_digital_write_byte(value)

gpio_get_alt

Returns the ALT bits for a given pin.

syntax

x = gh_rpi.gpio_get_alt (
pin
)

parameters

pin INTEGER pin number

return values

x INTEGER ALT bits

code sample

x = gh_rpi.gpio_get_alt(pin)

gpio_get_board_info

Returns information about the Raspberry Pi board.

syntax

maker, memsize, model, rev = gh_rpi.gpio_get_board_info()

parameters

none

return values

maker STRING maker of the board
memsize STRING memory size available on the board
model STRING model of the board
rev STRING revision of the board

code sample

model, rev, maker, memsize = gh_rpi.gpio_get_board_info()

gpio_init

Initializes the access to the RPi.
Must be called once in a INIT script.

syntax

gh_rpi.gpio_init (
pin_mode
)

parameters

pin_mode ENUM( gpio_pins_mapping_mode ) sets the pin numbering mode: 0 (wirinPi mode), 1 (GPIO mode), 2 (GPIO system mode) and 3 (physical mode)

return values

none

code sample

GPIO_PINS_MAPPING_MODE_GPIO = 1
GPIO_PINS_MAPPING_MODE_PHYSICAL = 3

gh_rpi.gpio_init(GPIO_PINS_MAPPING_MODE_GPIO)

gpio_phys_pin_to_gpio

Translates a physical pin number to native GPIO pin number.

syntax

gpio_pin = gh_rpi.gpio_phys_pin_to_gpio (
phys_pin
)

parameters

phys_pin INTEGER physical pin number

return values

gpio_pin INTEGER GPIO pin number

code sample

gpio_pin = gh_rpi.gpio_phys_pin_to_gpio(phys_pin)

gpio_pwm_tone_write

Writes the given frequency on the RPi's PWM pin.

syntax

gh_rpi.gpio_pwm_tone_write (
pin,
freq
)

parameters

pin INTEGER pin number
freq INTEGER frequency

return values

none

code sample

gh_rpi.gpio_pwm_tone_write(pin, freq)

gpio_pwm_write

Writes an output PWM value.

syntax

gh_rpi.gpio_pwm_write (
pin,
value
)

parameters

pin INTEGER pin number
value INTEGER PWM value

return values

none

code sample

gh_rpi.gpio_pwm_write(pin, value)

gpio_set_gpio_clock

Sets the frequency of a GPIO clock pin.

syntax

gh_rpi.gpio_set_gpio_clock (
pin,
freq
)

parameters

pin INTEGER pin number
freq INTEGER frequency

return values

none

code sample

gh_rpi.gpio_set_gpio_clock(pin, freq)

gpio_set_pad_drive

Sets the PAD driver value.

syntax

gh_rpi.gpio_set_pad_drive (
group,
value
)

parameters

group INTEGER group
value INTEGER value

return values

none

code sample

gh_rpi.gpio_set_pad_drive(group, value)

gpio_set_pin_mode

Sets the GPIO pin mode: input, output, PWM output, etc.

syntax

gh_rpi.gpio_set_pin_mode (
mode
)

parameters

mode ENUM( gpio_pin_mode ) pin mode: 0 (INPUT), 1 (OUTPUT), 2 (PWM_OUTPUT), 3 (GPIO_CLOCK), 4 (SOFT_PWM_OUTPUT), 5 (SOFT_TONE_OUTPUT) and 6 (PWM_TONE_OUTPUT)

return values

none

code sample

GPIO_MODE_OUTPUT = 1

gh_rpi.mgpio_set_pin_mode(GPIO_MODE_OUTPUT)

gpio_set_pin_mode_alt

Special function that lets you set any pin to any mode.

syntax

gh_rpi.gpio_set_pin_mode_alt (
pin,
mode
)

parameters

pin INTEGER pin number
mode ENUM( gpio_pin_mode ) mode

return values

none

code sample

gh_rpi.gpio_set_pin_mode_alt(pin, mode)

gpio_set_pmw_clock

Sets the PWM clock.

syntax

gh_rpi.gpio_set_pmw_clock (
divisor
)

parameters

divisor INTEGER frequency divisor

return values

none

code sample

gh_rpi.gpio_set_pmw_clock(divisor)

gpio_set_pull_up_down_control

Controls the internal pull-up/down resistors on a GPIO pin.

syntax

gh_rpi.gpio_set_pull_up_down_control (
pin,
pud
)

parameters

pin INTEGER pin number
pud INTEGER pull-up/down resistors value

return values

none

code sample

gh_rpi.gpio_set_pull_up_down_control(pin, pud)

gpio_set_pwm_mode

Selects the native balanced mode, or standard mark:space mode.

syntax

gh_rpi.gpio_set_pwm_mode (
mode
)

parameters

mode ENUM( gpio_pwm_mode ) PWM mode: 0 (PWM_MODE_MS) or 1 (PWM_MODE_BAL)

return values

none

code sample

gh_rpi.gpio_set_pwm_mode(mode)

gpio_set_pwm_range

Sets the PWM range register.

syntax

gh_rpi.gpio_set_pwm_range (
range
)

parameters

range INTEGER PWM range

return values

none

code sample

gh_rpi.gpio_set_pwm_range(range)

gpio_wpi_pin_to_gpio

Translates a wiringPi pin number to native GPIO pin number.

syntax

gpio_pin = gh_rpi.gpio_wpi_pin_to_gpio (
wpi_pin
)

parameters

wpi_pin INTEGER wiringPi pin number

return values

gpio_pin INTEGER GPIO pin number

code sample

gpio_pin = gh_rpi.gpio_wpi_pin_to_gpio(wpi_pin)

rgbmatrix_fill_f32

Clears all LEDs with an uniform color.

syntax

gh_rpi.rgbmatrix_fill_f32 (
r, g, b
)

parameters

r, g, b REAL RGB color (0.0 to 1.0)

return values

none

code sample

gh_rpi.rgbmatrix_fill_u8(1.0, 0, 0)

rgbmatrix_fill_u8

Clears all LEDs with an uniform color.

syntax

gh_rpi.rgbmatrix_fill_u8 (
r, g, b
)

parameters

r, g, b INTEGER RGB color (0 to 255)

return values

none

code sample

gh_rpi.rgbmatrix_fill_u8(255, 0, 0)

rgbmatrix_get_luminance_correct

Gets the luminance correct state.

syntax

state = gh_rpi.rgbmatrix_get_luminance_correct()

parameters

none

return values

state BOOLEAN 1 (enabled) or 0 (disabled)

code sample

state = gh_rpi.rgbmatrix_get_luminance_correct()

rgbmatrix_get_num_pixels

Returns the numbers of LEDs (or pixels).

syntax

nh, nw = gh_rpi.rgbmatrix_get_num_pixels()

parameters

none

return values

nh INTEGER number of rows
nw INTEGER number of columns

code sample

num_leds_x, num_leds_y = gh_rpi.rgbmatrix_get_num_pixels()

rgbmatrix_get_pwmbits

Gets the number of bits for color representation: from 1 bit for simple color to 11 bits for true color.

syntax

num_bits = gh_rpi.rgbmatrix_get_pwmbits()

parameters

none

return values

num_bits INTEGER number of bits

code sample

bits = gh_rpi.rgbmatrix_get_pwmbits()

rgbmatrix_init

Initializes the functions to deal with RGB LED matrix panels (following the HUB75 interface).

syntax

ret = gh_rpi.rgbmatrix_init (
num_rows,
num_chained_panels
)

parameters

num_rows INTEGER number of rows of the LED matrix (16 or 32)
num_chained_panels INTEGER number of chained panels

return values

ret BOOLEAN return code: 1 (success) or 0 (error)

code sample

ret = gh_rpi.rgbmatrix_init(32, 1)

rgbmatrix_set_luminance_correct

Map brightness of output linearly to input with CIE1931 profile.

syntax

state = gh_rpi.rgbmatrix_set_luminance_correct()

parameters

none

return values

state BOOLEAN 1 (enabled) or 0 (disabled)

code sample

gh_rpi.rgbmatrix_set_luminance_correct(1)

rgbmatrix_set_pixel_f32

Sets the color of a particular LED (or pixel).

syntax

gh_rpi.rgbmatrix_set_pixel_f32 (
x, y,
r, g, b
)

parameters

x, y INTEGER pixel coordinates
r, g, b REAL pixel RGB color (0.0 to 1.0)

return values

none

code sample

gh_rpi.rgbmatrix_set_pixel_f32(7, 8,  1.0, 0, 0)

rgbmatrix_set_pixel_u8

Sets the color of a particular LED (or pixel).

syntax

gh_rpi.rgbmatrix_set_pixel_u8 (
x, y,
r, g, b
)

parameters

x, y INTEGER pixel coordinates
r, g, b INTEGER pixel RGB color (0 to 255)

return values

none

code sample

gh_rpi.rgbmatrix_set_pixel_u8(7, 8,  255, 0, 0)

rgbmatrix_set_pwmbits

Sets the number of bits for color representation: from 1 bit for simple color to 11 bits for true color.

syntax

gh_rpi.rgbmatrix_set_pwmbits (
num_bits
)

parameters

num_bits INTEGER number of bits

return values

none

code sample

gh_rpi.rgbmatrix_set_pwmbits(11)

rgbmatrix_terminate

Terminates and cleanup functions to deal with RGB LED matrix panels.

syntax

gh_rpi.rgbmatrix_terminate()

parameters

none

return values

none

code sample

gh_rpi.rgbmatrix_terminate()

gh_sqlite3

SQLite3 module

gh_sqlite3 is the module that manages the embedded SQLite3 database engine.

db_bind_blob_from_buffer

Binds a blob value for a prepared statement.
The content that will be stored in the blob comes from a memory buffer.

syntax

rc = gh_sqlite3.db_bind_blob_from_buffer (
db_id,
col_index,
buff_ptr,
buff_size
)

parameters

db_id ID database identifier
col_index INTEGER index of the column
buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

return values

rc ENUM( sqlite_return_codes ) return code

code sample

local demo_dir = gh_utils.get_demo_dir()
filename = demo_dir .. "assets/data.txt"

buffer, buffer_size = gh_utils.file_buffer_create(filename)

local col_index = 1
gh_sqlite3.db_bind_blob_from_buffer(db_id, col_index, buffer, buffer_size)

gh_sqlite3.db_step(db_id)

-- After step()...
gh_utils.file_buffer_kill(buffer)

db_bind_blob_from_file

Binds a blob value for a prepared statement.
The content that will be stored in the blob comes from a file.

syntax

rc = gh_sqlite3.db_bind_blob_from_file (
db_id,
column,
filename
)

parameters

db_id ID database identifier
column INTEGER index of the column
filename STRING absolute path of the file

return values

rc ENUM( sqlite_return_codes ) return code

code sample

local col_index = 1
filename = demo_dir .. "assets/image.jpg"

gh_sqlite3.db_bind_blob_from_file(db_id, col_index, filename)

db_bind_blob_from_string

Binds a blob value for a prepared statement.
The content that will be stored in the blob comes from a string.

syntax

rc = gh_sqlite3.db_bind_blob_from_string (
db_id,
col_index,
str
)

parameters

db_id ID database identifier
col_index INTEGER index of the column
str STRING string to be stored in the blob

return values

rc ENUM( sqlite_return_codes ) return code

code sample

local col_index = 1
str = "......."

gh_sqlite3.db_bind_blob_from_string(db_id, col_index, str)

db_bind_double

Binds a double value for a prepared statement.

syntax

rc, x = gh_sqlite3.db_bind_double (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

rc ENUM( sqlite_return_codes ) return code
x REAL value

code sample

local col_index = 1
x = 3.14159265

gh_sqlite3.db_bind_double(db_id, col_index, x)

db_bind_int

Binds an integer value for a prepared statement.

syntax

rc, x = gh_sqlite3.db_bind_int (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

rc ENUM( sqlite_return_codes ) return code
x INTEGER value

code sample

local col_index = 1
x = 12

gh_sqlite3.db_bind_int(db_id, col_index, x)

db_bind_text

Binds a text value for a prepared statement.

syntax

rc, text = gh_sqlite3.db_bind_text (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

rc ENUM( sqlite_return_codes ) return code
text STRING text

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

local sql = "CREATE TABLE images (id INTEGER PRIMARY KEY, name varchar(64), data BLOB)"

if (gh_sqlite3.db_exec(db_id, sql) == SQLITE_ERROR) then
    print("SQL error 1")
end

sql = "INSERT INTO images (name, data) VALUES (?, ?);"
if (gh_sqlite3.db_prepare(db_id, sql) == SQLITE_OK) then
    local col_index = 1
    gh_sqlite3.db_bind_text(db_id, col_index, "toto.jpg")

    col_index = 2
    gh_sqlite3.db_bind_blob_from_file(db_id, col_index, demo_dir .. "assets/toto.jpg")

    rc = gh_sqlite3.db_step(db_id)

    gh_sqlite3.db_finalize(db_id)
end

db_close

Closes a database.

syntax

rc = gh_sqlite3.db_close (
db_id
)

parameters

db_id ID database identifier

return values

rc ENUM( sqlite_return_codes ) return code

code sample

rc = gh_sqlite3.db_close(db_id)

db_column_blob_to_file

Stores the content of a blob in a file.

syntax

rc = gh_sqlite3.db_column_blob_to_file (
db_id,
col_index,
filename
)

parameters

db_id ID database identifier
col_index INTEGER index of the column
filename STRING absolute path of the destination file

return values

rc ENUM( sqlite_return_codes ) return code

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

rc = gh_sqlite3.db_column_blob_to_file(db_id, col_index, filename)

db_column_blob_to_string

Stores the content of a blob in a string.

syntax

str = gh_sqlite3.db_column_blob_to_string (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

str STRING output string

code sample

str = gh_sqlite3.db_column_blob_to_string(db_id, col_index)

db_column_get_blob

Gets the size and data pointer of a blob field.

syntax

dataptr, size = gh_sqlite3.db_column_get_blob (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

dataptr INTEGER light user data representing the blob data
size INTEGER size of the blob data

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

dataptr, size = gh_sqlite3.db_column_get_blob(db_id, col_index)

db_column_get_double

Gets the real value (a double) of a column.

syntax

rc, v = gh_sqlite3.db_column_get_double (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

rc ENUM( sqlite_return_codes ) return code
v INTEGER column value

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

v, rc = gh_sqlite3.db_column_get_double(db_id, col_index)

db_column_get_int

Gets the integer value of a column.

syntax

rc, v = gh_sqlite3.db_column_get_int (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

rc ENUM( sqlite_return_codes ) return code
v INTEGER column value

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

v, rc = gh_sqlite3.db_column_get_int(db_id, col_index)

db_column_get_text

Gets the text value of a column.

syntax

rc, text = gh_sqlite3.db_column_get_text (
db_id,
col_index,
max_chars
)

parameters

db_id ID database identifier
col_index INTEGER index of the column
max_chars INTEGER max number of chars your want to retrieve

return values

rc ENUM( sqlite_return_codes ) return code
text STRING column value

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

v, rc = gh_sqlite3.db_column_get_text(db_id, col_index, 1024)

db_column_get_text1024

Gets the text value of a column.

syntax

rc, text = gh_sqlite3.db_column_get_text1024 (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

rc ENUM( sqlite_return_codes ) return code
text STRING column value

code sample

-- return codes:
local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

v, rc = gh_sqlite3.db_column_get_text1024(db_id, col_index)

db_enable_extended_result_codes

Enables or disables the extented result codes.

syntax

gh_sqlite3.db_enable_extended_result_codes (
db_id,
state
)

parameters

db_id ID database identifier
state BOOLEAN extended result codes: 1 (enabled) or 0 (disabled)

return values

none

code sample

state = 1
gh_sqlite3.db_enable_extended_result_codes(db_id, state)

db_exec

Executes an SQL request.

syntax

rc = gh_sqlite3.db_exec (
db_id,
sql
)

parameters

db_id ID database identifier
sql STRING SQL query

return values

rc ENUM( sqlite_return_codes ) return code

code sample

local SQLITE_OK = 0
local SQLITE_ERROR = 1

local sql = "CREATE TABLE users (name varchar(64), age int not null)"
local rc = gh_sqlite3.db_exec(db_id, sql)

if (rc == SQLITE_ERROR) then
    print("SQL error 1")
end

db_finalize

Frees resources allocated by db_prepare().

syntax

rc = gh_sqlite3.db_finalize (
db_id
)

parameters

db_id ID database identifier

return values

rc ENUM( sqlite_return_codes ) return code

code sample

rc = gh_sqlite3.db_finalize(db_id)

db_get_column_count

Gets the number of columns in a result set.

syntax

num_columns, rc = gh_sqlite3.db_get_column_count (
db_id
)

parameters

db_id ID database identifier

return values

num_columns INTEGER number of columns
rc ENUM( sqlite_return_codes ) return code

code sample

local num_columns, rc = gh_sqlite3.db_get_column_count(db_id)

db_get_column_name

Gets the name of a column.

syntax

name = gh_sqlite3.db_get_column_name (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

name STRING column name

code sample

name = gh_sqlite3.db_get_column_name(db_id, col_index)

db_get_column_type

Gets the type of a column in a result set.

syntax

type = gh_sqlite3.db_get_column_type (
db_id,
col_index
)

parameters

db_id ID database identifier
col_index INTEGER index of the column

return values

type ENUM( sqlite_column_type ) type of a column

code sample

local SQLITE_INTEGER = 1
local SQLITE_FLOAT = 2
local SQLITE_TEXT = 3
local SQLITE_BLOB = 4

local c = 0 -- first column
local type = gh_sqlite3.db_get_column_type(db_id, c)

if (type == SQLITE_TEXT) then
    local v = gh_sqlite3.db_column_get_text1024(db_id, c)
    print("Column " .. c .. " - type: TEXT - value: " .. v)
elseif (type == SQLITE_INTEGER) then
    local v = gh_sqlite3.db_column_get_int(db_id, c)
    print("Column " .. c .. " - type: INTEGER - value: " .. v)
elseif (type == SQLITE_FLOAT) then
    local v = gh_sqlite3.db_column_get_double(db_id, c)
    print("Column " .. c .. " - type: FLOAT - value: " .. v)
elseif (type == SQLITE_BLOB) then
    local size, dataptr = gh_sqlite3.db_column_get_blob(db_id, c)
    print("Column " .. c .. " - type: BLOB - size: " .. size)
end

db_get_errcode

Gets the last error code.

syntax

res_code = gh_sqlite3.db_get_errcode (
db_id
)

parameters

db_id ID database identifier

return values

res_code ENUM( sqlite_primary_result_codes ) primary result code

code sample

errcode = gh_sqlite3.db_get_errcode(db_id)

db_get_extended_errcode

Gets the last extended error code.
Extended error codes must be enabled with db_enable_extended_result_codes().

syntax

ext_res_code = gh_sqlite3.db_get_extended_errcode (
db_id
)

parameters

db_id ID database identifier

return values

ext_res_code ENUM( sqlite_extended_result_codes ) extended result code

code sample

errcode = gh_sqlite3.db_get_extended_errcode(db_id)

db_get_last_insert_rowid

Gets the last insert ID.

syntax

gh_sqlite3.db_get_last_insert_rowid (
db_id
)

parameters

db_id ID database identifier

return values

none

code sample

lastrowid = gh_sqlite3.db_get_last_insert_rowid(db_id)

db_get_version

Get the SQLite3 engine version.

syntax

int_ver, str_ver = gh_sqlite3.db_get_version()

parameters

none

return values

int_ver INTEGER numeric format of the version
str_ver STRING alphanumeric format of the version

code sample

int_ver, str_ver = gh_sqlite3.db_get_version()

db_open

Initializes and opens a database.

syntax

db_id, rc = gh_sqlite3.db_open (
db_filename
)

parameters

db_filename STRING absolute path of the database file

return values

db_id ID database identifier
rc ENUM( sqlite_return_codes ) return code

code sample

local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

local db_filename = demo_dir .. "database01.db"

db_id, rc = gh_sqlite3.db_open(db_filename)

db_open_v2

Initializes and opens a database.

syntax

db_id, rc = gh_sqlite3.db_open_v2 (
db_filename,
flags
)

parameters

db_filename STRING absolute path of the database file
flags ENUM( sqlite_open_flag ) additional flags that control the way the database is opened

return values

db_id ID database identifier
rc ENUM( sqlite_return_codes ) return code

code sample

local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101
local SQLITE_OPEN_READONLY = 1
local SQLITE_OPEN_READWRITE = 2
local SQLITE_OPEN_CREATE = 4
local SQLITE_OPEN_URI = 64
local SQLITE_OPEN_MEMORY = 128
local SQLITE_OPEN_NOMUTEX = 32768
local SQLITE_OPEN_FULLMUTEX = 65536
local SQLITE_OPEN_SHAREDCACHE = 131072
local SQLITE_OPEN_PRIVATECACHE = 262144

local flags = SQLITE_OPEN_READWRITE

local db_filename = demo_dir .. "database01.db"

db_id, rc = gh_sqlite3.db_open_v2(db_filename, flags)

db_prepare

Prepares an SQL request for later use with db_step().

syntax

rc = gh_sqlite3.db_prepare (
db_id,
sql
)

parameters

db_id ID database identifier
sql STRING SQL query

return values

rc ENUM( sqlite_return_codes ) return code

code sample

local SQLITE_OK = 0
local SQLITE_ERROR = 1

local sql = "SELECT * FROM users"
local rc = gh_sqlite3.db_prepare(db_id, sql)

if (rc == SQLITE_OK) then
    local num_columns = gh_sqlite3.db_get_column_count(db_id)
    ...
end

db_step

Evaluates a request prepared with db_prepare().

syntax

rc = gh_sqlite3.db_step (
db_id
)

parameters

db_id ID database identifier

return values

rc ENUM( sqlite_return_codes ) return code

code sample

local SQLITE_OK = 0
local SQLITE_ERROR = 1
local SQLITE_ROW = 100
local SQLITE_DONE = 101

rc = gh_sqlite3.db_step(db_id)
while (rc ~= SQLITE_DONE) do
    ...
end

gh_texture

Texture module

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

bind

Bind the texture to the renderer.

syntax

gh_texture.bind (
tex_id,
tex_unit
)

parameters

tex_id ID texture identifier
tex_unit INTEGER texture unit on which the texture is bound

return values

none

code sample

gh_texture.bind(tex_id, 0)

copy_sub_texture

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
)

parameters

src_tex_id ID source texture identifier
dst_tex_id ID destination texture identifier
x, y, width, height INTEGER start offset (x, y) and size of the sub texture

return values

new_dst_tex_id ID new texture identifier

code sample

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

create_1d

Creates an empty 1D texture.

syntax

tex_id = gh_texture.create_1d (
width,
pf
)

parameters

width INTEGER texture size
pf ENUM( pixel_format ) pixel format

return values

tex_id ID texture identifier

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

Creates an empty 2D texture.

syntax

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

parameters

width, height INTEGER texture size
pf ENUM( pixel_format ) pixel format

return values

tex_id ID texture identifier

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

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
)

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 ENUM( pixel_format ) pixel format
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

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

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
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)
pf ENUM( pixel_format ) pixel format
tex_unit INTEGER texture unit (for Direct3D 12 or Vulkan)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format

return values

tex_id ID texture identifier

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

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
)

parameters

filename STRING image filename
pf ENUM( pixel_format ) pixel format
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)

return values

tex_id ID texture identifier

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_v10

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_v10 (
filename,
pf,
gen_mipmaps,
compressed_format,
free_cpu_memory
)

parameters

filename STRING absolute path of the image file
pf ENUM( pixel_format ) pixel format
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format
free_cpu_memory BOOLEAN free CPU memory after uploading to GPU: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

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 free_gpu_memory = 0
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_v10(demo_dir .. "./data/tex.jpg", PF_U8_RGBA, gen_mipmaps, compression_format, free_gpu_memory)

create_from_file_v2

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
)

parameters

filename STRING image filename
pf ENUM( pixel_format ) pixel format
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

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

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
)

parameters

filename STRING image filename
pf ENUM( pixel_format ) pixel format
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compression BOOLEAN hardware compression: 1 (enabled) or 0 (disabled)
free_cpu_memory BOOLEAN frees the pixamp in CPU memory: 1 (true) or 0 (false)

return values

tex_id ID texture identifier

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

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
)

parameters

filename STRING absolute path of the image file
pf ENUM( pixel_format ) pixel format

return values

tex_id ID texture identifier

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

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
)

parameters

filename STRING absolute path of the image file
pf ENUM( pixel_format ) pixel format
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format

return values

tex_id ID texture identifier

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

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
)

parameters

filename STRING absolute path of the image file
pf ENUM( pixel_format ) pixel format
tex_unit INTEGER texture unit (for Direct3D 12 or Vulkan)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format

return values

tex_id ID texture identifier

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

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
)

parameters

filename STRING absolute path of the image file
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)
pf ENUM( pixel_format ) pixel format
tex_unit INTEGER texture unit (for Direct3D 12 or Vulkan)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format

return values

tex_id ID texture identifier

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

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
)

parameters

db_id ID database identifier
column INTEGER index of the column
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)
pf ENUM( pixel_format ) pixel format
tex_unit INTEGER texture unit (for Direct3D 12 or Vulkan)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format

return values

tex_id ID texture identifier

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

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
)

parameters

src_tex_id ID source texture identifier
x, y, width, height INTEGER start offset (x, y) and size of the sub texture

return values

new_dst_tex_id ID new texture identifier

code sample

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

create_from_zip_file

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
)

parameters

zip_filename STRING absolute path of the zip file
filename STRING image file in the zip archive
upload_to_gpu BOOLEAN uploads the pixmap into GPU memory: 1 (true) or 0 (false)
pf ENUM( pixel_format ) pixel format
tex_unit INTEGER texture unit (for Direct3D 12 or Vulkan)
gen_mipmaps BOOLEAN generates the mipmaps: 1 (true) or 0 (false)
compressed_format STRING compression format

return values

tex_id ID texture identifier

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

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

syntax

gh_texture.flip_horizontal (
tex_id
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_texture.flip_horizontal(tex_id)

get_gpu_memory_size

Gets the texture GPU memory size.

syntax

mem_size, compressed_mem_size = gh_texture.get_gpu_memory_size (
tex_id
)

parameters

tex_id ID 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(tex_id)

get_num_mipmaps

Returns the number of mipmap level for a texture.

syntax

n = gh_texture.get_num_mipmaps (
tex_id
)

parameters

tex_id ID texture identifier

return values

n INTEGER number of mipmap levels

code sample

n = gh_texture.get_num_mipmaps(tex_id)

get_size

Gets the texture size.

syntax

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

parameters

tex_id ID texture identifier

return values

width, height, depth INTEGER texture size

code sample

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

get_texel_1d

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
)

parameters

tex_id ID texture identifier
x_offset INTEGER offset inside the texture pixmap

return values

r, g, b, a REAL RGBA color value

code sample

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

get_texel_2d

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
)

parameters

tex_id ID texture identifier
x_offset, y_offset INTEGER offsets inside the texture pixmap

return values

r, g, b, a REAL RGBA color value

code sample

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

gpu_mem_to_cpu_mem

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
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_texture.gpu_mem_to_cpu_mem(tex_id)

gpu_memory_unload

Unloads the texture data from GPU memory.

syntax

ret = gh_texture.gpu_memory_unload (
tex_id
)

parameters

tex_id ID texture identifier

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

gh_texture.gpu_memory_unload(tex_id)

gpu_memory_upload

Uploads the texture data to GPU memory.

syntax

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

parameters

tex_id ID texture identifier
tex_unit INTEGER texture unit
create_srv INTEGER creates resource view (Direct3D 12)
free_cpu_memory BOOLEAN frees the CPU memory after upload: 1 (true) or 0 (false)

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

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

image_bind

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
)

parameters

tex_id ID texture identifier
tex_unit INTEGER texture unit on which the image is bound
access_type ENUM( tex_data_access ) specifies the red/write mode of the image

return values

none

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

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
)

parameters

dst_tex_id ID destination texture identifier
opa_tex_id ID opacity texture identifier

return values

none

code sample

gh_texture.inject_opacity_map(dst_tex_id, opa_tex_id)

renderer_update

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
)

parameters

tex_id ID texture identifier

return values

none

code sample

gh_texture.flip_horizontal(tex_id)

gh_texture.renderer_update(tex_id)

renderer_update2d

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

syntax

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

parameters

tex_id ID texture identifier
x_offset, y_offset INTEGER offsets inside the texture pixmap
width, height INTEGER size of the texture pixmap that will be uploaded

return values

none

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

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
)

parameters

tex_unit INTEGER texture unit on which a texture is bound

return values

none

code sample

tex_unit = 1
gh_texture.reset_texture_unit(tex_unit)

rt_color_bind_v2

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

syntax

gh_texture.rt_color_bind_v2 (
rt_id,
color_target_index,
tex_unit
)

parameters

rt_id ID render target identifier
color_target_index INTEGER index of the color target
tex_unit INTEGER texture unit on which the texture is bound

return values

none

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

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

syntax

gh_texture.rt_color_cubemap_bind (
rt_id,
tex_unit
)

parameters

rt_id ID render target identifier
tex_unit INTEGER texture unit on which the texture is bound

return values

none

code sample

tex_unit = 0
gh_texture.rt_color_cubemap_bind(rt_id, tex_unit)

rt_depth_bind

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

syntax

gh_texture.rt_depth_bind (
rt_id,
tex_unit
)

parameters

rt_id ID render target identifier
tex_unit INTEGER