Scripting API for GeeXLab 0.29.1.0

updated on 2019.09.21

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_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_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

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
)

parameters

av_id ID audio-video object identifier

return values

tex_id ID texture identifier

code sample

tex_id = gh_av.video_init_texture(av_id)

video_update_texture

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)

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

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)

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

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.

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_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_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_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

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

gpu_power_get_current_value

GTX 600/700: returns the current GPU power.

syntax

power = gh_gml.gpu_power_get_current_value (
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_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, "")

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.

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_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_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_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 = {}

InitTemperatures(temperatures)

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform1fv(gpuprog_id, "temperatures", 10, 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

lua

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

lua

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

return values

none

code sample

uv = {} -- array element: {x=0, y=0}

InitUV(uv)

gh_gpu_program.bind(gpuprog_id)
gh_gpu_program.uniform2fv(gpuprog_id, "uv", 10, 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

lua

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

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

lua

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

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_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 uniform name of the view matrix
uniform_name_proj_mat STRING uniform 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 uniform name of the view matrix
uniform_name_proj_mat STRING uniform name of the projection matrix
uniform_name_viewproj_mat STRING uniform 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_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 uniform name of the model view projection matrix
uniform_name_modelview_mat STRING uniform 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 uniform name of the matrix

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

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

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 ImGui 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 ImGui 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) circle

return values

none

code sample

local thickness = 2
local num_segments = 20
local 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 ImGui 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 ImGui 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) circle

return values

none

code sample

local thickness = 2
local filled = 1

gh_imgui.add_quad_to_drawlist(ax, ay, bx, by, cx, cy, dx, dy, 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)

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)

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)

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

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

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

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)

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

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)

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)

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_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_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_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_frame_rounding

Sets the frame corner rounding.
A value of 0 means a squared corner.

syntax

gh_imgui.set_frame_rounding (
x
)

parameters

x REAL size

return values

none

code sample

gh_imgui.set_frame_rounding(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_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_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)

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_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_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

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!")

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

gh_imgui.url (
link_caption,
link_url,
tooltip_text
)

parameters

link_caption STRING caption
link_url STRING url (https://....)
tooltip_text STRING tool tip (can be empty)

return values

none

code sample

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)

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 INTEGER size of the window
pos_x, pos_y INTEGER 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 INTEGER size of the window
pos_x, pos_y INTEGER 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)

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

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

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.

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

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

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)

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/")

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_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_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_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 bodiy 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_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_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_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_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_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)

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_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_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 texture unit on which the texture is bound

return values

none

code sample

tex_unit = 1
gh_texture.rt_depth_bind(rt_id, tex_unit)

rt_depth_cubemap_bind

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

syntax

gh_texture.rt_depth_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_depth_cubemap_bind(rt_id, tex_unit)

set_current_image_codec

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

syntax

gh_texture.set_current_image_codec (
codec_name
)

parameters

codec_name ENUM( tex_codec_name ) code name: 'FreeImage' or 'stb'

return values

none

code sample

gh_texture.set_current_image_codec("FreeImage")

set_texel_1d

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

syntax

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

parameters

tex_id ID texture identifier
x_offset INTEGER offset inside the texture pixmap
r, g, b, a REAL RGBA value

return values

none

code sample

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

set_texel_2d

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

syntax

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

parameters

tex_id ID texture identifier
x_offset, y_offset INTEGER offsets inside the texture pixmap
r, g, b, a REAL RGBA value

return values

none

code sample

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

share_texture_data

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

syntax

gh_texture.share_texture_data (
tex_id,
shared_tex_id
)

parameters

tex_id ID texture identifier
shared_tex_id ID shared texture identifier

return values

none

code sample

gh_texture.share_texture_data(tex_id, shared_tex_id)

update_gpu_memory_from_buffer

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

syntax

gh_texture.update_gpu_memory_from_buffer (
tex_id,
buff_ptr,
buff_size
)

parameters

tex_id ID texture identifier
buff_ptr POINTER pointer to the image buffer
buff_size INTEGER size in bytes of the buffer

return values

none

code sample

gh_texture.update_gpu_memory_from_buffer(tex_id, buffer, buffer_size)

update_gpu_memory_from_file

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

syntax

gh_texture.update_gpu_memory_from_file (
tex_id,
filename,
absolute_path
)

parameters

tex_id ID texture identifier
filename STRING image filename
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)

return values

none

code sample

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

write_to_file_v4

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

syntax

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

parameters

tex_id ID texture identifier
filename STRING absolute path of the saved image
flip_image BOOLEAN vertical flip of the image before saving: 1 (true) or 0 (false)
image_format STRING format/type of the image: jpg, bmp, png, tif, gif, tga
saving_options ENUM( saving_options ) saving options: quality_100, quality_90, quality_80, ..., quality_10

return values

none

code sample

gh_texture.set_current_image_codec("FreeImage")

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

gh_utils

Utility module

gh_utils is the module that provides various utility functions.

box_create

Creates a simple box.

syntax

box_id = gh_utils.box_create (
w, h, d,
r, g, b, a
)

parameters

w, h, d REAL width, height and depth of the box
r, g, b, a REAL RGBA color

return values

box_id ID box identifier

code sample

box_id = gh_utils.box_create(10.0, 10.0, 10.0,  1.0, 1.0, 0.0, 1.0)

box_update_size

Updates the size of a box.

syntax

gh_utils.box_update_size (
box_id,
w, h, d
)

parameters

box_id ID box identifier
w, h, d REAL width, height and depth of the box

return values

none

code sample

gh_utils.box_update_size(box_id, 12.0, 12.0, 12.0)

buffer_copy

Copies a source memory buffer to a destination memory buffer.

syntax

gh_utils.buffer_copy (
src_buff_ptr,
src_offset,
dst_buff_ptr,
dst_offset,
num_bytes
)

parameters

src_buff_ptr POINTER pointer to the source buffer
src_offset INTEGER offset in the source buffer in bytes
dst_buff_ptr POINTER pointer to the destination buffer
dst_offset INTEGER offset in the destination buffer in bytes
num_bytes INTEGER number of bytes that will be copied

return values

none

code sample

src_ptr, size = gh_utils.buffer_create(1024)
dst_ptr, size = gh_utils.buffer_create(1024)

...
gh_utils.buffer_create(src_ptr, 0, dst_ptr, 0, 1024)
...

buffer_crc32

Helper function to get the CRC32 hash code of a memory buffer.

syntax

