GLSL Hacker
FEATURES DOWNLOAD GALLERY BLOG LEARN



» Back to Reference Guide Index

gh_utils Library

Description

gh_utils is the module that provides various utility functions.

Number of functions: 60


gh_utils.get_platform

Description

Returns the platform: Windows (1), OSX (2) or Linux (3).

Languages

Lua - Python

Parameters

This function has no input parameter(s).

Return Values

  • platform [INTEGER]: 1 for Windows, 2 for OSX, 3 for Linux, 4 for Raspberry Pi.

    Code sample


    platform = gh_utils.get_platform()


    gh_utils.get_platform_name

    Description

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

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • platform_name [STRING]: the name of the platform.

    Code sample


    platform_name = gh_utils.get_platform_name()


    gh_utils.is_64bit

    Description

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

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • state [INTEGER]: 1 for 64-bit and 0 otherwise.

    Code sample


    app_64bit = gh_utils.is_64bit()


    gh_utils.random

    Description

    Returns a random floating point number between 0.0 and 1.0.

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • x [REAL]: randon number.

    Code sample


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


    gh_utils.get_elapsed_time

    Description

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

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • elapsed_time [REAL]: elapsed time in seconds.

    Code sample


    elapsed_time = gh_utils.get_elapsed_time()


    gh_utils.trace

    Description

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

    Languages

    Lua - Python

    Parameters

  • str [STRING]: Trace to write.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.trace("Hello world!")


    gh_utils.open_url

    Description

    Open an URL in the default browser.

    Languages

    Lua - Python

    Parameters

  • str [STRING]: url.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.open_url("http://www.geeks3d.com")


    gh_utils.raycast_get_ray

    Description

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

    Languages

    Lua - Python

    Parameters

  • screen_x, screen_y [INTEGER]: Screen position
  • camera_id [INTEGER]: current bound camera.

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


    gh_utils.raycast_cast_ray

    Description

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

    Languages

    Lua - Python

    Parameters

  • object_id [INTEGER]: tested object.
  • ro_x, ro_y, ro_z, rd_x, rd_y, rd_z [REAL]: 3D ray: ro (ray origin) and rd (ray direction)
  • camera_id [INTEGER]: current bound camera.

    Return Values

  • face_index [INETGER]: collision face index.
  • collision_time [REAL]: collision time.
  • collision_pos_x, collision_pos_y, collision_pos_z [REAL]: collision point.

    Code sample


    face_index, collision_time, collision_pos_x, collision_pos_y, collision_pos_z = gh_utils.raycast_cast_ray(mesh, ro_x, ro_y, ro_z, rd_x, rd_y, rd_z)


    gh_utils.webcam_create

    Description

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

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • webcam [INTEGER]: webcam identifier.

    Code sample


    webcam = gh_utils.webcam_create()


    gh_utils.webcam_kill

    Description

    Kills a webcam object (Windows only).

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.webcam_kill(webcam)


    gh_utils.webcam_start

    Description

    Initializes a webcam (Windows only).

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.
  • webcam_number [INTEGER]: index of the webcam. Default: 1. First webcam=1, second=2, and so on.

    Return Values

  • ret [INTEGER]: returns 1 if ok else 0.

    Code sample


    ret = gh_utils.webcam_start(webcam, 1)
    if (ret == 1) then
    -- Webcam started ok.
    end


    gh_utils.webcam_stop

    Description

    Stops a webcam (Windows only).

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.webcam_stop(webcam)


    gh_utils.webcam_get_name

    Description

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

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.

    Return Values

    This function has no return value(s).

    Code sample


    name = gh_utils.webcam_get_name(webcam)


    gh_utils.webcam_grab_frame

    Description

    Updates the webcam (Windows only).

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.webcam_grab_frame(webcam)


    gh_utils.webcam_get_frame_size

    Description

    Gets the size of a frame (Windows only).

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.

    Return Values

  • width, height [INTEGER]: size of a frame.

    Code sample


    w, h = gh_utils.webcam_get_frame_size(webcam)


    gh_utils.webcam_update_texture

    Description

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

    Languages

    Lua - Python

    Parameters

  • webcam [INTEGER]: webcam identifier.
  • texture [INTEGER]: texture identifier.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.webcam_update_texture(webcam, texture)


    gh_utils.font_create

    Description

    Creates a new font.

    Languages

    Lua - Python

    Parameters

  • font_name [STRING]: True type font name, ex: Arial, Verdana.
  • height [INTEGER]: font height.

    Return Values

  • font [INTEGER]: font identifier.

    Code sample


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


    gh_utils.font_set_viewport_info

    Description

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

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: font identifier.
  • x, y [INTEGER]: viewport offsets.
  • width, height [INTEGER]: viewport size.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.font_render

    Description

    Renders (draws) a text.

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: 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

    This function has no return value(s).

    Code sample


    gh_utils.font_set_viewport_info(font, 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))


    gh_utils.font_render3d

    Description

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

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: 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

    This function has no return value(s).

    Code sample


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


    gh_utils.thread_sleep

    Description

    Allows to pause the current thread.

    Languages

    Lua - Python

    Parameters

  • delay [INTEGER]: pause delay in milliseconds.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.thread_sleep(2000)


    gh_utils.get_demo_dir

    Description

    Gets the directory of the current scene file.

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • dir [STRING]: directory of the current scene file.

    Code sample


    demo_dir = gh_utils.get_demo_dir()


    gh_utils.get_host_app_dir

    Description

    Gets the directory of GLSL Hacker.

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • dir [STRING]: directory.

    Code sample


    app_dir = gh_utils.get_host_app_dir()


    gh_utils.get_scripting_libs_dir

    Description

    Gets the directory of GLSL Hacker common librairies (Lua and Python) used by demos. The defaulkt location is GLSLHacker/libs/

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • dir [STRING]: directory.

    Code sample


    libs_dir = gh_utils.get_scripting_libs_dir()


    gh_utils.drop_files_get_num_files

    Description

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

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • num_files [INTEGER]: number of dropped files

    Code sample


    num_files = gh_utils.drop_files_get_num_files()


    gh_utils.drop_files_get_file_by_index

    Description

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

    Languages

    Lua - Python

    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


    gh_utils.set_progress_bar_percent

    Description

    Sets the progress bar size in percent of the current window width. Coupled with gh_renderer.display_progress_bar(), these functions can be used in an INIT script to draw a progress bar while loading data.

    Languages

    Lua - Python

    Parameters

  • percent [REAL]: size of the progress bar: 100% means the window width.

    Return Values

    This function has no return value(s).

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


    gh_utils.set_progress_bar_caption

    Description

    Sets the caption (or title) of the progress bar.

    Languages

    Lua - Python

    Parameters

  • caption [STRING]: title of the progress bar.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.set_progress_bar_caption("Loading scene data...")
    gh_utils.set_progress_bar_percent(20)
    gh_renderer.display_progress_bar()


    gh_utils.do_screenshot

    Description

    Does a screenshot and write it to a file (JPEG file).

    Languages

    Lua - Python

    Parameters

  • filename [STRING]: name of the screenshot file.
  • is_absolute_path [INTEGER]: specifies whether the filename is absolute or relative to the main demo XML script.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.exe_script

    Description

    Executes a script.

    Languages

    Lua - Python

    Parameters

  • name [STRING]: Name of the script.
  • threaded [INTEGER]: Runs (1) the script in a separate system thread or not (0).

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.grid_create

    Description

    Creates a grid object.

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • grid [INTEGER]: grid identifier.

    Code sample


    grid = gh_utils.grid_create()


    gh_utils.grid_set_geometry_params

    Description

    Sets grid sizes and subdivisions.

    Languages

    Lua - Python

    Parameters

  • grid [INTEGER]: grid identifier.
  • x_size, z_size [REAL]: size.
  • x_div, z_div [INTEGER]: subdivisions.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.grid_set_lines_color

    Description

    Sets grid color.

    Languages

    Lua - Python

    Parameters

  • grid [INTEGER]: grid identifier.
  • r, g, b, a [REAL]: color.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.grid_set_main_lines_color

    Description

    Sets the color of main lines.

    Languages

    Lua - Python

    Parameters

  • grid [INTEGER]: grid identifier.
  • r, g, b, a [REAL]: color.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.grid_set_main_x_axis_color

    Description

    Sets the color of the main X axis.

    Languages

    Lua - Python

    Parameters

  • grid [INTEGER]: grid identifier.
  • r, g, b, a [REAL]: color.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.grid_set_main_z_axis_color

    Description

    Sets the color of the main Z axis.

    Languages

    Lua - Python

    Parameters

  • grid [INTEGER]: grid identifier.
  • r, g, b, a [REAL]: color.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.tripod_visualizer_camera_render

    Description

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

    Languages

    Lua - Python

    Parameters

  • camera [INTEGER]: camera identifier.
  • x_offset, y_offset, width, height [INTEGER]: viewport size.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.shared_variable_create

    Description

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

    Languages

    Lua - Python

    Parameters

  • name [STRING]: name.

    Return Values

  • sv [INTEGER]: shared var identifier.

    Code sample


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


    gh_utils.shared_variable_kill

    Description

    Destroys a shared variable.

    Languages

    Lua - Python

    Parameters

  • sv_name [STRING]: shared var name.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.shared_variable_kill(sv1_name)


    gh_utils.shared_variable_is_exist

    Description

    Checks if a shared variable exists.

    Languages

    Lua - Python

    Parameters

  • sv_name [STRING]: shared var name.

    Return Values

  • is_exist [INTEGER]: exists (1) or not (0).

    Code sample


    state = gh_utils.shared_variable_is_exist(sv_name)


    gh_utils.shared_variable_set_value_4f

    Description

    Sets a 4D value.

    Languages

    Lua - Python

    Parameters

  • sv_name [STRING]: shared var name.
  • x, y, z, w [REAL]: 4D value.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.shared_variable_get_value_4f

    Description

    Gets a 4D value.

    Languages

    Lua - Python

    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)


    gh_utils.shared_variable_set_value_str

    Description

    Sets a string value.

    Languages

    Lua - Python

    Parameters

  • sv_name [STRING]: shared var name.
  • str [STRING]: string value.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.shared_variable_set_value_str(sv_name, str)


    gh_utils.shared_variable_get_value_str

    Description

    Gets a string value.

    Languages

    Lua - Python

    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)


    gh_utils.dylib_load

    Description

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

    Languages

    Lua - Python

    Parameters

  • dylib_filename [STRING]: full path to the dynamic lib.

    Return Values

  • dylib_id [INTEGER]: identifier of the dylib.

    Code sample


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


    gh_utils.dylib_unload

    Description

    unloads a dynamic library.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.dylib_unload(dylib_id)


    gh_utils.dylib_start

    Description

    Calls the start function of a dynamic library.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.
  • width, height [INTEGER]: width and height of the 3D window.
  • data [STRING]: user data.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.dylib_stop

    Description

    Calls the stop function of a dynamic library.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.
  • data [STRING]: user data.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.dylib_stop(dylib_id, "")


    gh_utils.dylib_frame

    Description

    Calls the frame function of a dynamic library.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.
  • elapsed_time [REAL]: elapsed time in seconds.
  • data [STRING]: user data.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.dylib_frame(dylib_id, elapsed_time, "")


    gh_utils.dylib_resize

    Description

    Calls the frame function of a dynamic library.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.
  • width, height [INTEGER]: width and height of the 3D window.
  • data [STRING]: user data.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.dylib_set_message

    Description

    Sets a message. Allows to communicate with the dylib.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.
  • message [STRING]: message.

    Return Values

    This function has no return value(s).

    Code sample


    message = "....."
    gh_utils.dylib_set_message(dylib_id, message)


    gh_utils.dylib_set_message

    Description

    Gets a message. Allows to communicate with the dylib.

    Languages

    Lua - Python

    Parameters

  • dylib_id [INTEGER]: identifier of the dylib.

    Return Values

  • message [STRING]: message.

    Code sample


    message = gh_utils.dylib_get_message(dylib_id)


    gh_utils.ftgl_font_texture_load

    Description

    Loads a font texture from a true type font (TTF) file.

    Languages

    Lua - Python

    Parameters

  • filename [STING]: true type font file
  • height [INTEGER]: height of font glyphs.
  • texture_width, texture_height [INTEGER]: width and height of the font texture.
  • _5, _6 [INTEGER]: reserved.

    Return Values

  • font_texture [INTEGER]: font texture identifier.

    Code sample


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


    gh_utils.ftgl_font_create

    Description

    Creates a font object from a font texture.

    Languages

    Lua - Python

    Parameters

  • font_texture [INTEGER]: font texture identifier.

    Return Values

  • font [INTEGER]: font identifier.

    Code sample


    font = gh_utils.ftgl_font_create(font_texture)


    gh_utils.ftgl_font_add_text2d

    Description

    Adds a 2D text in a font.

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: 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

    This function has no return value(s).

    Code sample


    gh_utils.ftgl_font_add_text2d(font, 10, 20, 1.0, 0.0, 0.0, 1.0, "GLSL Hacker line1")
    gh_utils.ftgl_font_add_text2d(font, 10, 40, 1.0, 0.0, 0.0, 1.0, "GLSL Hacker line2")


    gh_utils.ftgl_font_clear

    Description

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

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: font identifier.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.ftgl_font_render

    Description

    Renders a 2D font.

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: font identifier.

    Return Values

    This function has no return value(s).

    Code sample


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


    gh_utils.ftgl_font_kill

    Description

    Kills a font (TERMINATE script)

    Languages

    Lua - Python

    Parameters

  • font [INTEGER]: font identifier.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.ftgl_font_kill(font)


    gh_utils.ftgl_font_texture_kill

    Description

    Kills a font texture (TERMINATE script)

    Languages

    Lua - Python

    Parameters

  • font_texture [INTEGER]: font texture identifier.

    Return Values

    This function has no return value(s).

    Code sample


    gh_utils.ftgl_font_texture_kill(font_texture)





    2013-2015 Geeks3D. All Rights Reserved.

    .:- G3D Network -:.