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_mesh Library


Description
gh_mesh is the module that manages meshes. A mesh is a set of triangular faces that allows 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.

Number of functions: 35

gh_mesh.create

Description
Creates a mesh.

Languages: Lua - Python

Return Values
  • mesh [INTEGER]: mesh identifier

    Code sample :

    mesh = gh_mesh.create()


    gh_mesh.alloc_mesh_data

    Description
    Allocates memory for mesh data (vertices and faces lists).

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • num_vertices [INTEGER]: number of vertices.
  • num_faces [INTEGER]: number of faces

    Code sample :

    mesh_triangle = gh_mesh.create()
    gh_mesh.alloc_mesh_data(mesh_triangle, 3, 1)


    gh_mesh.create_plane

    Description
    Creates a mesh plane.

    Languages: Lua - Python

    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 [INTEGER]: mesh identifier

    Code sample :

    mesh_plane = gh_mesh.create_plane(20.0, 10.0, 4, 4)


    gh_mesh.create_quad

    Description
    Creates a mesh quad. A quad is a mesh plane with only 4 vertices.

    Languages: Lua - Python

    Parameters
  • width, height [REAL]: size of the quad in the XY plane.

    Return Values
  • mesh [INTEGER]: mesh identifier

    Code sample :

    mesh_quad = gh_mesh.create_quad(20.0, 10.0)


    gh_mesh.update_quad_size

    Description
    Updates the width and height of a mesh quad.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • width, height [REAL]: size of the quad in the XY plane.

    Code sample :

    gh_mesh.update_quad_size(mesh_quad, 20.0, 15.0)


    gh_mesh.create_sphere

    Description
    Creates a mesh sphere.

    Languages: Lua - Python

    Parameters
  • radius [REAL]: Radius of the sphere.
  • stacks, slices [INTEGER]: number of subdivisions along the X and Y axis.

    Return Values
  • mesh [INTEGER]: mesh identifier

    Code sample :

    mesh_sphere = gh_mesh.create_sphere(10.0, 20, 20)


    gh_mesh.create_torus

    Description
    Creates a mesh torus.

    Languages: Lua - Python

    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 [INTEGER]: mesh identifier

    Code sample :

    mesh_torus = gh_mesh.create_torus(10.0, 4.0, 20)


    gh_mesh.create_cylinder

    Description
    Creates a mesh cylinder.

    Languages: Lua - Python

    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 [INTEGER]: mesh identifier

    Code sample :

    mesh_cyl = gh_mesh.create_cylinder(radius, height, stacks, slices)


    gh_mesh.create_ellipse

    Description
    Creates a mesh ellipse.

    Languages: Lua - Python

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


    gh_mesh.create_triangle

    Description
    Creates a mesh triangle. Vertices are positioned in the range [-1.0;+1.0].

    Languages: Lua - Python

    Return Values
  • mesh [INTEGER]: mesh identifier

    Code sample :

    mesh_triangle = gh_mesh.create_triangle()


    gh_mesh.create_terrain

    Description
    Creates a mesh terrain from a height map.

    Languages: Lua - Python

    Parameters
  • texture_id [INTEGER]: terrain texture (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 [INTEGER]: mesh identifier

    Code sample :

    mesh_terrain = gh_mesh.create_terrain(texture_id, num_subdivisions, vertical_scale, terrain_size, height_threshold)


    gh_mesh.init_instancing

    Description
    Initializes the geometry instancing rendering.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • num_instances [INTEGER]: number of instances.

    Code sample :

    num_instances = 1000
    gh_mesh.init_instancing(mesh, num_instances)


    gh_mesh.set_instance_position

    Description
    Sets the position of a particular instance.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • index [INTEGER]: index of the instance from 0 to num_instances-1.
  • x, y, z [REAL]: position of the instance.

    Code sample :

    local num_instances = 1000
    gh_mesh.init_instancing(mesh, num_instances)
    local instance_index = 0
    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.set_instance_position(mesh, instance_index, x, y, z)
    x = math.random(-60, 60)
    y = math.random(-60, 60)
    z = math.random(-60, 60)
    gh_mesh.set_instance_orientation(mesh, instance_index, x, y, z)
    instance_index = instance_index+1
    end


    gh_mesh.set_instance_orientation

    Description
    Sets the orientation of a particular instance using Euler's angles.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: 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.

    Code sample :

    local num_instances = 1000
    gh_mesh.init_instancing(mesh, num_instances)
    local instance_index = 0
    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.set_instance_position(mesh, instance_index, x, y, z)
    x = math.random(-60, 60)
    y = math.random(-60, 60)
    z = math.random(-60, 60)
    gh_mesh.set_instance_orientation(mesh, instance_index, x, y, z)
    instance_index = instance_index+1
    end


    gh_mesh.set_vertex_position

    Description
    Sets the relative position of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • vertex_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.
  • x, y, z [REAL]: 3D position

    Code sample :

    vertex_index = 0
    gh_mesh.set_vertex_position(mesh, vertex_index, x, y, z)


    gh_mesh.get_vertex_position

    Description
    Gets the relative position of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object 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_position(mesh, vertex_index)


    gh_mesh.get_vertex_absolute_position

    Description
    Gets the absolute position of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object 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, vertex_index)


    gh_mesh.set_vertices_color

    Description
    Sets the RGBA color of all vertices.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • r, g, b, a [REAL]: rgba color of the vertex

    Code sample :

    gh_mesh.set_vertices_color(mesh, r, g, b, a)


    gh_mesh.set_vertex_color

    Description
    Sets the RGBA color of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object 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

    Code sample :

    vertex_index = 0
    gh_mesh.set_vertex_color(mesh, vertex_index, r, g, b, a)


    gh_mesh.get_vertex_color

    Description
    Gets the RGBA color of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object 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, vertex_index)


    gh_mesh.set_vertex_normal

    Description
    Sets the normal vector of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • vertex_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.
  • x, y, z [REAL]: normal vector

    Code sample :

    vertex_index = 0
    gh_mesh.set_vertex_normal(mesh, vertex_index, x, y, z)


    gh_mesh.get_vertex_normal

    Description
    Gets the normal vector of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object 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, vertex_index)


    gh_mesh.set_vertex_tangent

    Description
    Sets the tangent vector of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • vertex_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.
  • x, y, z, w [REAL]: tangent vector

    Code sample :

    vertex_index = 0
    gh_mesh.set_vertex_tangent(mesh, vertex_index, x, y, z, w)


    gh_mesh.get_vertex_tangent

    Description
    Gets the tangent vector of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object 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, vertex_index)


    gh_mesh.set_vertex_uv

    Description
    Sets the texcoord of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • vertex_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.
  • x, y, z, w [REAL]: texcoord
  • texture_unit [INTEGER]: texture unit of the texcoord set. Only two sets are supported.

    Code sample :

    vertex_index = 0
    texture_unit = 0
    gh_mesh.set_vertex_uv(mesh, vertex_index, x, y, z, w, texture_unit)


    gh_mesh.get_vertex_uv

    Description
    Gets the texcoord of a particular vertex.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • vertex_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.
  • texture_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
    texture_unit = 0
    x, y, z, w = gh_mesh.get_vertex_uv(mesh, vertex_index, texture_unit)


    gh_mesh.set_face_vertex_indices

    Description
    Sets the vertex indices of a particular face.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • face_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.
  • a, b, c [INTEGER]: vertex indices

    Code sample :

    gh_mesh.set_face_vertex_indices(mesh, face_index, a, b, c)


    gh_mesh.get_face_vertex_indices

    Description
    Gets the vertex indices of a particular face.

    Languages: Lua - Python

    Parameters
  • object_id [INTEGER]: Object identifier.
  • face_index [INTEGER]: index of the vertex between 0 and gh_object.get_num_vertices()-1.

    Return Values
  • a, b, c [INTEGER]: vertex indices

    Code sample :

    a, b, c = gh_mesh.get_face_vertex_indices(mesh, face_index)


    gh_mesh.user_geometry_add_vertex

    Description
    Adds a new vertex to the mesh. Allows to create customized meshes.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • x, y, z [REAL]: position of the vertex.

    Return Values
  • index [INTEGER]: Zero-based index of the new vertex

    Code sample :

    index = gh_mesh.user_geometry_add_vertex(mesh, x, y, z)


    gh_mesh.user_geometry_set_vertex_position

    Description
    Sets the position attribute of a vertex created with user_geometry_add_vertex().

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • index [INTEGER]: index of the vertex.
  • x, y, z [REAL]: position of the vertex.

    Code sample :

    gh_mesh.user_geometry_set_vertex_position(mesh, index, x, y, z)


    gh_mesh.user_geometry_set_vertex_color

    Description
    Sets the color attribute of a vertex created with user_geometry_add_vertex().

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • index [INTEGER]: index of the vertex.
  • r, g, b, a [REAL]: RGBA color of the vertex.

    Code sample :

    gh_mesh.user_geometry_set_vertex_color(mesh, index, r, g, b, a)


    gh_mesh.user_geometry_set_vertex_normal

    Description
    Sets the normal vector attribute of a vertex created with user_geometry_add_vertex().

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • index [INTEGER]: index of the vertex.
  • x, y, z [REAL]: XYZ coordinates of the normal vector.

    Code sample :

    gh_mesh.user_geometry_set_vertex_normal(mesh, index, x, y, z)


    gh_mesh.user_geometry_set_vertex_uv0

    Description
    Sets the texture coordinates UV0 attribute of a vertex created with user_geometry_add_vertex().

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • index [INTEGER]: index of the vertex.
  • x, y, z, w [REAL]: XYZW coordinates of UV0. Usually, only XY are used and ZW are set to 0.

    Code sample :

    gh_mesh.user_geometry_set_vertex_uv0(mesh, index, x, y, 0, 0)


    gh_mesh.user_geometry_add_face

    Description
    Adds a new face to the mesh. The face is made up of three vertex indices.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.
  • a, b, c [INTEGER]: Indices of three vertices that make up the face.

    Code sample :

    gh_mesh.user_geometry_add_face(mesh, 0, 1, 2)


    gh_mesh.build

    Description
    Builds the mesh. Useful with user_geometry_add_vertex() and user_geometry_add_face() functions.

    Languages: Lua - Python

    Parameters
  • mesh [INTEGER]: mesh identifier.

    Code sample :

    mesh = gh_mesh.create()
    gh_object.setpos(mesh, 0, 0, 0)
    gh_object.set_euler_angles(mesh, 0, 0, 0)

    -- A triangle: 3 vertices and 1 face!
    -- See the howto_build_the_triangle.jpg image for some details about how to build the triangle.
    -- Step 1: the vertices
    --
    index = gh_mesh.user_geometry_add_vertex(mesh, -5, -5, 0)
    gh_mesh.user_geometry_set_vertex_color(mesh, index, 1, 0, 0, 1)

    index = gh_mesh.user_geometry_add_vertex(mesh, 0, 5, 0)
    gh_mesh.user_geometry_set_vertex_color(mesh, index, 0, 1, 0, 1)

    index = gh_mesh.user_geometry_add_vertex(mesh, 5, -5, 0)
    gh_mesh.user_geometry_set_vertex_color(mesh, index, 0, 0, 1, 1)

    -- Step 2: the faces
    --
    gh_mesh.user_geometry_add_face(mesh, 0, 1, 2)

    -- Step 3: build the mesh
    --
    gh_mesh.build(mesh)





  • (C)2012-2013 Geeks3D