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

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





  • (C)2012-2013 Geeks3D