hashcode = gh_utils.buffer_crc32 (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the line to read in bytes

return values

hashcode STRING hashcode of the buffer

code sample

filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

hashcode = gh_utils.buffer_crc32(buffer_ptr, buffer_size)

gh_utils.file_buffer_kill(buffer_ptr)

buffer_create

Creates an empty memory buffer.

syntax

buff_ptr, buff_size = gh_utils.buffer_create (
size
)

parameters

size INTEGER size in bytes.

return values

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

code sample

buffer_ptr, buffer_size = gh_utils.buffer_create(1024)
...
gh_utils.buffer_kill(buffer_ptr)

buffer_kill

Frees the pointer returned by buffer_create(), file_buffer_create() or zip_buffer_create.

syntax

gh_utils.buffer_kill (
buff_ptr
)

parameters

buff_ptr POINTER pointer to the buffer

return values

none

code sample

buffer_ptr, buffer_size = gh_utils.buffer_create(1024)
...
gh_utils.buffer_kill(buffer_ptr)

buffer_md5

Helper function to get the MD5 hash code of a memory buffer.

syntax

hashcode = gh_utils.buffer_md5 (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the line to read in bytes

return values

hashcode STRING hashcode of the buffer

code sample

filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

hashcode = gh_utils.buffer_md5(buffer_ptr, buffer_size)

gh_utils.file_buffer_kill(buffer_ptr)

buffer_read_1f

Reads a float from a memory buffer via a pointer.
The pointer must have been created by buffer_create(), zip_buffer_create() or file_buffer_create().

syntax

x, y = gh_utils.buffer_read_1f (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes

return values

x, y REAL value

code sample

filename = gh_utils.get_demo_dir() .. "data.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

offset = 0
x = gh_utils.buffer_read_1f(buffer_ptr, offset)
...
gh_utils.file_buffer_kill(buffer_ptr)

buffer_read_2f

Reads a vec2 from a memory buffer via a pointer.
The pointer must have been created by buffer_create(), zip_buffer_create() or file_buffer_create().

syntax

x, y = gh_utils.buffer_read_2f (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes

return values

x, y REAL value

code sample

filename = gh_utils.get_demo_dir() .. "data.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

offset = 0
x, y = gh_utils.buffer_read_2f(buffer_ptr, offset)
...
gh_utils.file_buffer_kill(buffer_ptr)

buffer_read_3f

Reads a vec3 from a memory buffer via a pointer.
The pointer must have been created by buffer_create(), zip_buffer_create() or file_buffer_create().

syntax

x, y, z = gh_utils.buffer_read_3f (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes

return values

x, y, z REAL value

code sample

filename = gh_utils.get_demo_dir() .. "data.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

offset = 0
x, y, z = gh_utils.buffer_read_3f(buffer_ptr, offset)
...
gh_utils.file_buffer_kill(buffer_ptr)

buffer_read_4f

Reads a vec4 from a memory buffer via a pointer.
The pointer must have been created by buffer_create(), zip_buffer_create() or file_buffer_create().

syntax

x, y, z, w = gh_utils.buffer_read_4f (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes

return values

x, y, z, w REAL value

code sample

filename = gh_utils.get_demo_dir() .. "data.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

offset = 0
x, y, z, w = gh_utils.buffer_read_4f(buffer_ptr, offset)
...
gh_utils.file_buffer_kill(buffer_ptr)

buffer_read_byte

Reads a byte from a memory buffer via a pointer.
The pointer must have been created by zip_buffer_create() or file_buffer_create().

syntax

x = gh_utils.buffer_read_byte (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes

return values

x INTEGER value of the byte

code sample

filename = gh_utils.get_demo_dir() .. "config.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

-- read the first byte:
x = gh_utils.buffer_read_byte(buffer_ptr, 0)

-- read the second byte:
x = gh_utils.buffer_read_byte(buffer_ptr, 1)

...
...
...

gh_utils.file_buffer_kill(buffer_ptr)

buffer_read_line

Reads a line from a memory buffer via a pointer.
The pointer must have created by zip_buffer_create() or file_buffer_create().

syntax

line, line_size = gh_utils.buffer_read_line (
buff_ptr,
buff_size,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
offset INTEGER offset of the line to read in bytes

return values

line STRING content of a line
line_size INTEGER size of the line in bytes. If line_size==0, the end of the buffer is reached.

code sample

filename = gh_utils.get_demo_dir() .. "config.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

line_offset = 0
-- read the first line:
line, line_size = gh_utils.buffer_read_line(buffer_ptr, buffer_size, line_offset)

line_offset = line_offset + line_size
-- read the second line:
line, line_size = gh_utils.buffer_read_line(buffer_ptr, buffer_size, line_offset)
...
...
...
gh_utils.file_buffer_kill(buffer_ptr)

buffer_sha1

Helper function to get the SHA1 hash code of a memory buffer.

syntax

hashcode = gh_utils.buffer_sha1 (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the line to read in bytes

return values

hashcode STRING hashcode of the buffer

code sample

filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

hashcode = gh_utils.buffer_sha1(buffer_ptr, buffer_size)
gh_utils.file_buffer_kill(buffer_ptr)

buffer_sha256

Helper function to get the SHA256 hash code of a memory buffer.

syntax

hashcode = gh_utils.buffer_sha256 (
buff_ptr,
offset
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the line to read in bytes

return values

hashcode STRING hashcode of the buffer

code sample

filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

hashcode = gh_utils.buffer_sha256(buffer_ptr, buffer_size)
gh_utils.file_buffer_kill(buffer_ptr)

buffer_to_file

Save the content of a memory buffer into a file.

syntax

ret = gh_utils.buffer_to_file (
buff_ptr,
buff_size,
dst_filename
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes
dst_filename STRING absolute path of the file on the file system

return values

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

code sample

dst_filename = gh_utils.get_demo_dir() .. "image01.jpg"

if (gh_utils.buffer_to_file(buffer, buffer_size, dst_filename) == 1) then
    -- OK!
end

buffer_write_1f

Writes a float to a memory buffer via a pointer.
The pointer must have been created by zip_buffer_create() or file_buffer_create().

syntax

gh_utils.buffer_write_1f (
buff_ptr,
offset,
x
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes
x REAL value

return values

none

code sample

buffer_ptr, buffer_size = gh_utils.buffer_create(1024)

x = 3.14
gh_utils.buffer_write_1f(buffer_ptr, 0, x)
...
gh_utils.buffer_to_file(buffer_ptr, buffer_size, dst_filename)

gh_utils.buffer_kill(buffer_ptr)

buffer_write_2f

Writes a vec2 to a memory buffer via a pointer.
The pointer must have been created by zip_buffer_create() or file_buffer_create().

syntax

gh_utils.buffer_write_2f (
buff_ptr,
offset,
x, y
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes
x, y REAL value

return values

none

code sample

buffer_ptr, buffer_size = gh_utils.buffer_create(1024)

x = 3.14
y = 1.22
gh_utils.buffer_write_2f(buffer_ptr, 0, x, y)
...
gh_utils.buffer_to_file(buffer_ptr, buffer_size, dst_filename)

gh_utils.buffer_kill(buffer_ptr)

buffer_write_3f

Writes a vec3 to a memory buffer via a pointer.
The pointer must have been created by zip_buffer_create() or file_buffer_create().

syntax

gh_utils.buffer_write_3f (
buff_ptr,
offset,
x, y, z
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes
x, y, z REAL value

return values

none

code sample

buffer_ptr, buffer_size = gh_utils.buffer_create(1024)

x = 3.14
y = 1.22
z = -0.57
gh_utils.buffer_write_3f(buffer_ptr, 0, x, y, z)
...
gh_utils.buffer_to_file(buffer_ptr, buffer_size, dst_filename)

gh_utils.buffer_kill(buffer_ptr)

buffer_write_4f

Writes a vec4 to a memory buffer via a pointer.
The pointer must have been created by zip_buffer_create() or file_buffer_create().

syntax

gh_utils.buffer_write_4f (
buff_ptr,
offset,
x, y, z, w
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes
x, y, z, w REAL value

return values

none

code sample

buffer_ptr, buffer_size = gh_utils.buffer_create(1024)

x = 3.14
y = 1.22
z = -0.57
w = 1.0
gh_utils.buffer_write_4f(buffer_ptr, 0, x, y, z, w)
...
gh_utils.buffer_to_file(buffer_ptr, buffer_size, dst_filename)

gh_utils.buffer_kill(buffer_ptr)

buffer_write_byte

Writes a byte to a memory buffer via a pointer.
The pointer must have been created by zip_buffer_create() or file_buffer_create().

syntax

gh_utils.buffer_write_byte (
buff_ptr,
offset,
x
)

parameters

buff_ptr POINTER pointer to the buffer
offset INTEGER offset of the byte to read in bytes
x INTEGER value of the byte

return values

none

code sample

filename = gh_utils.get_demo_dir() .. "config.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)

-- write the first byte:
x = 100
gh_utils.buffer_write_byte(buffer_ptr, 0, x)

-- write the second byte:
x = 112
gh_utils.buffer_write_byte(buffer_ptr, 1, x)

...
...
...

gh_utils.buffer_to_file(buffer_ptr, buffer_size, dst_filename)

gh_utils.file_buffer_kill(buffer_ptr)

circle_create

Creates a simple circle in the XZ plane.

syntax

circle_id = gh_utils.circle_create (
radius,
subdivisions,
r, g, b, a
)

parameters

radius REAL radius
subdivisions INTEGER subdivisions
r, g, b, a REAL RGBA color

return values

circle_id ID circle identifier

code sample

circle_id = gh_utils.circle_create(10.0, 20, 1.0, 1.0, 0.0, 1.0)

circle_create_v2

Creates a simple circle.

syntax

circle_id = gh_utils.circle_create_v2 (
plane_type,
radius,
subdivisions,
r, g, b, a
)

parameters

plane_type ENUM( plane_type ) 0 (XZ), 1 (XY) or 2 (YZ)
radius REAL radius
subdivisions INTEGER subdivisions
r, g, b, a REAL RGBA color

return values

circle_id ID circle identifier

code sample

plane_type = 1
circle_id = gh_utils.circle_create_v2(plane_type, 10.0, 20, 1.0, 1.0, 0.0, 1.0)

circle_update_radius

Updates the radius of a circle.

syntax

gh_utils.circle_update_radius (
circle_id,
radius
)

parameters

circle_id ID circle identifier
radius REAL radius

return values

none

code sample

gh_utils.circle_update_radius(circle_id, 12.0)

clipboard_get_text

windows

Allows to get the content (text type) of the clipboard (currently on Windows only).

syntax

text, text_len = gh_utils.clipboard_get_text()

parameters

none

return values

text STRING text from the clipboard
text_len INTEGER length of the text

code sample

text, text_len = gh_utils.clipboard_get_text()

clipboard_set_text

windows

Allows to copy a string to the clipboard (currently on Windows only).

syntax

gh_utils.clipboard_set_text (
text
)

parameters

text STRING text to be copied in the clipboard

return values

none

code sample

gh_utils.clipboard_set_text("Hello!")

cpu_get_mem_available_size_mb

Returns the size of the available physical system memory in MB.

syntax

size = gh_utils.cpu_get_mem_available_size_mb()

parameters

none

return values

size INTEGER size in MB

code sample

mem_size_mb = gh_utils.cpu_get_mem_available_size_mb()

cpu_get_mem_size_mb

Returns the size of the physical system memory in MB.

syntax

size = gh_utils.cpu_get_mem_size_mb()

parameters

none

return values

size INTEGER size in MB

code sample

mem_size_mb = gh_utils.cpu_get_mem_size_mb()

cpu_get_name

windowslinuxmacos

Returns the CPU name - This function requires the GPU monitoring plugin (Windows, Linux and macOS).

syntax

str = gh_utils.cpu_get_name()

parameters

none

return values

str STRING CPU name

code sample

local cpu_name = gh_utils.cpu_get_name()

cpu_get_speed_mhz

windowslinuxmacos

Returns the CPU speed in MHz - This function requires the GPU monitoring plugin (Windows, Linux and macOS).

syntax

speed = gh_utils.cpu_get_speed_mhz()

parameters

none

return values

speed REAL CPU speed

code sample

local cpu_speed = gh_utils.cpu_get_speed_mhz()

cpu_usage_cleanup

windows

Cleans up the CPU usage code.
Should be called in a TERMINATE script (Windows only).

syntax

gh_utils.cpu_usage_cleanup()

parameters

none

return values

none

code sample

gh_utils.cpu_usage_cleanup()

cpu_usage_get_core_count

windows

Returns the number of CPU cores (Windows only).

syntax

num_cores = gh_utils.cpu_usage_get_core_count()

parameters

none

return values

num_cores INTEGER number of cores

code sample

local cores = gh_utils.cpu_usage_get_core_count()

cpu_usage_get_core_usage

windows

Returns the usage of a particular core (Windows only).

syntax

usage = gh_utils.cpu_usage_get_core_usage (
index
)

parameters

index INTEGER core index from 0 to cpu_usage_get_core_count()-1

return values

usage INTEGER core usage in percent

code sample

local core_index = 0
local usage = gh_utils.cpu_usage_get_core_usage(core_index)

cpu_usage_init

windows

Initializes the CPU usage code.
Should be called in INIT scripts (Windows only).

syntax

ret = gh_utils.cpu_usage_init()

parameters

none

return values

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

code sample

local ret = gh_utils.cpu_usage_init()

cpu_usage_update

windows

Updates the CPU usage.
Should be called in a FRAME script (Windows only).

syntax

gh_utils.cpu_usage_update()

parameters

none

return values

none

code sample

gh_utils.cpu_usage_update()

do_file_from_sqlite3_blob

Executes a script stored in a SQLite3 blob.

syntax

ret = gh_utils.do_file_from_sqlite3_blob (
db_id,
column
)

parameters

db_id ID database identifier
column INTEGER index of the column

return values

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

code sample

gh_utils.do_file_from_sqlite3_blob(db_id, column)

do_file_from_zip

Executes a script file stored in a zip archive.

syntax

ret = gh_utils.do_file_from_zip (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of the zip file
filename STRING script file in the zip archive

return values

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

code sample

zip_filename = demo_dir .. "data.zip"
gh_utils.do_file_from_zip(zip_filename, "scripts/init02.lua")

do_screenshot

opengl

Does a screenshot and write it to a file (JPEG file) - OpenGL and Vulkan renderers.

syntax

gh_utils.do_screenshot (
filename,
absolute_path
)

parameters

filename STRING relative path of the screenshot file
absolute_path BOOLEAN file path: 1 (absolute) or 0 (relative)

return values

none

code sample

gh_utils.do_screenshot("image.jpg", 0)

do_screenshot_v2

opengl

Does a screenshot and write it to a file (JPEG file) - OpenGL and Vulkan renderers.

syntax

gh_utils.do_screenshot_v2 (
filename,
flip_image
)

parameters

filename STRING relative path of the screenshot file
flip_image BOOLEAN vertical flip of the image before saving: 1 (true) or 0 (false)

return values

none

code sample

local demo_dir = gh_utils.get_demo_dir()
local flip_image = 1

gh_utils.do_screenshot_v2(demo_dir .. "image.jpg", flip_image)

do_screenshot_v3

opengl

Does a screenshot and write it to a file (JPEG file) - OpenGL and Vulkan renderers.

syntax

gh_utils.do_screenshot_v3 (
filename,
x, y, width, height,
flip_image
)

parameters

filename STRING relative path of the screenshot file
x, y, width, height INTEGER zone of the viewport to save
flip_image BOOLEAN vertical flip of the image before saving: 1 (true) or 0 (false)

return values

none

code sample

local demo_dir = gh_utils.get_demo_dir()
local flip_image = 1
local x = 0
local y = 0

gh_utils.do_screenshot_v3(demo_dir .. "image.jpg", x, y, winW, winH, flip_image)

do_screenshot_v4

opengl

Does a screenshot and write it to a file - OpenGL and Vulkan renderers.

syntax

gh_utils.do_screenshot_v4 (
filename,
x, y, width, height,
flip_image,
format,
saving_options
)

parameters

filename STRING relative path of the screenshot file
x, y, width, height INTEGER zone of the viewport to save
flip_image BOOLEAN vertical flip of the image before saving: 1 (true) or 0 (false)
format STRING image format (.jpg, .bmp, etc) (depends on the image plugin)
saving_options STRING saving options (depends on the image plugin)

return values

none

code sample

local demo_dir = gh_utils.get_demo_dir()
local flip_image = 1
local x = 0
local y = 0
format = "jpg"
saving_options = ""
gh_utils.do_screenshot_v4(demo_dir .. "image.jpg", x, y, winW, winH, flip_image, format, saving_options)

do_screenshot_v5

opengl

Does a screenshot and write it to a file - OpenGL and Vulkan renderers.

syntax

gh_utils.do_screenshot_v5 (
filename,
x, y, width, height,
flip_image,
format,
saving_options,
image_codec_name
)

parameters

filename STRING relative path of the screenshot file
x, y, width, height INTEGER zone of the viewport to save
flip_image BOOLEAN vertical flip of the image before saving: 1 (true) or 0 (false)
format STRING image format (.jpg, .bmp, etc) (depends on the image plugin)
saving_options STRING saving options (depends on the image plugin)
image_codec_name STRING name of the image plugin used to save the image: stb, FreeImage, ImageMagick.

return values

none

code sample

local demo_dir = gh_utils.get_demo_dir()
local flip_image = 1
local x = 0
local y = 0
format = "jpg"
saving_options = ""
image_codec_name = "FreeImage" -- default codec: "stb"
gh_utils.do_screenshot_v4(demo_dir .. "image.jpg", x, y, winW, winH, flip_image, format, saving_options, image_codec_name)

drop_files_get_file_by_index

windows

Returns the name of a particular file that has been dropped on the application.
This function is useful in a DRAG_N_DROP script (Windows only).

syntax

filename = gh_utils.drop_files_get_file_by_index (
index
)

parameters

index INTEGER index of the file: from 0 to drop_files_get_num_files()-1

return values

filename STRING name of a dropped file

code sample

num_files = gh_utils.drop_files_get_num_files()

if (num_files > 0) then
    -- Gets the first dropped file:
    filename = gh_utils.drop_files_get_file_by_index(0)
end

drop_files_get_num_files

windows

Returns the number of files that have been dropped on the application.
This function is useful in a DRAG_N_DROP script (Windows only).

syntax

num_dropped = gh_utils.drop_files_get_num_files()

parameters

none

return values

num_dropped INTEGER number of dropped files

code sample

num_files = gh_utils.drop_files_get_num_files()

dylib_frame

Calls the frame function of a dynamic library.

syntax

gh_utils.dylib_frame (
dylib_id,
elapsed_time,
data
)

parameters

dylib_id ID dylib identifier
elapsed_time REAL elapsed time in seconds
data STRING user data

return values

none

code sample

gh_utils.dylib_frame(dylib_id, elapsed_time, "")

dylib_get_message

Gets a message.
Allows to communicate with the dylib.

syntax

message = gh_utils.dylib_get_message (
dylib_id
)

parameters

dylib_id ID dylib identifier

return values

message STRING message

code sample

message = gh_utils.dylib_get_message(dylib_id)

dylib_load

Loads a dynamic library.
Check the forum for more information about loading dynamic libraries.

syntax

dylib_id = gh_utils.dylib_load (
dylib_filename
)

parameters

dylib_filename STRING absolute path of the dynamic lib

return values

dylib_id ID dylib identifier

code sample

dylib_id = gh_utils.dylib_load("/Users/toto/my3dcode.dylib")

dylib_resize

Calls the frame function of a dynamic library.

syntax

gh_utils.dylib_resize (
dylib_id,
width, height,
data
)

parameters

dylib_id ID dylib identifier
width, height INTEGER width and height of the 3D window
data STRING user data

return values

none

code sample

gh_utils.dylib_resize(dylib_id, width, height, "")

dylib_set_message

Sets a message.
Allows to communicate with the dylib.

syntax

gh_utils.dylib_set_message (
dylib_id,
message
)

parameters

dylib_id ID dylib identifier
message STRING message

return values

none

code sample

message = "....."

gh_utils.dylib_set_message(dylib_id, message)

dylib_start

Calls the start function of a dynamic library.

syntax

gh_utils.dylib_start (
dylib_id,
width, height,
data
)

parameters

dylib_id ID dylib identifier
width, height INTEGER width and height of the 3D window
data STRING user data

return values

none

code sample

gh_utils.dylib_start(dylib_id, width, height, "")

dylib_stop

Calls the stop function of a dynamic library.

syntax

gh_utils.dylib_stop (
dylib_id,
data
)

parameters

dylib_id ID dylib identifier
data STRING user data

return values

none

code sample

gh_utils.dylib_stop(dylib_id, "")

dylib_unload

Unloads a dynamic library.

syntax

gh_utils.dylib_unload (
dylib_id
)

parameters

dylib_id ID dylib identifier

return values

none

code sample

gh_utils.dylib_unload(dylib_id)

exe_from_buffer

Executes a script from a memory buffer.

syntax

ret = gh_utils.exe_from_buffer (
buff_ptr,
buff_size
)

parameters

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

return values

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

code sample

local demo_dir = gh_utils.get_demo_dir()
filename = demo_dir .. "assets/init_textures.lua"

buffer, buffer_size = gh_utils.file_buffer_create(filename)

if (gh_utils.exe_from_buffer(buffer, buffer_size) == 1) then
    -- ok
end

gh_utils.file_buffer_kill(buffer)

exe_script

Executes a script.

syntax

gh_utils.exe_script (
name,
threaded
)

parameters

name STRING name of the script
threaded BOOLEAN runs the script in a separate system thread: 1 (enabled) or 0 (disabled)

return values

none

code sample

local threaded = 0
gh_utils.exe_script("init_meshes", threaded)

exe_script_v2

Executes a script.

syntax

gh_utils.exe_script_v2 (
name,
threaded,
create_worker_wind3d
)

parameters

name STRING name of the script
threaded BOOLEAN runs the script in a separate system thread: 1 (enabled) or 0 (disabled)
create_worker_wind3d BOOLEAN creates a worker 3D window: 1 (yes) or 0 (no). The worker 3D window is required if you plan to call an OpenGL related function in the threaded script

return values

none

code sample

local threaded = 1
local create_worker_wind3d = 0

gh_utils.exe_script_v2("load_textures_cpu", threaded, create_worker_wind3d)

exe_script_v3

Executes a script.

syntax

gh_utils.exe_script_v3 (
name,
threaded,
create_worker_wind3d,
thread_affinity_mask
)

parameters

name STRING name of the script
threaded BOOLEAN runs the script in a separate system thread: 1 (enabled) or 0 (disabled)
create_worker_wind3d BOOLEAN creates a worker 3D window: 1 (yes) or 0 (no). The worker 3D window is required if you plan to call an OpenGL related function in the threaded script
thread_affinity_mask INTEGER specifies the affinity mask for the thread. Only on Windows. A thread affinity mask is a bit vector in which each bit represents a logical processor. Set this mask to 0 to disable it.

return values

none

code sample

local threaded = 1
local create_worker_wind3d = 0
local thread_affinity_mask = 0

gh_utils.exe_script_v3("load_textures_cpu", threaded, create_worker_wind3d, thread_affinity_mask)

exe_string

Executes a script.

syntax

ret = gh_utils.exe_string (
lua_python_commands
)

parameters

lua_python_commands STRING commands in Lua or Python

return values

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

code sample

gh_utils.exe_string("demo_folder = gh_utils.get_demo_dir()")
print(demo_folder)

extract_dir_from_filename

Utility function that extracts a path / folder from a file name.

syntax

filename = gh_utils.extract_dir_from_filename (
filename
)

parameters

filename STRING filename

return values

filename STRING filename of the main zip archive

code sample

folder = gh_utils.extract_dir_from_filename(filename)

file_buffer_create

Gets a pointer to the memory buffer of a file stored in the file system.

syntax

buff_ptr, buff_size = gh_utils.file_buffer_create (
filename
)

parameters

filename STRING absolute path of the file

return values

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

code sample

filename = gh_utils.get_demo_dir() .. "config.txt"

buffer_ptr, buffer_size = gh_utils.file_buffer_create(filename)
...
gh_utils.buffer_kill(buffer_ptr)

file_crc32

Helper function to get the CRC32 hash code of a file on the disk or in a zip file.

syntax

crc32, crc32_str = gh_utils.file_crc32 (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of a zip file. Optional
filename STRING absolute or relative path of the file

return values

crc32 INTEGER CRC32 code
crc32_str STRING string version of the CRC32 code

code sample

zip_filename = ""
filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

crc32, crc32_str = gh_utils.file_crc32(zip_filename, filename)

file_md5

Helper function to get the MD5 hash code of a file on the disk or in a zip file.

syntax

hashcode = gh_utils.file_md5 (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of a zip file. Optional
filename STRING absolute or relative path of the file

return values

hashcode STRING hashcode of the file

code sample

zip_filename = ""
filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

hashcode = gh_utils.file_md5(zip_filename, filename)

file_sha1

Helper function to get the SHA1 hash code of a file on the disk or in a zip file.

syntax

hashcode = gh_utils.file_sha1 (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of a zip file. Optional
filename STRING absolute or relative path of the file

return values

hashcode STRING hashcode of the file

code sample

zip_filename = ""
filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

hashcode = gh_utils.file_sha1(zip_filename, filename)

file_sha256

Helper function to get the SHA-256 hash code of a file on the disk or in a zip file.

syntax

hashcode = gh_utils.file_sha256 (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of a zip file. Optional
filename STRING absolute or relative path of the file

return values

hashcode STRING hashcode of the file

code sample

zip_filename = ""
filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

hashcode = gh_utils.file_sha256(zip_filename, filename)

file_size

Helper function to get the size of a file on the disk or in a zip file.

syntax

size = gh_utils.file_size (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of a zip file. Optional
filename STRING absolute or relative path of the file

return values

size INTEGER size of the file in bytes

code sample

zip_filename = ""
filename = gh_utils.get_demo_dir() .. "assets/image01.jpg"

size = gh_utils.file_size(zip_filename, filename)

font_create

Creates a new font.

syntax

font_id = gh_utils.font_create (
font_name,
height
)

parameters

font_name STRING TrueType font name, ex: Arial, Verdana
height INTEGER font height

return values

font_id ID font identifier

code sample

font_id = gh_utils.font_create("Arial", 14)

font_render

Renders (draws) a text.

syntax

gh_utils.font_render (
font_id,
x, y,
r, g, b, a,
text
)

parameters

font_id ID font identifier
x, y INTEGER X and Y start offsets in the current viewport
r, g, b, a REAL RGBA color of the text
text STRING text to render

return values

none

code sample

gh_utils.font_set_viewport_info(font_id, 0, 0, width, height)

gh_utils.font_render(font, 10, 40, 0.2, 1.0, 0.0, 1.0, string.format("Image filename: %s", texture_filename))

font_render3d

Renders (draws) a text at a 3D position.

syntax

gh_utils.font_render3d (
font_id,
x, y, z,
r, g, b, a,
text
)

parameters

font_id ID font identifier
x, y, z REAL 3D position of the beginning of the text
r, g, b, a REAL RGBA color of the text
text STRING text to render

return values

none

code sample

gh_utils.font_render3d(font_id, 0, 20.0, -20.0, 0.2, 1.0, 0.0, 1.0, "V1")

font_set_viewport_info

Sets the viewport information.
You have to call this function when the window is resized.

syntax

gh_utils.font_set_viewport_info (
font_id,
x, y,
width, height
)

parameters

font_id ID font identifier
x, y INTEGER viewport offsets
width, height INTEGER viewport size

return values

none

code sample

gh_utils.font_set_viewport_info(font_id, 0, 0, width, height)

ftgl_font_add_text2d

Adds a 2D text in a font.

syntax

gh_utils.ftgl_font_add_text2d (
font_id,
x, y,
r, g, b, a,
text
)

parameters

font_id ID font identifier
x, y INTEGER screen coordiantes of the beginning of the text
r, g, b, a REAL color of the text
text STRING text

return values

none

code sample

gh_utils.ftgl_font_add_text2d(font_id, 10, 20, 1.0, 0.0, 0.0, 1.0, "GeeXLab - line1")
gh_utils.ftgl_font_add_text2d(font_id, 10, 40, 1.0, 0.0, 0.0, 1.0, "GeeXLab - line2")

ftgl_font_add_text3d

Adds a 3D text in a font.

syntax

gh_utils.ftgl_font_add_text3d (
font_id,
x, y, z,
r, g, b, a,
text
)

parameters

font_id ID font identifier
x, y, z REAL 3D position of the beginning of the text
r, g, b, a REAL color of the text
text STRING text

return values

none

code sample

gh_utils.ftgl_font_add_text3d(font_id, x, y, z, 1.0, 0.0, 0.0, 1.0, "GeeXLab - line1")
gh_utils.ftgl_font_add_text2d(font_id, x+20, y-30, z-30, 1.0, 0.0, 0.0, 1.0, "GeeXLab - line2")

ftgl_font_clear

Clears all 2D texts in a font.
Useful with dynamic texts

syntax

gh_utils.ftgl_font_clear (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_utils.ftgl_font_clear(font_id)

gh_utils.ftgl_font_add_text2d(font_id, 10, 20, 1.0, 0.0, 0.0, 1.0, string.format("Elapsed time: %.3f sec.", elapsed_time))

gh_utils.ftgl_font_render(font_id)

ftgl_font_create

Creates a font object from a font texture.

syntax

font_id = gh_utils.ftgl_font_create (
font_tex_id
)

parameters

font_tex_id ID font texture identifier

return values

font_id ID font identifier

code sample

font_id = gh_utils.ftgl_font_create(font_tex_id)

ftgl_font_kill

Kills a font (TERMINATE script).

syntax

gh_utils.ftgl_font_kill (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_utils.ftgl_font_kill(font_id)

ftgl_font_render

Renders a 2D font.

syntax

gh_utils.ftgl_font_render (
font_id
)

parameters

font_id ID font identifier

return values

none

code sample

gh_utils.ftgl_font_clear(font_id)

gh_utils.ftgl_font_add_text2d(font_id, 10, 20, 1.0, 0.0, 0.0, 1.0, string.format("Elapsed time: %.3f sec.", elapsed_time))

gh_utils.ftgl_font_render(font_id)

ftgl_font_texture_kill

Kills a font texture (TERMINATE script).

syntax

gh_utils.ftgl_font_texture_kill (
font_tex_id
)

parameters

font_tex_id ID font texture identifier

return values

none

code sample

gh_utils.ftgl_font_texture_kill(font_tex_id)

ftgl_font_texture_load

Loads a font texture from a TrueType (TTF) font file.

syntax

font_tex_id = gh_utils.ftgl_font_texture_load (
filename,
height,
tex_width, tex_height,
_5, _6
)

parameters

filename STRING TrueType font file
height INTEGER height of font glyphs
tex_width, tex_height INTEGER width and height of the font texture
_5, _6 INTEGER reserved

return values

font_tex_id ID font texture identifier

code sample

font_tex_id = gh_utils.ftgl_font_texture_load(filename, 50, 1024, 1024, 0, 0)

get_app_dir

Gets the directory of GeeXLab.

syntax

dir = gh_utils.get_app_dir()

parameters

none

return values

dir STRING directory

code sample

app_dir = gh_utils.get_app_dir()

get_app_version

Returns the four numbers that define the GeeXLab version.

syntax

major, minor, patch, build = gh_utils.get_app_version()

parameters

none

return values

major, minor, patch, build INTEGER version of GeeXLab

code sample

major, minor, patch, build = gh_utils.get_app_version()

get_command_line

Returns the command line used to lauch GeeXLab.

syntax

command_line = gh_utils.get_command_line()

parameters

none

return values

command_line STRING command line

code sample

command_line = gh_utils.get_command_line()

get_date_str

Gets the date with the following format: Y.M.D.h.m.s.
Handy funtion for naming files.

syntax

date = gh_utils.get_date_str()

parameters

none

return values

date STRING date (Y.M.D.h.m.s)

code sample

date = gh_utils.get_date_str()

get_demo_dir

Gets the directory of the current scene file.

syntax

dir = gh_utils.get_demo_dir()

parameters

none

return values

dir STRING directory of the current scene file

code sample

demo_dir = gh_utils.get_demo_dir()

get_demo_zip_filename

Gets the file name of the main zip archive (the zip archive that contains the main XML demo).

syntax

demo_zip_filename = gh_utils.get_demo_zip_filename()

parameters

none

return values

demo_zip_filename STRING filename of the main zip archive

code sample

main_zip_filename = gh_utils.get_demo_zip_filename()

get_elapsed_time

Gets the elapsed time since the start of the current scene.

syntax

elapsed_time = gh_utils.get_elapsed_time()

parameters

none

return values

elapsed_time REAL elapsed time in seconds

code sample

local elapsed_time = gh_utils.get_elapsed_time()

get_lib_dir

Gets the directory of GeeXLab common librairies (Lua and Python) used by demos.
The defaulkt location is {GeeXLab_folder}/libs/.

syntax

dir = gh_utils.get_lib_dir()

parameters

none

return values

dir STRING directory

code sample

lib_dir = gh_utils.get_lib_dir()

get_os_info

Gets some basic information about the host Operating System (OS).

syntax

major, minor, build, name, codename = gh_utils.get_os_info()

parameters

none

return values

major, minor, build INTEGER version of the OS
name, codename STRING string identication of the OS

code sample

name, codename, major, minor, build = gh_utils.get_os_info()

get_platform

Returns the platform: 1 (Windows), 2 (macOS), 3 (Linux), 4 (Raspberry Pi), 5 (ASUS Tinker Board)

syntax

platform = gh_utils.get_platform()

parameters

none

return values

platform ENUM( platform ) 1 (Windows), 2 (macOS), 3 (Linux), 4 (Raspberry Pi), 5 (ASUS Tinker Board)

code sample

platform = gh_utils.get_platform()

get_platform_name

Returns the platform name: Windows xx-bit, macOS 10.x, Linux xx-bit, Raspberry Pi.

syntax

platform_name = gh_utils.get_platform_name()

parameters

none

return values

platform_name STRING the name of the platform

code sample

platform_name = gh_utils.get_platform_name()

get_time_step

Returns the time step between two consecutive frames.

syntax

dt = gh_utils.get_time_step()

parameters

none

return values

dt REAL time step in seconds

code sample

local dt = gh_utils.get_time_step()

get_uptime

Gets the up time since the launch of GeeXLab.

syntax

uptime = gh_utils.get_uptime()

parameters

none

return values

uptime REAL up time in seconds

code sample

local uptime = gh_utils.get_uptime()

global_array_char_alloc

Allocates a global array of string.
This array is readable and writable by any script in any thread.

syntax

gh_utils.global_array_char_alloc (
num_elements,
max_string_len
)

parameters

num_elements INTEGER number of elements
max_string_len INTEGER max length of a string in a the array

return values

none

code sample

num_elements = 256
max_string_len = 1024

gh_utils.global_array_char_alloc(num_elements, max_string_len)

global_array_char_get

Reads a value from the global char array.

syntax

value = gh_utils.global_array_char_get (
index
)

parameters

index INTEGER index in the array

return values

value STRING value

code sample

index = 2
value = gh_utils.global_array_char_get(index)

global_array_char_set

Writes a value to the global char array.

syntax

gh_utils.global_array_char_set (
index,
value
)

parameters

index INTEGER index in the array
value STRING value

return values

none

code sample

index = 2
value = "Hello"

gh_utils.global_array_char_set(index, value)

global_array_float_alloc

Allocates a global array of floats.
This array is readable and writable by any script in any thread.

syntax

gh_utils.global_array_float_alloc (
num_elements
)

parameters

num_elements INTEGER number of elements

return values

none

code sample

num_elements = 256
gh_utils.global_array_float_alloc(num_elements)

global_array_float_get

Reads a value from the global float array.

syntax

value = gh_utils.global_array_float_get (
index
)

parameters

index INTEGER index in the array

return values

value REAL value

code sample

index = 2
value = gh_utils.global_array_float_get(index)

global_array_float_set

Writes a value to the global float array.

syntax

gh_utils.global_array_float_set (
index,
value
)

parameters

index INTEGER index in the array
value REAL value

return values

none

code sample

index = 2
value = 3.14

gh_utils.global_array_float_set(index, value)

global_array_int_alloc

Allocates a global array of integers.
This array is readable and writable by any script in any thread.

syntax

gh_utils.global_array_int_alloc (
num_elements
)

parameters

num_elements INTEGER number of elements

return values

none

code sample

num_elements = 256
gh_utils.global_array_int_alloc(num_elements)

global_array_int_get

Reads a value from the global int array.

syntax

value = gh_utils.global_array_int_get (
index
)

parameters

index INTEGER index in the array

return values

value INTEGER value

code sample

index = 2
value = gh_utils.global_array_int_get(index)

global_array_int_set

Writes a value to the global int array.

syntax

gh_utils.global_array_int_set (
index,
value
)

parameters

index INTEGER index in the array
value INTEGER value

return values

none

code sample

index = 2
value = 10

gh_utils.global_array_int_set(index, value)

grid_create

Creates a grid object.

syntax

grid_id = gh_utils.grid_create()

parameters

none

return values

grid_id ID grid identifier

code sample

grid_id = gh_utils.grid_create()

grid_set_display_lines_options

Sets various grid options for rendering.

syntax

gh_utils.grid_set_display_lines_options (
grid_id,
display_main_lines,
display_lines
)

parameters

grid_id ID grid identifier
display_main_lines BOOLEAN display of main lines (axis + border): 1 (enabled) or 0 (disabled)
display_lines BOOLEAN display of lines: 1 (enabled) or 0 (disabled)

return values

none

code sample

gh_utils.grid_set_display_lines_options(grid_id, 1, 1)

grid_set_geometry_params

Sets grid sizes and subdivisions.

syntax

gh_utils.grid_set_geometry_params (
grid_id,
x_size, z_size,
x_div, z_div
)

parameters

grid_id ID grid identifier
x_size, z_size REAL size
x_div, z_div INTEGER subdivisions

return values

none

code sample

gh_utils.grid_set_geometry_params(grid_id, 20, 20, 10, 10)

grid_set_lines_color

Sets grid color.

syntax

gh_utils.grid_set_lines_color (
grid_id,
r, g, b, a
)

parameters

grid_id ID grid identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_utils.grid_set_lines_color(grid_id, 0.7, 0.7, 0.7, 1)

grid_set_main_lines_color

Sets the color of main lines.

syntax

gh_utils.grid_set_main_lines_color (
grid_id,
r, g, b, a
)

parameters

grid_id ID grid identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_utils.grid_set_main_lines_color(grid_id, 1.0, 1.0, 0.0, 1)

grid_set_main_x_axis_color

Sets the color of the main X axis.

syntax

gh_utils.grid_set_main_x_axis_color (
grid_id,
r, g, b, a
)

parameters

grid_id ID grid identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_utils.grid_set_main_x_axis_color(grid_id, 1.0, 0.0, 0.0, 1)

grid_set_main_z_axis_color

Sets the color of the main Z axis.

syntax

gh_utils.grid_set_main_z_axis_color (
grid_id,
r, g, b, a
)

parameters

grid_id ID grid identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_utils.grid_set_main_z_axis_color(grid_id, 0.0, 0.0, 1.0, 1)

hex_color_to_rgb

Converts an HTML style color to three RGB components.

syntax

r, g, b = gh_utils.hex_color_to_rgb (
html_color
)

parameters

html_color STRING color in HTML style

return values

r, g, b STRING RGB color

code sample

r, g, b = gh_utils.hex_color_to_rgb("#ff0044")

is_64bit

Checks if the host application is a 64-bit or a 32-bit application.

syntax

state = gh_utils.is_64bit()

parameters

none

return values

state BOOLEAN 1 (64-bit) or 0 (otherwise)

code sample

app_64bit = gh_utils.is_64bit()

is_luajit

luawindows

Checks if the LuaJIT engine is used in place of the regular Lua engine (Windows only).

syntax

state = gh_utils.is_luajit()

parameters

none

return values

state BOOLEAN 1 (LuaJIT) or 0 (otherwise)

code sample

is_luajit = gh_utils.is_luajit()

is_rpi

Checks if the platform is Raspberry Pi (RPi).

syntax

state = gh_utils.is_rpi()

parameters

none

return values

state BOOLEAN 1 if RPi and 0 otherwise

code sample

rpi = gh_utils.is_rpi()

line_create

Creates a simple line.

syntax

line_id = gh_utils.line_create()

parameters

none

return values

line_id ID line identifier

code sample

line_id = gh_utils.line_create()

gh_utils.line_set_start_position(line_id, -10, -10, 0.0)
gh_utils.line_set_start_color(line_id, 1, 1, 0, 1)
gh_utils.line_set_end_position(line_id, 10, 10, 0.0)
gh_utils.line_set_end_color(line_id, 1, 1, 1, 1)

line_set_end_color

Sets the end color of a line.

syntax

gh_utils.line_set_end_color (
line_id,
r, g, b, a
)

parameters

line_id ID line identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_utils.line_set_end_color(line_id, 1, 1, 0, 1)

line_set_end_position

Sets the end position of a line.

syntax

gh_utils.line_set_end_position (
line_id,
x, y, z
)

parameters

line_id ID line identifier
x, y, z REAL position

return values

none

code sample

gh_utils.line_set_end_position(line_id, 10, 10, 0.0)

line_set_start_color

Sets the start color of a line.

syntax

gh_utils.line_set_start_color (
line_id,
r, g, b, a
)

parameters

line_id ID line identifier
r, g, b, a REAL RGBA color

return values

none

code sample

gh_utils.line_set_start_color(line_id, 1, 1, 0, 1)

line_set_start_position

Sets the start position of a line.

syntax

gh_utils.line_set_start_position (
line_id,
x, y, z
)

parameters

line_id ID line identifier
x, y, z REAL position

return values

none

code sample

gh_utils.line_set_start_position(line_id, -10, -10, 0.0)

math_length_vec3

Gets the length of a vec3 vector.

syntax

len = gh_utils.math_length_vec3 (
x, y, z
)

parameters

x, y, z REAL vector

return values

len REAL length

code sample

len = gh_utils.math_length_vec3(x, y, z)

math_normalize_vec3

Normalizes a vec3 vector.

syntax

vx, vy, vz = gh_utils.math_normalize_vec3 (
x, y, z
)

parameters

x, y, z REAL vector

return values

vx, vy, vz REAL normalized vector

code sample

vx, vy, vz = gh_utils.math_normalize_vec3(x, y, z)

math_quat_from_lookat

Creates a quaternion from vectors of a look-at matrix (position, target and up).

syntax

qx, qy, qz, qw = gh_utils.math_quat_from_lookat (
px, py, pz,
tx, ty, tz,
ux, uy, uz
)

parameters

px, py, pz REAL position
tx, ty, tz REAL target
ux, uy, uz REAL up

return values

qx, qy, qz, qw REAL rotation quaternion

code sample

qx, qy, qz, qw = gh_utils.math_quat_from_lookat(px, py, pz,  tx, ty, tz,  ux, uy, uz)

math_quat_from_vectors_rotation

Creates a quaternion from two vectors.

syntax

qx, qy, qz, qw = gh_utils.math_quat_from_vectors_rotation (
x0, y0, z0,
x1, y1, z1
)

parameters

x0, y0, z0 REAL vector 0
x1, y1, z1 REAL vector 1

return values

qx, qy, qz, qw REAL rotation quaternion

code sample

qx, qy, qz, qw = gh_utils.math_quat_from_vectors_rotation(x0, y0, z0, x1, y1, z1)

nfd_open_dialog

macos

NativeFileDialog - opens a dialog box for opening a file.
Works on Windows, Linux (GTK3+) and Raspberry Pi (Raspibian with GTK3+).
Does not work on macOS because macOS UI functions must be called from application main thread only (sucks!).

syntax

filename, ret = gh_utils.nfd_open_dialog (
filters_list,
default_path
)

parameters

filters_list STRING filters list like jpg,png,txt... Can be empty.
default_path STRING default path

return values

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

code sample

filename, ret = gh_utils.nfd_open_dialog("jgp,png", "")

nfd_pick_folder

macos

NativeFileDialog - opens a dialog box for selecting a folder.
Works on Windows, Linux (GTK3+) and Raspberry Pi (Raspibian with GTK3+).
Does not work on macOS because macOS UI functions must be called from application main thread only (sucks!).

syntax

folder, ret = gh_utils.nfd_pick_folder (
default_path
)

parameters

default_path STRING default path

return values

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

code sample

filename, ret = gh_utils.nfd_pick_folder("")

nfd_save_dialog

macos

NativeFileDialog - opens a dialog box for saving a file.
Works on Windows, Linux (GTK3+) and Raspberry Pi (Raspibian with GTK3+).
Does not work on macOS because macOS UI functions must be called from application main thread only (sucks!).

syntax

filename, ret = gh_utils.nfd_save_dialog (
filters_list,
default_path
)

parameters

filters_list STRING filters list like jpg,png,txt... Can be empty.
default_path STRING default path

return values

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

code sample

filename, ret = gh_utils.nfd_save_dialog("jgp,png", "")

open_url

Open an URL in the default browser.

syntax

gh_utils.open_url (
str
)

parameters

str STRING url

return values

none

code sample

gh_utils.open_url("https://geeks3d.com")

pack_rgba_u8

windows

Pack four R, G, B and A channels into a single integer.

syntax

rgba = gh_utils.pack_rgba_u8 (
r, g, b, a
)

parameters

r, g, b, a INTEGER the four R, G, B and A channels

return values

rgba INTEGER the rgba color coded in a single integer

code sample

color = gh_utils.pack_rgba_u8(r, g, b, a)

printc

(zzz) Helper function to print text directly in the console.

syntax

gh_utils.printc (
text
)

parameters

text STRING text

return values

none

code sample

gh_utils.printc(text)

progress_bar_inc

Increments the progress bar size in percent of the current window width.
This functions can be used in an INIT script to draw a progress bar while loading data.
To enable the progress bar, the display_progress_bar=1 attribute must be used in the window XML node.

syntax

gh_utils.progress_bar_inc (
percent_inc,
caption
)

parameters

percent_inc REAL increment in percent
caption STRING caption of the progress bar

return values

none

code sample

gh_utils.progress_bar_set(20, "Initializing...")

...
... do some stuff
...

for i=1, 50 do
    ...
    gh_utils.progress_bar_inc(1)
end

...
... do some stuff
...

gh_utils.progress_bar_set(100, "Initialization complete.")

progress_bar_set

Sets the progress bar size in percent of the current window width.
This functions can be used in an INIT script to draw a progress bar while loading data.
To enable the progress bar, the display_progress_bar=1 attribute must be used in the window XML node.

syntax

gh_utils.progress_bar_set (
percent,
caption
)

parameters

percent REAL percent
caption STRING caption of the progress bar

return values

none

code sample

gh_utils.progress_bar_set(20, "Initializing...")

...
... do some stuff
...

gh_utils.progress_bar_set(50, "Still initializing...")

...
... do some stuff
...

gh_utils.progress_bar_set(100, "Initialization complete.")

project_3d_to_2d_v1

Projects a 3D point into the 2D screen space.
Useful to know if a vertex is under the mouse for example.

syntax

px, py = gh_utils.project_3d_to_2d_v1 (
cam_id,
obj_id,
x, y, z, w
)

parameters

cam_id ID camera identifier
obj_id ID object identifier. The transformation matrix of the object will be used.
x, y, z, w REAL 3D position (w=1.0) of the point to project

return values

px, py REAL 2D position on the screen space

code sample

px, py = gh_utils.project_3d_to_2d_v1(cam_id, obj_id, x, y, z, 1.0)

project_3d_to_2d_v2

Projects a 3D point into the 2D screen space.
Useful to know if a vertex is under the mouse for example.

syntax

px, py = gh_utils.project_3d_to_2d_v2 (
cam_id,
x, y, z, w
)

parameters

cam_id ID camera identifier
x, y, z, w REAL 3D position (w=1.0) of the point to project

return values

px, py REAL 2D position on the screen space

code sample

px, py = gh_utils.project_3d_to_2d_v2(cam_id, x, y, z, 1.0)

random

Returns a random floating point number between 0.0 and 1.0.

syntax

x = gh_utils.random()

parameters

none

return values

x REAL random number

code sample

local x = gh_utils.random()
local y = gh_utils.random()
local z = gh_utils.random()

raycast_cast_ray

Casts a ray in the 3D scene and returns collision information (with a mesh).

syntax

coll_pos_x, coll_pos_y, coll_pos_z, coll_time, face_index = gh_utils.raycast_cast_ray (
mesh_id,
ro_x, ro_y, ro_z, rd_x, rd_y, rd_z
)

parameters

mesh_id INTEGER tested mesh
ro_x, ro_y, ro_z, rd_x, rd_y, rd_z REAL 3D ray: ro (ray origin) and rd (ray direction)

return values

coll_pos_x, coll_pos_y, coll_pos_z REAL collision point
coll_time REAL collision time
face_index INTEGER collision face index

code sample

face_index, coll_time, coll_pos_x, coll_pos_y, coll_pos_z = gh_utils.raycast_cast_ray(mesh_id, ro_x, ro_y, ro_z, rd_x, rd_y, rd_z)

raycast_cast_ray_v2

Casts a ray in the 3D scene and returns collision information (with a mesh).

syntax

coll_pos_x, coll_pos_y, coll_pos_z, coll_time, face_index = gh_utils.raycast_cast_ray_v2 (
mesh_id,
ro_x, ro_y, ro_z, rd_x, rd_y, rd_z,
do_bounding_volume_test
)

parameters

mesh_id INTEGER tested mesh
ro_x, ro_y, ro_z, rd_x, rd_y, rd_z REAL 3D ray: ro (ray origin) and rd (ray direction)
do_bounding_volume_test BOOLEAN performs the bounding volume test before doing deep mesh test: 1 (true) or 0 (false)

return values

coll_pos_x, coll_pos_y, coll_pos_z REAL collision point
coll_time REAL collision time
face_index INTEGER collision face index

code sample

do_bounding_volume_test = 1

face_index, coll_time, coll_pos_x, coll_pos_y, coll_pos_z = gh_utils.raycast_cast_ray_v2(mesh_id, ro_x, ro_y, ro_z, rd_x, rd_y, rd_z, do_bounding_volume_test)

raycast_get_ray

Gets a 3D ray from a screen position (mouse for example) for a perspective camera.

syntax

ro_x, ro_y, ro_z, rd_x, rd_y, rd_z = gh_utils.raycast_get_ray (
screen_x, screen_y,
cam_id
)

parameters

screen_x, screen_y INTEGER screen position
cam_id ID camera identifier

return values

ro_x, ro_y, ro_z, rd_x, rd_y, rd_z REAL 3D ray: ro (ray origin) and rd (ray direction)

code sample

ro_x, ro_y, ro_z, rd_x, rd_y, rd_z = gh_utils.raycast_get_ray(200, 100, cam_id)

raycast_get_ray_ortho_cam

Gets a 3D ray from a screen position (mouse for example) for an orthographic camera.

syntax

ro_x, ro_y, ro_z, rd_x, rd_y, rd_z = gh_utils.raycast_get_ray_ortho_cam (
screen_x, screen_y,
cam_id
)

parameters

screen_x, screen_y INTEGER screen position
cam_id ID camera identifier

return values

ro_x, ro_y, ro_z, rd_x, rd_y, rd_z REAL 3D ray: ro (ray origin) and rd (ray direction)

code sample

ro_x, ro_y, ro_z, rd_x, rd_y, rd_z = gh_utils.raycast_get_ray_ortho_cam(100, 200, cam_id)

sanitize_string

Sanitize a string.

syntax

gh_utils.sanitize_string (
text,
filter_type
)

parameters

text STRING str
filter_type ENUM( filter_type ) type the filter used to sanitize. Currently the only filter is FILTER_FLAG_STRIP_LOW_HIGH (value = 0) that removes characters with ASCII value lesser than 32 and greater than 127.

return values

none

code sample

sanitized_text = gh_utils.sanitize_string(text, 0)

shared_variable_create

Creates a named shared variables.
Shared variables allow to pass values between two windows or between Lua and Python scripts.

syntax

sv_id = gh_utils.shared_variable_create (
name
)

parameters

name STRING name

return values

sv_id ID shared variable identifier

code sample

sv_name = "sv1"
sv_id = gh_utils.shared_variable_create(sv_name)

shared_variable_create_array

Creates a shared variable that holds an array of elements of same type.

syntax

sv_id = gh_utils.shared_variable_create_array (
sv_name,
sv_type,
num_elements
)

parameters

sv_name STRING shared var name
sv_type ENUM( shared_var_elem_type ) type of the shared var elements
num_elements INTEGER number of elements in the array

return values

sv_id ID shared variable identifier

code sample

num_textures = 16
sv_id = gh_utils.shared_variable_create_array("texture_ids", "integer", num_textures)

shared_variable_get_array_value_1f

Gets the value of a particular element of an array.

syntax

elem_value = gh_utils.shared_variable_get_array_value_1f (
sv_name,
elem_index
)

parameters

sv_name STRING shared var name
elem_index INTEGER 0-based index of the element

return values

elem_value REAL value of the element

code sample

elem_value = gh_utils.shared_variable_get_array_value_1f("texture_ids", 0)

shared_variable_get_array_value_1i

Gets the value of a particular element of an array.

syntax

elem_value = gh_utils.shared_variable_get_array_value_1i (
sv_name,
elem_index
)

parameters

sv_name STRING shared var name
elem_index INTEGER 0-based index of the element

return values

elem_value INTEGER value of the element

code sample

elem_value = gh_utils.shared_variable_get_array_value_1i("texture_ids", 0)

shared_variable_get_array_value_str

Gets the value of a particular element of an array.

syntax

elem_value = gh_utils.shared_variable_get_array_value_str (
sv_name,
elem_index
)

parameters

sv_name STRING shared var name
elem_index INTEGER 0-based index of the element

return values

elem_value STRING value of the element

code sample

elem_value = gh_utils.shared_variable_get_array_value_str("texture_ids", 0)

shared_variable_get_value_4f

Gets a 4D value.

syntax

x, y, z, w = gh_utils.shared_variable_get_value_4f (
sv_name
)

parameters

sv_name STRING shared var name

return values

x, y, z, w REAL 4D value

code sample

x, y, z, w = gh_utils.shared_variable_get_value_4f(sv_name)

shared_variable_get_value_str

Gets a string value.

syntax

str = gh_utils.shared_variable_get_value_str (
sv_name
)

parameters

sv_name STRING shared var name

return values

str STRING string value

code sample

str = gh_utils.shared_variable_get_value_str(sv_name)

shared_variable_is_exist

Checks if a shared variable exists.

syntax

is_exist = gh_utils.shared_variable_is_exist (
sv_name
)

parameters

sv_name STRING shared var name

return values

is_exist BOOLEAN exists: 1 (true) or 0 (false)

code sample

state = gh_utils.shared_variable_is_exist(sv_name)

shared_variable_kill

Destroys a shared variable.

syntax

gh_utils.shared_variable_kill (
sv_name
)

parameters

sv_name STRING shared var name

return values

none

code sample

gh_utils.shared_variable_kill(sv1_name)

shared_variable_set_array_value_1f

Sets the value of a particular element of an array.

syntax

gh_utils.shared_variable_set_array_value_1f (
sv_name,
elem_index,
elem_value
)

parameters

sv_name STRING shared var name
elem_index INTEGER 0-based index of the element
elem_value REAL value of the element

return values

none

code sample

gh_utils.shared_variable_set_array_value_1f("texture_ids", 0, 16.0)

shared_variable_set_array_value_1i

Sets the value of a particular element of an array.

syntax

gh_utils.shared_variable_set_array_value_1i (
sv_name,
elem_index,
elem_value
)

parameters

sv_name STRING shared var name
elem_index INTEGER 0-based index of the element
elem_value INTEGER value of the element

return values

none

code sample

gh_utils.shared_variable_set_array_value_1i("texture_ids", 0, 2)

shared_variable_set_array_value_str

Sets the value of a particular element of an array.

syntax

gh_utils.shared_variable_set_array_value_str (
sv_name,
elem_index,
elem_value
)

parameters

sv_name STRING shared var name
elem_index INTEGER 0-based index of the element
elem_value STRING value of the element

return values

none

code sample

gh_utils.shared_variable_set_array_value_str("texture_ids", 0, "abcd")

shared_variable_set_value_4f

Sets a 4D value.

syntax

gh_utils.shared_variable_set_value_4f (
sv_name,
x, y, z, w
)

parameters

sv_name STRING shared var name
x, y, z, w REAL 4D value

return values

none

code sample

gh_utils.shared_variable_set_value_4f(sv_name, 0.2, 0.3, 0.4, 1.0)

shared_variable_set_value_str

Sets a string value.

syntax

gh_utils.shared_variable_set_value_str (
sv_name,
str
)

parameters

sv_name STRING shared var name
str STRING string value

return values

none

code sample

gh_utils.shared_variable_set_value_str(sv_name, str)

sphere_create

Creates a simple sphere made up of several circles.

syntax

sphere_id = gh_utils.sphere_create (
radius,
subdivisions,
r, g, b, a
)

parameters

radius REAL radius
subdivisions INTEGER subdivisions
r, g, b, a REAL RGBA color

return values

sphere_id ID sphere identifier

code sample

sphere_id = gh_utils.sphere_create(10.0, 20, 1.0, 1.0, 0.0, 1.0)

sphere_update_radius

Updates the radius of a sphere.

syntax

gh_utils.sphere_update_radius (
sphere_id,
radius
)

parameters

sphere_id ID sphere identifier
radius REAL radius

return values

none

code sample

gh_utils.sphere_update_radius(sphere_id, 12.0)

stop_demo

Stops a demo and quits GeeXLab.

syntax

gh_utils.stop_demo()

parameters

none

return values

none

code sample

gh_utils.stop_demo()

sys_exec

Executes a system command.

syntax

gh_utils.sys_exec (
command,
parameters,
exe_dir
)

parameters

command STRING command
parameters STRING command parameters
exe_dir STRING command execution folder

return values

none

code sample

local demo_dir = gh_utils.getdemo_dir()

gh_utils.sys_exec("ffmpeg", "-i input.mp4 output.avi", demo_dir)

thread_sleep

Allows to pause the current thread.

syntax

gh_utils.thread_sleep (
delay
)

parameters

delay INTEGER pause delay in milliseconds

return values

none

code sample

gh_utils.thread_sleep(2000)

trace

Writes a trace in the log file and in the debug window.

syntax

gh_utils.trace (
str
)

parameters

str STRING trace to write

return values

none

code sample

gh_utils.trace("Hello world!")

trackball_get_orientation

Returns the rotation quaternion of the trackball.

syntax

x, y, z, w = gh_utils.trackball_get_orientation (
x, y,
prev_x, prev_y
)

parameters

x, y INTEGER current mouse position
prev_x, prev_y INTEGER previous mouse position

return values

x, y, z, w REAL rotation quaternion

code sample

x, y, z, w = gh_utils.trackball_get_orientation(x, y, prev_x, prev_y)

trackball_init

Inits the trackball engine.
The trackball allows to naturally rotate an object as we rotate a sphere.

syntax

gh_utils.trackball_init (
radius,
x, y
)

parameters

radius REAL radius of the trackball. The radius is in screen space.
x, y INTEGER size of the screen

return values

none

code sample

gh_utils.trackball_init(radius, w, h)

tripod_visualizer_camera_render

Draws in a viewport the tripod of a camera.
Useful to visualize the current orientation of the camera.

syntax

gh_utils.tripod_visualizer_camera_render (
cam_id,
x_offset, y_offset, width, height
)

parameters

cam_id ID camera identifier
x_offset, y_offset, width, height INTEGER viewport size

return values

none

code sample

gh_utils.tripod_visualizer_camera_render(cam_id, 0, 0, 100, 100)

unpack_rgba_u8

windows

Unpack a single integer inti four R, G, B and A channels.

syntax

r, g, b, a = gh_utils.unpack_rgba_u8 (
rgba
)

parameters

rgba INTEGER the rgba color coded in a single integer

return values

r, g, b, a INTEGER the four R, G, B and A channels

code sample

r, g, b, a = gh_utils.unpack_rgba_u8(color)

vendor_name_from_vendor_id

Gets the vendor name from its vendor ID.

syntax

date = gh_utils.vendor_name_from_vendor_id (
vendorID
)

parameters

vendorID INTEGER vendor ID (like 4318 for NVIDIA)

return values

date STRING date (Y.M.D.h.m.s)

code sample

name = gh_utils.vendor_name_from_vendor_id(4318)

if (name == "NVIDIA") then
    -- do something
end

webcam_create

windows

Creates a new webcam object.
A max of 8 webcams can be created (Windows only).

syntax

webcam_id = gh_utils.webcam_create()

parameters

none

return values

webcam_id ID webcam identifier

code sample

webcam_id = gh_utils.webcam_create()

webcam_get_frame_size

windows

Gets the size of a frame (Windows only).

syntax

width, height = gh_utils.webcam_get_frame_size (
webcam_id
)

parameters

webcam_id ID webcam identifier

return values

width, height INTEGER size of a frame

code sample

w, h = gh_utils.webcam_get_frame_size(webcam_id)

webcam_get_name

windows

Gets the webcam name, for example: 'Microsoft LifeCam Studio' (Windows only).

syntax

gh_utils.webcam_get_name (
webcam_id
)

parameters

webcam_id ID webcam identifier

return values

none

code sample

name = gh_utils.webcam_get_name(webcam_id)

webcam_get_num

windows

Returns the number of webcams detected by GeeXLab (Windows only).

syntax

num_webcams = gh_utils.webcam_get_num()

parameters

none

return values

num_webcams ID number of webcams

code sample

num_webcam = gh_utils.webcam_get_num()

webcam_grab_frame

windows

Updates the webcam (Windows only).

syntax

gh_utils.webcam_grab_frame (
webcam_id
)

parameters

webcam_id ID webcam identifier

return values

none

code sample

gh_utils.webcam_grab_frame(webcam_id)

webcam_kill

windows

Kills a webcam object (Windows only).

syntax

gh_utils.webcam_kill (
webcam_id
)

parameters

webcam_id ID webcam identifier

return values

none

code sample

gh_utils.webcam_kill(webcam_id)

webcam_start

windows

Initializes a webcam (Windows only).

syntax

ret = gh_utils.webcam_start (
webcam_id,
webcam_number
)

parameters

webcam_id ID webcam identifier
webcam_number INTEGER index of the webcam. Default: 1. First webcam=1, second=2, and so on.

return values

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

code sample

ret = gh_utils.webcam_start(webcam_id, 1)

if (ret == 1) then
    -- Webcam started ok.
end

webcam_stop

windows

Stops a webcam (Windows only).

syntax

gh_utils.webcam_stop (
webcam_id
)

parameters

webcam_id ID webcam identifier

return values

none

code sample

gh_utils.webcam_stop(webcam_id)

webcam_update_texture

windows

Updates a texture pixmap with the current webcam frame (Windows only).

syntax

gh_utils.webcam_update_texture (
webcam_id,
tex_id
)

parameters

webcam_id ID webcam identifier
tex_id ID texture identifier

return values

none

code sample

gh_utils.webcam_update_texture(webcam_id, tex_id)

win_registry_create_key

windows

Create a subkey in Windows registry (Windows only).
WARNING: serious problems might occur if you modify the registry incorrectly.

syntax

ret = gh_utils.win_registry_create_key (
key_name,
subkey_name,
options
)

parameters

key_name STRING key name
subkey_name STRING subkey name
options STRING options - reserved

return values

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

code sample

key_name = "HKEY_CURRENT_USER"			
subkey_name = "Software\\MyKoolUtility"
options = ""
ret = gh_utils.win_registry_create_key(key_name, subkey_name, options)

win_registry_delete_key

windows

Delete a subkey from Windows registry (Windows only).
WARNING: serious problems might occur if you modify the registry incorrectly.

syntax

ret = gh_utils.win_registry_delete_key (
key_name,
subkey_name
)

parameters

key_name STRING key name
subkey_name STRING subkey name

return values

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

code sample

key_name = "HKEY_CURRENT_USER"			
subkey_name = "Software\\MyKoolUtility"
ret = gh_utils.win_registry_delete_key(key_name, subkey_name)

win_registry_read_value_dword

windows

Read an integer (REG_DWORD) value from Windows registry (Windows only).
WARNING: serious problems might occur if you modify the registry incorrectly.

syntax

ret, x = gh_utils.win_registry_read_value_dword (
key_name,
subkey_name,
value_name
)

parameters

key_name STRING key name
subkey_name STRING subkey name
value_name STRING value_name

return values

ret BOOLEAN return code: 1 (success) or 0 (error)
x INTEGER dword value

code sample

key_name = "HKEY_LOCAL_MACHINE"			
subkey_name = "HARDWARE\\DESCRIPTION\\System\\BIOS"
value_name = "BiosMajorRelease"
ret, x = gh_utils.win_registry_read_value_dword(key_name, subkey_name, value_name)

win_registry_read_value_string

windows

Read a string (REG_SZ) value from Windows registry (Windows only).
WARNING: serious problems might occur if you modify the registry incorrectly.

syntax

ret, str = gh_utils.win_registry_read_value_string (
key_name,
subkey_name,
value_name
)

parameters

key_name STRING key name
subkey_name STRING subkey name
value_name STRING value_name

return values

ret BOOLEAN return code: 1 (success) or 0 (error)
str STRING string value

code sample

key_name = "HKEY_LOCAL_MACHINE"			
subkey_name = "HARDWARE\\DESCRIPTION\\System\\BIOS"
value_name = "BIOSVendor"
ret, str = gh_utils.win_registry_read_value_string(key_name, subkey_name, value_name)

win_registry_write_value_dword

windows

Write an integer (REG_DWORD) value into Windows registry (Windows only).
WARNING: serious problems might occur if you modify the registry incorrectly.

syntax

ret = gh_utils.win_registry_write_value_dword (
key_name,
subkey_name,
value_name,
x
)

parameters

key_name STRING key name
subkey_name STRING subkey name
value_name STRING value_name
x INTEGER dword value

return values

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

code sample

key_name = "HKEY_LOCAL_MACHINE"			
subkey_name = "HARDWARE\\DESCRIPTION\\System\\BIOS"
value_name = "BiosMajorRelease"
ret = gh_utils.win_registry_write_value_dword(key_name, subkey_name, value_name, 5)

win_registry_write_value_string

windows

Write a string (REG_SZ) value into Windows registry (Windows only).
WARNING: serious problems might occur if you modify the registry incorrectly.

syntax

ret = gh_utils.win_registry_write_value_string (
key_name,
subkey_name,
value_name,
str
)

parameters

key_name STRING key name
subkey_name STRING subkey name
value_name STRING value_name
str STRING string value

return values

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

code sample

key_name = "HKEY_LOCAL_MACHINE"			
subkey_name = "HARDWARE\\DESCRIPTION\\System\\BIOS"
value_name = "BIOSVendor"
ret = gh_utils.win_registry_write_value_string(key_name, subkey_name, value_name, "American Megatrends Inc.")

zip_buffer_create

Allocates a memory buffer of a file stored in a zip archive and returns the pointer to the memory buffer.

syntax

buff_ptr, buff_size = gh_utils.zip_buffer_create (
zip_filename,
filename
)

parameters

zip_filename STRING absolute path of the zip file
filename STRING path of the file in the zip archive

return values

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

code sample

zip_filename = gh_utils.get_demo_dir() .. "demo.zip"
filename = "config.txt"

buffer_ptr, buffer_size = gh_utils.zip_buffer_create(zip_filename, filename)
...
gh_utils.buffer_kill(buffer_ptr)

zip_to_file

Extracts a file from a zip and save it on the file system.

syntax

ret = gh_utils.zip_to_file (
zip_filename,
src_filename,
dst_filename
)

parameters

zip_filename STRING absolute path of the zip file
src_filename STRING path of the file in the zip archive
dst_filename STRING absolute path of the file on the file system

return values

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

code sample

zip_filename = gh_utils.get_demo_dir() .. "demo.zip"
src_filename = "assets/image01.jpg"
dst_filename = gh_utils.get_demo_dir() .. "image01.jpg"

if (gh_utils.file_size(zip_filename, src_filename, dst_filename) == 1) then
    -- OK!
end

gh_vb

Vertex Buffer module (for OpenGL)

gh_vb is a module that manages OpenGL vertex buffers.
gh_vb allows to create, set values and render simple vertex buffers.

bind

Binds a vertex buffer.

syntax

gh_vb.bind (
vb_id
)

parameters

vb_id ID vertex buffer identifier

return values

none

code sample

gh_vb.bind(vb_id)

create

Creates a vertex buffer.

syntax

vb_id = gh_vb.create (
buff_size,
num_vertex_attribs
)

parameters

buff_size INTEGER size of the vertex buffer in bytes
num_vertex_attribs INTEGER number of vertex attribs

return values

vb_id ID vertex buffer identifier

code sample

vb_id = gh_vb.create(buffer_size, num_vertex_attribs)

draw_lines

Draws lines from a vertex buffer.

syntax

gh_vb.draw_lines (
vb_id,
count,
start,
render_mode
)

parameters

vb_id ID vertex buffer identifier
count INTEGER number of vertices that must be drawn
start INTEGER index of the first vertex
render_mode ENUM( line_mode ) render mode: 0 (LINE_RENDER_DEFAULT), 1 (LINE_RENDER_STRIP), 2 (LINE_RENDER_LOOP)

return values

none

code sample

-- Draws the first 100 vertices as lines.
LINE_RENDER_DEFAULT = 0
LINE_RENDER_STRIP = 1
LINE_RENDER_LOOP = 2

gh_vb.draw_lines(vb_id, 100, 0, LINE_RENDER_STRIP)

draw_points

Draws points from a vertex buffer.

syntax

gh_vb.draw_points (
vb_id,
count,
start
)

parameters

vb_id ID vertex buffer identifier
count INTEGER number of points that must be drawn
start INTEGER index of the first point

return values

none

code sample

-- Draws the first 100 points.
gh_vb.draw_points(vb_id, 100, 0)

draw_triangles

Draws triangles from a vertex buffer.

syntax

gh_vb.draw_triangles (
vb_id,
count,
start,
triangle_mode
)

parameters

vb_id ID vertex buffer identifier
count INTEGER number of vertices that must be drawn
start INTEGER index of the first vertex
triangle_mode ENUM( triangle_mode ) triangle mode

return values

none

code sample

-- triangle modes:
TRIANGLE = 0
TRIANGLE_STRIP = 1
TRIANGLE_FAN = 9

-- Draws the first 90 vertices as triangles (30 triangles).
gh_vb.draw_triangles(vb_id, 90, 0, TRIANGLE)

kill

Kills a vertex buffer.

syntax

gh_vb.kill (
vb_id
)

parameters

vb_id ID vertex buffer identifier

return values

none

code sample

gh_vb.kill(vb_id)

map

Maps the vertex buffer to CPU memory.
The buffer pointer returned by map() is valid until the next call to unmap.

syntax

buff_ptr, buff_size = gh_vb.map (
vb_id,
access_mode
)

parameters

vb_id ID vertex buffer identifier
access_mode STRING XX

return values

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

code sample

buffer, buffer_size = gh_vb.map(vb_id, "")

set_value_1f

Sets a value in the vertex buffer.

syntax

gh_vb.set_value_1f (
vb_id,
buff_offset_bytes,
x
)

parameters

vb_id ID vertex buffer identifier
buff_offset_bytes INTEGER offset in bytes
x REAL value

return values

none

code sample

offset = 4
gh_vb.set_value_1f(vb_id, offset, x)

set_value_1ui

Sets a value in the vertex buffer.

syntax

gh_vb.set_value_1ui (
vb_id,
buff_offset_bytes,
x
)

parameters

vb_id ID vertex buffer identifier
buff_offset_bytes INTEGER offset in bytes
x INTEGER value

return values

none

code sample

offset = 4
gh_vb.set_value_1ui(vb_id, offset, x)

set_value_2f

Sets a value in the vertex buffer.

syntax

gh_vb.set_value_2f (
vb_id,
buff_offset_bytes,
x, y
)

parameters

vb_id ID vertex buffer identifier
buff_offset_bytes INTEGER offset in bytes
x, y REAL value

return values

none

code sample

offset = 8
gh_vb.set_value_2f(vb_id, offset, x, y)

set_value_3f

Sets a value in the vertex buffer.

syntax

gh_vb.set_value_3f (
vb_id,
buff_offset_bytes,
x, y, z
)

parameters

vb_id ID vertex buffer identifier
buff_offset_bytes INTEGER offset in bytes
x, y, z REAL value

return values

none

code sample

offset = 12
gh_vb.set_value_3f(vb_id, offset, x, y, z)

set_value_4f

Sets a value in the vertex buffer.

syntax

gh_vb.set_value_4f (
vb_id,
buff_offset_bytes,
x, y, z, w
)

parameters

vb_id ID vertex buffer identifier
buff_offset_bytes INTEGER offset in bytes
x, y, z, w REAL value

return values

none

code sample

offset = 16
gh_vb.set_value_4f(vb_id, offset, x, y, z, w)

set_value_4x4f

Sets a value in the vertex buffer.

syntax

gh_vb.set_value_4x4f (
vb_id,
buff_offset_bytes,
m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15
)

parameters

vb_id ID vertex buffer identifier
buff_offset_bytes INTEGER offset 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

offset = 64
gh_vb.set_value_4x4f(vb_id, offset, m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15)

set_vertex_attrib_data

Specifies the description of a vertex attibute.
This description will be used to render the vertex array.

syntax

gh_vb.set_vertex_attrib_data (
vb_id,
vertex_attrib_index,
attrib_location,
type,
dim,
stride,
offset
)

parameters

vb_id ID vertex buffer identifier
vertex_attrib_index INTEGER XX
attrib_location INTEGER XX
type INTEGER XX
dim INTEGER XX
stride INTEGER XX
offset INTEGER XX

return values

none

code sample

gh_vb.set_vertex_attrib_data(vb_id, vertex_attrib_index, attrib_location, type, dim, stride, offset)

unbind

Unbinds a vertex buffer.

syntax

gh_vb.unbind (
vb_id
)

parameters

vb_id ID vertex buffer identifier

return values

none

code sample

gh_vb.unbind(vb_id)

unmap

Unmaps the vertex buffer.

syntax

gh_vb.unmap (
vb_id
)

parameters

vb_id ID vertex buffer identifier

return values

none

code sample

gh_vb.unmap(vb_id)

gh_vertex_pool

Vertex pool module

gh_vertex_pool is the module that manages a pool of vertices (or an array of vertices).

create

Creates a vertex pool.

syntax

vp_id = gh_vertex_pool.create (
num_vertices
)

parameters

num_vertices INTEGER number of vertices in the vertex pool

return values

vp_id ID vertex pool identifier

code sample

vp_id = gh_vertex_pool.create(1000)

render

Renders a vertex pool.

syntax

gh_vertex_pool.render (
vp_id,
start_vertex,
num_vertices
)

parameters

vp_id ID vertex pool identifier
start_vertex INTEGER index of first vertex. Usually = 0
num_vertices INTEGER number of vertices to render. Set it to -1 to render from start_vertex to the last vertex.

return values

none

code sample

gh_vertex_pool.render(vp_id, 0, -1)

set_vertex_source

Set the source of the vertices of a vertex pool.

syntax

gh_vertex_pool.set_vertex_source (
vp_id,
gpubuff_id
)

parameters

vp_id ID vertex pool identifier
gpubuff_id ID gpu buffer identifier

return values

none

code sample

gh_vertex_pool.set_vertex_source(vp_id, gpu_buffer_id)

vb_get_vertex_color

Gets the color of a vertex in a mapped GPU memory.

syntax

r, g, b, a = gh_vertex_pool.vb_get_vertex_color (
vp_id,
index
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index

return values

r, g, b, a REAL RGBA color value

code sample

r, g, b, a = gh_vertex_pool.vb_get_vertex_color(vp_id, index)

vb_get_vertex_normal

Gets the normal of a vertex in a mapped GPU memory.

syntax

x, y, z, w = gh_vertex_pool.vb_get_vertex_normal (
vp_id,
index
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index

return values

x, y, z, w REAL 4D vector

code sample

x, y, z, w = gh_vertex_pool.vb_get_vertex_normal(vp_id, index)

vb_get_vertex_position

Gets the position of a vertex in a mapped GPU memory.

syntax

x, y, z, w = gh_vertex_pool.vb_get_vertex_position (
vp_id,
index
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index

return values

x, y, z, w REAL 4D position

code sample

x, y, z, w = gh_vertex_pool.vb_get_vertex_position(vp_id, index)

vb_get_vertex_tangent

Gets the tangent of a vertex in a mapped GPU memory.

syntax

x, y, z, w = gh_vertex_pool.vb_get_vertex_tangent (
vp_id,
index
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index

return values

x, y, z, w REAL 4D vector

code sample

x, y, z, w = gh_vertex_pool.vb_get_vertex_tangent(vp_id, index)

vb_map

Maps the GPU memory of the vertex buffer into CPU address space.
Once the vertex buffer is mapped, you can use gh_vertex_pool functions for reading and writing or you can use memory buffer functions of the gh_utils library.

syntax

buff_ptr, buff_size = gh_vertex_pool.vb_map (
vp_id
)

parameters

vp_id ID vertex pool identifier

return values

buff_ptr POINTER pointer to the buffer
buff_size INTEGER size of the buffer in bytes

code sample

buffer_ptr, buffer_size = gh_vertex_pool.vb_map(vp_id)

if (buffer_size > 0) then
    --
    -- do read/write ops with the buffer.
    --

    index = 0
    x, y, z, w = gh_utils.buffer_read_4f(buffer_ptr, index)

    z = z * 2.0
    gh_utils.buffer_write_4f(buffer_ptr, 0, x, y, z, w)
end

gh_vertex_pool.vb_unmap(vp_id)

vb_set_vertex_color

Sets the color of a vertex in a mapped GPU memory.

syntax

gh_vertex_pool.vb_set_vertex_color (
vp_id,
index,
r, g, b, a
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index
r, g, b, a REAL RGBA color

return values

none

code sample

gh_vertex_pool.vb_map(vp_id)

for i=0, z_max-1 do
    for j=0, x_max-1 do
        local index = i*z_max + j
        r, g, b, a = gh_vertex_pool.vb_get_vertex_color(vp_id, index)
        ...
        ... do some stuff with r, g, b, a.
        ...
        gh_vertex_pool.vb_set_vertex_color(vp_id, index, r, g, b, a)
    end
end

gh_vertex_pool.vb_unmap(vp_id)

vb_set_vertex_normal

Sets the normal of a vertex in a mapped GPU memory.

syntax

gh_vertex_pool.vb_set_vertex_normal (
vp_id,
index,
x, y, z, w
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index
x, y, z, w REAL 4D vector

return values

none

code sample

gh_vertex_pool.vb_map(vp_id)

gh_vertex_pool.vb_set_vertex_normal(vp_id, index, x, y, z, w)

gh_vertex_pool.vb_unmap(vp_id)

vb_set_vertex_position

Sets the position of a vertex in a mapped GPU memory.

syntax

gh_vertex_pool.vb_set_vertex_position (
vp_id,
index,
x, y, z, w
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index
x, y, z, w REAL 4D position

return values

none

code sample

gh_vertex_pool.vb_map(vp_id)

for i=0, z_max-1 do
    for j=0, x_max-1 do
        local index = i*z_max + j

        x, y, z, w = gh_vertex_pool.vb_get_vertex_position(vp_id, index)

        y1 = 2.0 * math.cos(elapsed_time + x * 0.1) + math.sin(elapsed_time + z * 0.1)
        y2 = 2.0 * math.sin(elapsed_time + x * 0.1) + math.cos(elapsed_time + z * 0.1)
        gh_vertex_pool.vb_set_vertex_position(vp_id, index, x, y1+y2, z, w)
    end
end

gh_vertex_pool.vb_unmap(vp_id)

vb_set_vertex_tangent

Sets the tangent of a vertex in a mapped GPU memory.

syntax

gh_vertex_pool.vb_set_vertex_tangent (
vp_id,
index,
x, y, z, w
)

parameters

vp_id ID vertex pool identifier
index INTEGER vertex index
x, y, z, w REAL 4D vector

return values

none

code sample

gh_vertex_pool.vb_map(vp_id)

gh_vertex_pool.vb_set_vertex_tangent(vp_id, index, x, y, z, w)

gh_vertex_pool.vb_unmap(vp_id)

vb_unmap

Unmaps the GPU memory of the vertex buffer.

syntax

gh_vertex_pool.vb_unmap (
vp_id
)

parameters

vp_id ID vertex pool identifier

return values

none

code sample

gh_vertex_pool.vb_unmap(vp_id)

vertex_get_color

Gets the color of a particular vertex.

syntax

r, g, b, a = gh_vertex_pool.vertex_get_color (
vp_id,
index
)

parameters

vp_id ID vertex pool identifier
index INTEGER index of the vertex from 0 to num_vertices-1

return values

r, g, b, a REAL RGBA color of the vertex

code sample

r, g, b, a = gh_vertex_pool.vertex_get_color(vp_id, index)

vertex_get_position

Gets the position of a particular vertex.

syntax

x, y, z, w = gh_vertex_pool.vertex_get_position (
vp_id,
index
)

parameters

vp_id ID vertex pool identifier
index INTEGER index of the vertex from 0 to num_vertices-1

return values

x, y, z, w REAL 4D position of the vertex

code sample

x, y, z, w = gh_vertex_pool.vertex_get_position(vp_id, index)

vertex_set_color

Sets the color of a particular vertex.

syntax

gh_vertex_pool.vertex_set_color (
vp_id,
index,
r, g, b, a
)

parameters

vp_id ID vertex pool identifier
index INTEGER index of the vertex from 0 to num_vertices-1
r, g, b, a REAL RGBA color of the vertex

return values

none

code sample

gh_vertex_pool.vertex_set_color(vp_id, index, r, g, b, a)

vertex_set_position

Sets the position of a particular vertex.

syntax

gh_vertex_pool.vertex_set_position (
vp_id,
index,
x, y, z, w
)

parameters

vp_id ID vertex pool identifier
index INTEGER index of the vertex from 0 to num_vertices-1
x, y, z, w REAL 4D position of the vertex

return values

none

code sample

gh_vertex_pool.vertex_set_position(vp_id, index, x, y, z, 1.0)

vertices_from_gpu_buffer

Copies all vertices from a GPU buffer to a vertex pool.

syntax

gh_vertex_pool.vertices_from_gpu_buffer (
vp_id,
gpubuff_id
)

parameters

vp_id ID vertex pool identifier
gpubuff_id ID gpu buffer identifier

return values

none

code sample

gh_vertex_pool.vertices_from_gpu_buffer(vp_id, gpu_buffer_id)

vertices_to_gpu_buffer

Copies all vertices to a GPU buffer.

syntax

gh_vertex_pool.vertices_to_gpu_buffer (
vp_id,
gpubuff_id
)

parameters

vp_id ID vertex pool identifier
gpubuff_id ID gpu buffer identifier

return values

none

code sample

gh_vertex_pool.vertices_to_gpu_buffer(vp_id, gpu_buffer_id)

gh_vr

OpenVR module

gh_vr is the module that manages OpenVR functions.
OpenVR allows you to render graphics into virtual reality headsets (or HMD) like HT Vive or Occulus Rift.

apply_controller_transform

Applies the transformation matrix of the controller to the object used to visualize the controller.

syntax

ret = gh_vr.apply_controller_transform (
controller_index,
controller_object,
hmd_object
)

parameters

controller_index INTEGER XX identifier of the object used to visualize the controller
controller_object INTEGER platform index
hmd_object INTEGER HMD object. Can be 0 if there is no HMD object.

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

ret = gh_vr.applay_controller_transform(controller_index, controller_object, hmd_object)

get_controller_button_state

Returns the state of the controller button.

syntax

button_pressed = gh_vr.get_controller_button_state (
controller_index
)

parameters

controller_index INTEGER index of the controller (0 or 1)

return values

button_pressed BOOLEAN pressed: 1 (true) or 0 (false)

code sample

button_pressed = gh_vr.get_controller_button_state(0)

get_num_controllers

Returns the number of controllers.

syntax

num_controllers = gh_vr.get_num_controllers()

parameters

none

return values

num_controllers INTEGER number of controllers

code sample

num_controllers = gh_vr.get_num_controllers()

is_initialized

Checks if the VR initialization state.

syntax

ret = gh_vr.is_initialized()

parameters

none

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

state = gh_vr.is_initialized()

submit

Submit left and right render targets to the HMD and compose the VR scene.

syntax

ret = gh_vr.submit (
rt_left_eye,
rt_right_eye
)

parameters

rt_left_eye INTEGER left render target
rt_right_eye INTEGER right render target

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

ret = gh_vr.submit(rt_left_eye, rt_right_eye)

update_cameras

Updates left and right cameras according to HMD position and orientation.

syntax

ret = gh_vr.update_cameras (
left_camera,
right_camera
)

parameters

left_camera INTEGER left camera
right_camera INTEGER right camera

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

ret = gh_vr.update_cameras(left_camera, right_camera)

update_cameras_v2

Updates left and right cameras according to HMD orientation.
The position is defined by the hmd_object.

syntax

ret = gh_vr.update_cameras_v2 (
left_camera,
right_camera,
hmd_object
)

parameters

left_camera INTEGER left camera
right_camera INTEGER right camera
hmd_object INTEGER HMD object

return values

ret BOOLEAN 1 (success) or 0 (error)

code sample

ret = gh_vr.update_cameras_v2(left_camera, right_camera, hmd_object)

update_controller_transform

Updates the transformation matrix of the object that will be used to render a controller according to the transformation (position / orientation) of the HMD.

syntax

gh_vr.update_controller_transform (
controller_index,
controller_id,
hmd_object_id
)

parameters

controller_index INTEGER index of the controller
controller_id ID identifier of the object that represents a controller
hmd_object_id ID identifier of the object that represents the HMD

return values

none

code sample

controller_id = gh_mesh.create_sphere()
...
gh_vr.update_controller_transform(controller_index, controller_id, hmd_object_id)
...
gh_object.render(controller_id)

update_controllers_state

Updates the state of the controllers.
Should be called once per frame.

syntax

gh_vr.update_controllers_state()

parameters

none

return values

none

code sample

gh_vr.update_controllers_state()

gh_window

Window module

gh_window is the module that manages the current window.

getsize

Returns the size of the window.

syntax

width, height = gh_window.getsize (
win_id
)

parameters

win_id ID identifier of the window. 0 is the current window.

return values

width, height INTEGER size of the window

code sample

width, height = gh_window.getsize(0)

set_alpha

windows

Sets the alpha value of the window (Windows only).

syntax

gh_window.set_alpha (
win_id,
alpha
)

parameters

win_id ID identifier of the window. 0 is the current window.
alpha REAL alpha value from 0.0 to 1.0

return values

none

code sample

gh_window.set_alpha(0, 0.8)

timer_get_milliseconds

Returns the number of milliseconds since the last reset.

syntax

elapsed_time = gh_window.timer_get_milliseconds (
win_id
)

parameters

win_id ID identifier of the window. 0 is the current window.

return values

elapsed_time REAL elapsed time in milliseconds

code sample

elapsed_time = gh_window.timer_get_milliseconds(0)

timer_get_seconds

Returns the number of seconds since the last reset.

syntax

elapsed_time = gh_window.timer_get_seconds (
win_id
)

parameters

win_id ID identifier of the window. 0 is the current window.

return values

elapsed_time REAL elapsed time in seconds

code sample

elapsed_time = gh_window.timer_get_seconds(0)

timer_reset

Resets the timer of the window.

syntax

gh_window.timer_reset (
win_id
)

parameters

win_id ID identifier of the window. 0 is the current window.

return values

none

code sample

gh_window.timer_reset(0)

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 sound_create sound_create_from_buffer sound_create_from_sqlite3_blob sound_create_from_zip sound_create_v2 wip sound_get_duration_ms sound_get_open_state sound_get_position_ms sound_get_volume sound_is_playing sound_kill sound_play sound_set_loop_state sound_set_paused sound_set_volume sound_spectrum_get_num_values sound_spectrum_get_value sound_spectrum_read sound_spectrum_read_v2 sound_update_audio_data_params wip update
gh_av decoder_close decoder_open get_codec_name get_duration get_elapsed_time get_num_frames get_streams_index pause process_frame reset_streams seek_frame_time set_volume start_audio_video_processing stop_audio_video_processing video_get_resolution video_init_texture video_update_texture
gh_bullet3 actor_apply_central_force actor_apply_central_impulse actor_apply_torque actor_apply_transform actor_clear_forces actor_create_box actor_create_box_v2 actor_create_cylinder actor_create_cylinder_v2 actor_create_mesh actor_create_mesh_v2 actor_create_sphere actor_create_sphere_v2 actor_create_static_plane actor_get_activation_state actor_get_angular_speed2 actor_get_angular_velocity actor_get_contact_info actor_get_linear_speed2 actor_get_linear_velocity actor_get_orientation actor_get_position actor_kill actor_set_3d_object actor_set_activation_state actor_set_angular_factor actor_set_angular_velocity actor_set_ccd_params actor_set_collision_margin actor_set_damping actor_set_gravity actor_set_linear_factor actor_set_linear_velocity actor_set_material actor_set_orientation actor_set_position actor_set_sleeping_thresholds actor_update_mass get_version init material_create material_kill material_update scene_add_actor scene_check_contacts scene_create scene_create_sap scene_kill scene_remove_actor scene_reset_all_contacts scene_set_gravity scene_set_solver_num_iterations scene_step_simulation scene_sync_3d_objects terminate
gh_camera bind bind_v2 create_ortho create_orthographic create_persp create_persp_v2 create_persp_v3 create_perspective frustum_check_object_aa_box frustum_check_object_sphere frustum_check_point frustum_check_sphere frustum_update get_euler_angles get_fov get_position get_projection_matrix get_projection_matrix_4x4 get_up_vector get_view get_view_matrix get_view_quaternion load_gl2_matrix reset_reflection_matrix set_fov set_lookat set_orientation_cubemap set_pitch set_position set_projection_matrix set_reflection_matrix_v1 set_reflection_matrix_v2 set_reflection_matrix_v3 set_roll set_up_vec set_view_matrix set_viewport set_yaw update_ortho update_persp update_persp_v2
gh_cuda nvidia device_get_attribute_1i device_get_attribute_2i device_get_attribute_3i device_get_name device_get_pci_bus_id_string device_get_total_memory get_driver_version get_num_devices sm_version_to_num_cores
gh_flex windowsnvidia get_compute_device_name get_version make_phase particles_copy_position_to_vb_fast particles_copy_to_vb particles_create particles_get_phase particles_get_position particles_get_velocity particles_kill particles_map_active_indices particles_map_phase particles_map_position particles_map_velocity particles_set_active_index particles_set_num_active_indices particles_set_phase particles_set_position particles_set_velocity particles_unmap_active_indices particles_unmap_phase particles_unmap_position particles_unmap_velocity particles_update_active set_device_index shapes_create shapes_kill shapes_map shapes_set_box shapes_set_box_v2 shapes_set_mesh shapes_set_mesh_v2 shapes_set_sphere shapes_unmap solver_create solver_kill solver_set_num_active_particles solver_set_param_1f solver_set_param_1i solver_set_param_3f solver_set_param_collision_plane solver_update solver_update_params solver_write_particles solver_write_shapes start stop
gh_font build_texture clear create create_from_buffer create_from_sqlite3_blob create_from_zip create_v2 create_v3 get_text_width get_texture render set_scale text_2d text_2d_v2 text_3d update update_texture_2d_array_layer wtext_2d wtext_2d_v2
gh_gml windowslinuxmacos geforce_logo_get_illumination geforce_logo_is_illumination_supported geforce_logo_set_illumination get_all_limiting_policies get_clocks get_fan_speed get_gpu_codename get_gpu_config get_gpu_cores get_gpu_driver get_gpu_fullname get_num_gpus get_pci_identifiers get_temperatures get_usages gpu_power_get_current_value gpu_power_get_power_limit
gh_gpu_buffer atomic_counter_get_value atomic_counter_set_value bind bind_base bind_range create create_from_uniform_block map map_range set_matrix4x4 set_value_1f set_value_1ui set_value_1ui64_bindless_texture set_value_2f set_value_3f set_value_4f set_value_4x4f sub_data_read_1f sub_data_read_1ui sub_data_read_2f sub_data_read_3f sub_data_read_4f sub_data_write_1f sub_data_write_1ui sub_data_write_2f sub_data_write_3f sub_data_write_4f unbind unmap
gh_gpu_program add_shader_from_buffer bind create create_empty create_from_file create_from_file_v3 create_from_shader_files create_from_shader_files_gl_spirv opengl create_from_zip_file create_from_zip_file_gl_spirv opengl create_gl_spirv opengl create_v2 get_interface_block_index get_uniform_array_stride get_uniform_block_size get_uniform_size_and_offset get_vertex_attrib_name run_compute run_compute_group_size set_livecoding_state set_shader_storage_block_binding set_uniform_block_binding set_vertex_attrib_name uniform1d uniform1f uniform1fv lua uniform1i uniform1iv lua uniform1ui64 uniform1ui64v lua uniform2d uniform2f uniform2fv lua uniform2i uniform3d uniform3f uniform3fv lua uniform3i uniform4d uniform4f uniform4f_array uniform4fv lua uniform4i uniform4i_array uniform_4x4f uniform_camera_matrices uniform_camera_matrices_v2 uniform_modelviewproj_matrices uniform_object_matrix uniform_subroutine vk_create_from_spirv_module_file vulkan
gh_imagemagick file_convert file_crop file_exif_get_num_properties file_exif_get_property file_exif_to_log file_ping file_resize texture_auto_level texture_blur texture_charcoal texture_cleanup texture_constitute texture_create_from_buffer texture_create_from_file texture_create_from_zip_file texture_crop texture_decipher texture_edge texture_emboss texture_encipher texture_flip texture_flop texture_gaussian_blur texture_motion_blur texture_negate texture_oil_paint texture_posterize texture_quantize texture_read texture_resize texture_sepia texture_sharpen texture_sketch texture_solarize texture_swirl texture_transpose texture_update texture_wave texture_write
gh_imgui add_bezier_curve_to_drawlist add_circle_to_drawlist add_font_from_buffer add_font_from_file add_font_from_zip_file add_line_to_drawlist add_quad_to_drawlist begin_child button button_arrow calc_text_size checkbox collapsing_header color_edit_rgba color_edit_rgba_v2 color_picker_rgba color_picker_rgba_v2 column_get_offset column_get_width column_next column_set_offset column_set_width columns combo_box_add_item combo_box_create combo_box_draw dummy end_child frame_begin frame_begin_v2 frame_end get_color get_content_region_available_width get_cur_font_display_offset get_cursor_pos get_cursor_screen_pos get_cursor_start_pos get_font_size get_item_rect get_scroll get_scroll_max get_text_line_heigh_with_spacing get_version get_window_pos get_window_pos_size get_window_size gizmo_begin_frame gizmo_decompose_matrix_to_components gizmo_enable gizmo_is_over gizmo_is_using gizmo_manipulate gizmo_set_rect group_begin group_end image opengl image_button opengl indent init input_text is_any_item_hovered is_any_window_hovered is_item_clicked is_item_hovered is_mouse_clicked is_window_hovered list_box_begin list_box_draw list_box_draw_v2 list_box_end list_clipping_begin list_clipping_end menu_begin menu_begin_bar menu_begin_main_bar menu_end menu_end_bar menu_end_main_bar menu_item plotline_create plotline_draw plotline_draw_v2 plotline_get_value1f plotline_set_value1f pop_font pop_item_width pop_style_color popup_begin popup_begin_context popup_end popup_open progress_bar push_font push_item_width push_style_color radio_button rebuild_all_fonts reset_default_font same_line select_draw_list selectable separator set_color set_cur_font_display_offset set_default_font set_frame_border_size set_frame_rounding set_indent_spacing set_item_default_focus set_keyboard_focus_here set_next_item_width set_next_window_content_size set_scroll set_scroll_from_pos_y set_scroll_here_y set_style_colors set_tooltip set_window_border_size set_window_focus set_window_rounding show_demo_window show_metrics_window show_test_window slider_1f slider_1i slider_4f spacing tab_bar_begin tab_bar_begin_v2 tab_bar_end tab_item_begin tab_item_begin_v2 tab_item_end terminate text text_rgba text_unformatted_v1 text_unformatted_v2 text_wrapped tree_node tree_node_ex tree_node_leaf tree_node_leaf_v2 tree_pop underline unindent url vslider_1f vslider_1i widget window_begin window_begin_v2 window_end
gh_input joystick_get_button_state windows joystick_get_num windows joystick_get_position windows joystick_get_status windows keyboard_clear_key_buffer windows keyboard_is_key_down keyboard_update_buffer windows mouse_get_button_state mouse_get_position mouse_get_wheel_delta mouse_reset_wheel_delta mouse_set_position mouse_show_cursor windows
gh_leap windowsmacos get_device_name get_finger_bone_direction get_finger_bone_position get_hand_palm_angles get_hand_palm_normal get_hand_palm_position get_num_devices get_num_fingers get_num_hands is_connected update
gh_logiled set_flash_lighting set_key_lighting set_lighting set_pulse_lighting set_target stop_effects
gh_material add_texture bind create get_gpu_program remove_texture set_gpu_program
gh_mesh alloc_mesh_data create_box create_box_8v create_cylinder create_cylinder_xyz create_disc create_ellipse create_gear create_icosphere create_plane create_plane_v3 create_quad create_sphere create_terrain create_torus create_triangle create_v2 get_face_normal get_face_vertex_indices get_vertex_absolute_position get_vertex_color get_vertex_normal get_vertex_position get_vertex_tangent get_vertex_uv instancing_attrib_buffer_get instancing_attrib_buffer_update_needed instancing_get_color instancing_get_orientation instancing_get_position instancing_get_scale instancing_init instancing_set_axis_angle instancing_set_color instancing_set_orientation instancing_set_orientation_v2 instancing_set_position instancing_set_position_v2 instancing_set_scale resize_box resize_plane resize_quad ribbon_add_point ribbon_create ribbon_set_cross_vector set_face_vertex_indices set_vertex_color set_vertex_normal set_vertex_position set_vertex_tangent set_vertex_uv set_vertices_color voxelize
gh_model create_from_file create_from_file_loader_3ds create_from_file_loader_assimp create_from_file_loader_assimp_v2 create_from_file_loader_fbx create_from_file_loader_gltf create_from_file_loader_obj create_from_file_loader_stl create_from_zip_file_loader_assimp load_textures load_textures_from_zip
gh_node add_child get_child_by_index get_name get_num_children getid kill remove_child set_name
gh_nvg private
gh_object add_material average_vertices_normal lua compute_faces_normal compute_vertices_normal lua copy_transform create flip_faces flip_vertex_normals get_absolute_orientation get_absolute_orientation_euler_angles get_absolute_orientation_vector_z get_absolute_orientation_vectors get_absolute_position get_distance get_material get_num_faces get_num_faces_v2 get_num_materials get_num_vertices get_num_vertices_v2 get_orientation get_orientation_euler_angles get_orientation_vector_z get_orientation_vectors get_plane_equation get_position get_transform remove_all_materials remove_material render render_geometry render_geometry_draw render_geometry_finish render_geometry_prepare rotate_vertices_position rotate_vertices_position_euler_xyz scale_vertices_position set_absolute_transform_update_mode set_automatic_uniform_state set_euler_angles set_materials_texture_unit_offset set_orientation set_position set_scale set_tessellation_state set_transform set_transform_order set_vertices_color smooth_vertices_normal lua transform_update_scale translate_vertices_position update_automatic_uniforms
gh_opencl get_device_compute_units_info get_device_info get_device_type get_num_devices get_num_platforms get_platform_info
gh_physx3 windowslinuxmacos actor_add_force actor_add_force_at_position actor_apply_transform actor_clear_forces actor_get_angular_speed2 actor_get_angular_velocity actor_get_linear_speed2 actor_get_linear_velocity actor_get_orientation actor_get_position actor_get_sleep_threshold actor_is_sleeping actor_kill actor_put_to_sleep actor_set_3d_object actor_set_angular_damping actor_set_angular_velocity actor_set_euler_angles actor_set_gravity_state actor_set_kinematic_state actor_set_kinematic_target actor_set_linear_damping actor_set_linear_velocity actor_set_material actor_set_orientation actor_set_position actor_set_sleep_threshold actor_set_solver_iterations actor_update_mass actor_wake_up check_results cloth_create_from_mesh cloth_is_running_on_gpu cloth_set_external_acceleration cloth_set_gpu_state cloth_set_stiffness cloth_update_mesh_vertex_data cloth_update_particles_from_mesh_particles create_actor_box create_actor_capsule create_actor_mesh create_actor_mesh_v2 create_actor_plane create_actor_sphere create_material create_scene create_scene_broadphase_gpu create_scene_broadphase_mbp create_scene_broadphase_sap fetch_results gpu_get_clock_frequency_khz gpu_get_name gpu_get_num_multiprocessors gpu_get_total_memory_size_mb gpu_is_supported windows joint_create joint_distance_set_distances joint_distance_set_spring joint_kill joint_prismatic_set_limits joint_revolute_set_angular_limits joint_revolute_set_rotational_limits joint_set_break_force joint_set_motor_params joint_spherical_set_limit_cone kill_material particle_system_create particle_system_create_fluid particle_system_from_gxc_ps particle_system_position_from_vertex_pool particle_system_position_to_vertex_pool particle_system_to_gxc_ps run_simulation run_simulation_step scene_sync_3d_objects set_max_depenetration_velocity set_scene_gravity set_simulation_scales set_solver_iteration_counts start stop update_material
gh_physx4 windowslinuxmacos actor_add_force actor_add_force_at_position actor_apply_transform actor_clear_forces actor_get_angular_speed2 actor_get_angular_velocity actor_get_linear_speed2 actor_get_linear_velocity actor_get_orientation actor_get_position actor_get_sleep_threshold actor_is_sleeping actor_kill actor_put_to_sleep actor_set_3d_object actor_set_angular_damping actor_set_angular_velocity actor_set_euler_angles actor_set_gravity_state actor_set_kinematic_state actor_set_kinematic_target actor_set_linear_damping actor_set_linear_velocity actor_set_material actor_set_orientation actor_set_position actor_set_sleep_threshold actor_set_solver_iterations actor_update_mass actor_wake_up check_results create_actor_box create_actor_capsule create_actor_mesh create_actor_mesh_v2 create_actor_plane create_actor_sphere create_material create_scene create_scene_broadphase_abp create_scene_broadphase_gpu create_scene_broadphase_mbp create_scene_broadphase_sap create_scene_set_solver_type fetch_results gpu_get_clock_frequency_khz gpu_get_name gpu_get_num_multiprocessors gpu_get_total_memory_size_mb gpu_is_supported windows joint_create joint_distance_set_distances joint_distance_set_spring joint_kill joint_prismatic_set_limits joint_revolute_set_angular_limits joint_revolute_set_rotational_limits joint_set_break_force joint_set_motor_params joint_spherical_set_limit_cone kill_material run_simulation run_simulation_step scene_get_num_active_actors scene_sync_3d_objects scene_sync_3d_objects_v2 set_max_depenetration_velocity set_scene_gravity set_simulation_scales set_solver_iteration_counts start stop update_material
gh_polyline create_v2 get_vertex_color get_vertex_position set_vertex_color set_vertex_draw_range set_vertex_position set_vertex_position_color set_vertices_color lua set_vertices_color_v2 set_vertices_position lua wideline_add_point wideline_create wideline_reset_points wideline_set_line_width
gh_ps action_set_gravity create create_action_gravity create_emitter_point emitter_set_particle_rate_and_speed emitter_set_spawn_directions get_num_alive_particles process_particle_actions process_particle_emitters process_particles update_particles_lifetime
gh_render_target bind create create_cubemap create_depth create_ex create_ex_v3 create_rb create_v2 cubemap_set_draw_face kill resize resolve_multisampling use_with_syphon macos
gh_renderer check_opengl_extension clear_color_buffer clear_color_depth_buffers clear_depth_buffer conservative_rasterization_get_properties_nv conservative_rasterization_set_sub_pixel_precision_bias_nv disable_state display_progress_bar draw_primitives enable_state get_api_version get_api_version_major get_api_version_minor get_capability_4i get_num_opengl_extensions get_num_virtual_screens macos get_opengl_error get_opengl_extension get_renderer_model get_renderer_vendor get_shading_language_version get_virtual_screen macos glx_get_client_extension glx_get_client_num_extensions glx_get_renderer_info_int glx_get_renderer_info_str glx_get_server_extension glx_get_server_num_extensions is_opengl_es memory_barrier point rasterizer_apply_states rasterizer_set_cull_face rasterizer_set_cull_state rasterizer_set_polygon_mode set_blending_color set_blending_equation set_blending_factors set_blending_state set_depth_test_func set_depth_test_state set_line_stipple set_line_width set_scissor set_scissor_state set_texture2d_state set_viewport set_viewport_scissor set_virtual_screen macos set_vsync shader_thread_group_get_properties_nv solid update_fixed_mvp_matrices update_virtual_screen macos wireframe
gh_rpi raspberry gpio_analog_read gpio_analog_write gpio_digital_read gpio_digital_write gpio_digital_write_byte gpio_get_alt gpio_get_board_info gpio_init gpio_phys_pin_to_gpio gpio_pwm_tone_write gpio_pwm_write gpio_set_gpio_clock gpio_set_pad_drive gpio_set_pin_mode gpio_set_pin_mode_alt gpio_set_pmw_clock gpio_set_pull_up_down_control gpio_set_pwm_mode gpio_set_pwm_range gpio_wpi_pin_to_gpio rgbmatrix_fill_f32 rgbmatrix_fill_u8 rgbmatrix_get_luminance_correct rgbmatrix_get_num_pixels rgbmatrix_get_pwmbits rgbmatrix_init rgbmatrix_set_luminance_correct rgbmatrix_set_pixel_f32 rgbmatrix_set_pixel_u8 rgbmatrix_set_pwmbits rgbmatrix_terminate
gh_sqlite3 db_bind_blob_from_buffer db_bind_blob_from_file db_bind_blob_from_string db_bind_double db_bind_int db_bind_text db_close db_column_blob_to_file db_column_blob_to_string db_column_get_blob db_column_get_double db_column_get_int db_column_get_text db_column_get_text1024 db_enable_extended_result_codes db_exec db_finalize db_get_column_count db_get_column_name db_get_column_type db_get_errcode db_get_extended_errcode db_get_last_insert_rowid db_get_version db_open db_open_v2 db_prepare db_step
gh_texture bind copy_sub_texture create_1d create_2d create_cube_from_file create_from_buffer create_from_file create_from_file_v2 create_from_file_v3 create_from_file_v5 create_from_file_v6 create_from_file_v8 create_from_file_v9 create_from_sqlite3_blob create_from_sub_texture create_from_zip_file flip_horizontal get_gpu_memory_size get_num_mipmaps get_size get_texel_1d get_texel_2d gpu_mem_to_cpu_mem gpu_memory_unload gpu_memory_upload image_bind inject_opacity_map renderer_update renderer_update2d reset_texture_unit rt_color_bind_v2 rt_color_cubemap_bind rt_depth_bind rt_depth_cubemap_bind set_current_image_codec set_texel_1d set_texel_2d share_texture_data update_gpu_memory_from_buffer update_gpu_memory_from_file write_to_file_v4
gh_utils box_create box_update_size buffer_copy buffer_crc32 buffer_create buffer_kill buffer_md5 buffer_read_1f buffer_read_2f buffer_read_3f buffer_read_4f buffer_read_byte buffer_read_line buffer_sha1 buffer_sha256 buffer_to_file buffer_write_1f buffer_write_2f buffer_write_3f buffer_write_4f buffer_write_byte circle_create circle_create_v2 circle_update_radius clipboard_get_text windows clipboard_set_text windows cpu_get_mem_available_size_mb cpu_get_mem_size_mb cpu_get_name windowslinuxmacos cpu_get_speed_mhz windowslinuxmacos cpu_usage_cleanup windows cpu_usage_get_core_count windows cpu_usage_get_core_usage windows cpu_usage_init windows cpu_usage_update windows do_file_from_sqlite3_blob do_file_from_zip do_screenshot opengl do_screenshot_v2 opengl do_screenshot_v3 opengl do_screenshot_v4 opengl do_screenshot_v5 opengl drop_files_get_file_by_index windows drop_files_get_num_files windows dylib_frame dylib_get_message dylib_load dylib_resize dylib_set_message dylib_start dylib_stop dylib_unload exe_from_buffer exe_script exe_script_v2 exe_script_v3 exe_string extract_dir_from_filename file_buffer_create file_crc32 file_md5 file_sha1 file_sha256 file_size font_create font_render font_render3d font_set_viewport_info ftgl_font_add_text2d ftgl_font_add_text3d ftgl_font_clear ftgl_font_create ftgl_font_kill ftgl_font_render ftgl_font_texture_kill ftgl_font_texture_load get_app_dir get_app_version get_command_line get_date_str get_demo_dir get_demo_zip_filename get_elapsed_time get_lib_dir get_os_info get_platform get_platform_name get_time_step get_uptime global_array_char_alloc global_array_char_get global_array_char_set global_array_float_alloc global_array_float_get global_array_float_set global_array_int_alloc global_array_int_get global_array_int_set grid_create grid_set_display_lines_options grid_set_geometry_params grid_set_lines_color grid_set_main_lines_color grid_set_main_x_axis_color grid_set_main_z_axis_color hex_color_to_rgb is_64bit is_luajit luawindows is_rpi line_create line_set_end_color line_set_end_position line_set_start_color line_set_start_position math_length_vec3 math_normalize_vec3 math_quat_from_lookat math_quat_from_vectors_rotation nfd_open_dialog macos nfd_pick_folder macos nfd_save_dialog macos open_url pack_rgba_u8 windows printc progress_bar_inc progress_bar_set project_3d_to_2d_v1 project_3d_to_2d_v2 random raycast_cast_ray raycast_cast_ray_v2 raycast_get_ray raycast_get_ray_ortho_cam sanitize_string shared_variable_create shared_variable_create_array shared_variable_get_array_value_1f shared_variable_get_array_value_1i shared_variable_get_array_value_str shared_variable_get_value_4f shared_variable_get_value_str shared_variable_is_exist shared_variable_kill shared_variable_set_array_value_1f shared_variable_set_array_value_1i shared_variable_set_array_value_str shared_variable_set_value_4f shared_variable_set_value_str sphere_create sphere_update_radius stop_demo sys_exec thread_sleep trace trackball_get_orientation trackball_init tripod_visualizer_camera_render unpack_rgba_u8 windows vendor_name_from_vendor_id webcam_create windows webcam_get_frame_size windows webcam_get_name windows webcam_get_num windows webcam_grab_frame windows webcam_kill windows webcam_start windows webcam_stop windows webcam_update_texture windows win_registry_create_key windows win_registry_delete_key windows win_registry_read_value_dword windows win_registry_read_value_string windows win_registry_write_value_dword windows win_registry_write_value_string windows zip_buffer_create zip_to_file
gh_vb bind create draw_lines draw_points draw_triangles kill map set_value_1f set_value_1ui set_value_2f set_value_3f set_value_4f set_value_4x4f set_vertex_attrib_data unbind unmap
gh_vertex_pool create render set_vertex_source vb_get_vertex_color vb_get_vertex_normal vb_get_vertex_position vb_get_vertex_tangent vb_map vb_set_vertex_color vb_set_vertex_normal vb_set_vertex_position vb_set_vertex_tangent vb_unmap vertex_get_color vertex_get_position vertex_set_color vertex_set_position vertices_from_gpu_buffer vertices_to_gpu_buffer
gh_vr apply_controller_transform get_controller_button_state get_num_controllers get_recommended_render_target_size is_initialized submit update_cameras update_cameras_v2 update_controller_transform update_controllers_state
gh_window getsize set_alpha windows timer_get_milliseconds timer_get_seconds timer_reset
gh_asus_aura windows get_gpu_light_ctrl_num_leds get_mb_light_ctrl_num_leds get_num_gpu_light_ctrl get_num_mb_light_ctrl set_gpu_led_color set_gpu_mode set_mb_led_color set_mb_mode


GeeXLab Rootard Guide | Downloads | Contact | Newsletter