Quick Links
  • Homepage
        - Overview
        - Download
        - Screenshots
        - Community
  • Code Sample Pack
  • Reference Guide
  • Changelog
  • Overview of GLSL Hacker
  • Live Coding
  • Hack your first GLSL Code
  • Moon3D




  • GLSL Hacker Articles

    > Compute shaders on Radeon
    > Distance functions in GLSL
    > GLSL Interpolation Qualifiers
    > Tessellation Spacing Modes
    > Normal Visualizer with GS
    > 3D Surface Plots
    > Normal Mapping
    > Circle and Disc in GLSL
    > PhysX 3 Flag Demo
    > GLSL Hacker on Raspberry Pi
    GLSL Hacker

    Reference Guide
    Host-API Lua / Python



    Back to Homepage
    Back to Developer's Guide Index

    gh_utils Library


    Description
    gh_utils is the module that provides various utility functions.

    Number of functions: 53

    gh_utils.get_platform

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

    Languages: Lua - Python

    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

    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

    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

    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

    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.

    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.

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

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    Code sample :

    gh_utils.thread_sleep(2000)


    gh_utils.get_demo_dir

    Description
    Gets the directory of the current scene file.

    Languages: Lua - Python

    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

    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

    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

    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.

    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.

    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.

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

    Code sample :

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


    gh_utils.grid_create

    Description
    Creates a grid object.

    Languages: Lua - Python

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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)





  • (C)2012-2014 Geeks3D