< GeeXLab Reference Guide />

gh_mesh library

Description

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.

Number of functions: 65

gh_mesh.alloc_mesh_data ()
gh_mesh.create_box ()
gh_mesh.create_box_8v ()
gh_mesh.create_cylinder ()
gh_mesh.create_cylinder_xyz ()
gh_mesh.create_disc ()
gh_mesh.create_ellipse ()
gh_mesh.create_gear ()
gh_mesh.create_icosphere ()
gh_mesh.create_plane ()
gh_mesh.create_plane_v3 ()
gh_mesh.create_quad ()
gh_mesh.create_sphere ()
gh_mesh.create_terrain ()
gh_mesh.create_torus ()
gh_mesh.create_triangle ()
gh_mesh.create_v2 ()
gh_mesh.get_face_normal ()
gh_mesh.get_face_vertex_indices ()
gh_mesh.get_vertex_absolute_position ()
gh_mesh.get_vertex_color ()
gh_mesh.get_vertex_normal ()
gh_mesh.get_vertex_position ()
gh_mesh.get_vertex_tangent ()
gh_mesh.get_vertex_uv ()
gh_mesh.instancing_attrib_buffer_get ()
gh_mesh.instancing_attrib_buffer_update_needed ()
gh_mesh.instancing_get_color ()
gh_mesh.instancing_get_orientation ()
gh_mesh.instancing_get_position ()
gh_mesh.instancing_get_scale ()
gh_mesh.instancing_init ()
gh_mesh.instancing_set_axis_angle ()
gh_mesh.instancing_set_color ()
gh_mesh.instancing_set_orientation ()
gh_mesh.instancing_set_orientation_v2 ()
gh_mesh.instancing_set_position ()
gh_mesh.instancing_set_position_v2 ()
gh_mesh.instancing_set_scale ()
gh_mesh.resize_box ()
gh_mesh.resize_plane ()
gh_mesh.resize_quad ()
gh_mesh.ribbon_add_point ()
gh_mesh.ribbon_create ()
gh_mesh.ribbon_set_cross_vector ()
gh_mesh.set_face_vertex_indices ()
gh_mesh.set_vertex_color ()
gh_mesh.set_vertex_normal ()
gh_mesh.set_vertex_position ()
gh_mesh.set_vertex_tangent ()
gh_mesh.set_vertex_uv ()
gh_mesh.set_vertices_color ()
gh_mesh.voxelize ()
gh_mesh.meshlet_generate ()
gh_mesh.meshlet_get_count ()
gh_mesh.meshlet_get_vertex_count ()
gh_mesh.meshlet_get_index_count ()
gh_mesh.meshlet_get_vertex ()
gh_mesh.meshlet_get_index ()
gh_mesh.set_vertex_alloc_params_separate_vertex_arrays ()
gh_mesh.vertices_to_gpu_buffer ()
gh_mesh.vertices_from_gpu_buffer ()
gh_mesh.vertices_position_to_gpu_buffer ()
gh_mesh.vertices_position_from_gpu_buffer ()
gh_mesh.set_vertex_source ()

alloc_mesh_data

Description

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

Syntax

gh_mesh.alloc_mesh_data( mesh_id, num_vertices, num_faces )

Languages

Parameters

mesh_id [ID]: mesh identifier
num_vertices [INTEGER]: number of vertices
num_faces [INTEGER]: number of faces

Return Values

This function has no return value(s).

Code sample


mesh_triangle = gh_mesh.create()

gh_mesh.alloc_mesh_data(mesh_triangle, 3, 1)

create_box

Description

Creates a mesh box.

Syntax

mesh_id = gh_mesh.create_box( width, height, depth, wsegs, hsegs, dsegs )

Languages

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

Description

Creates a mesh box with 8 vertices.

Syntax

mesh_id = gh_mesh.create_box_8v( width, height, depth )

Languages

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

Description

Creates a mesh cylinder.

Syntax

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

Languages

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

Description

Creates a mesh cylinder.

Syntax

mesh_id = gh_mesh.create_cylinder_xyz( central_axis, radius, height, stacks, slices )

Languages

Parameters

central_axis [ENUM]: 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

Description

Creates a mesh disc.

Syntax

mesh_id = gh_mesh.create_disc( radius, thickness, slices )

Languages

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

Description

Creates a mesh ellipse.

Syntax

mesh_id = gh_mesh.create_ellipse( major_radius, minor_radius, slices, radius_segments, opening_angle )

Languages

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

Description

Creates a mesh gear.

Syntax

mesh_id = gh_mesh.create_gear( inner_radius, outer_radius, tooth_depth, num_teeth, width )

Languages

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

Description

Creates an ico-sphere mesh.

Syntax

mesh_id = gh_mesh.create_icosphere( radius, recursion_level )

Languages

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

Description

Creates a mesh plane.

Syntax

mesh_id = gh_mesh.create_plane( width, height, wsegs, hsegs )

Languages

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

Description

Creates a mesh plane with an initial rotation.

Syntax

mesh_id = gh_mesh.create_plane_v3( width, height, wsegs, hsegs, pitch, yaw, roll )

Languages

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

Description

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

Syntax

mesh_id = gh_mesh.create_quad( width, height )

Languages

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

Description

Creates a mesh sphere.

Syntax

mesh_id = gh_mesh.create_sphere( radius, stacks, slices )

Languages

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

Description

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 )

Languages

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

Description

Creates a mesh torus.

Syntax

mesh_id = gh_mesh.create_torus( outer_radius, inner_radius, slices )

Languages

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

Description

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

Syntax

mesh_id = gh_mesh.create_triangle()

Languages

Parameters

This function has no input parameter(s).

Return Values

mesh_id [ID]: mesh identifier

Code sample


mesh_triangle = gh_mesh.create_triangle()

create_v2

Description

Creates a mesh.

Syntax

mesh_id = gh_mesh.create_v2()

Languages

Parameters

This function has no input parameter(s).

Return Values

mesh_id [ID]: mesh identifier

Code sample


mesh_id = gh_mesh.create_v2()

get_face_normal

Description

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 )

Languages

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

Description

Gets the vertex indices of a particular face.

Syntax

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

Languages

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

Description

Gets the absolute position of a particular vertex.

Syntax

x, y, z = gh_mesh.get_vertex_absolute_position( mesh_id, vertex_index )

Languages

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

Description

Gets the RGBA color of a particular vertex.

Syntax

r, g, b, a = gh_mesh.get_vertex_color( mesh_id, vertex_index )

Languages

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

Description

Gets the normal vector of a particular vertex.

Syntax

x, y, z = gh_mesh.get_vertex_normal( mesh_id, vertex_index )

Languages

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

Description

Gets the relative position of a particular vertex.

Syntax

x, y, z, w = gh_mesh.get_vertex_position( mesh_id, vertex_index )

Languages

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

Description

Gets the tangent vector of a particular vertex.

Syntax

x, y, z, w = gh_mesh.get_vertex_tangent( mesh_id, vertex_index )

Languages

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

Description

Gets the texcoord of a particular vertex.

Syntax

x, y, z, w = gh_mesh.get_vertex_uv( mesh_id, vertex_index, tex_unit )

Languages

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

Description

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 )

Languages

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

Description

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 )

Languages

Parameters

mesh_id [ID]: mesh identifier
va_index [INTEGER]: vertex attrib index

Return Values

This function has no return value(s).

Code sample


va_index = 0
gh_mesh.instancing_attrib_buffer_update_needed(mesh_id, va_index)

instancing_get_color

Description

Gets the color of a particular instance.

Syntax

r, g, b, a = gh_mesh.instancing_get_color( mesh_id, index )

Languages

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

Description

Gets the orientation of a particular instance.

Syntax

x, y, z, w = gh_mesh.instancing_get_orientation( mesh_id, index )

Languages

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

Description

Gets the position of a particular instance.

Syntax

x, y, z, w = gh_mesh.instancing_get_position( mesh_id, index )

Languages

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

Description

Gets the scale of a particular instance.

Syntax

x, y, z, w = gh_mesh.instancing_get_scale( mesh_id, index )

Languages

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

Description

Initializes the geometry instancing rendering.

Syntax

gh_mesh.instancing_init( mesh_id, num_instances )

Languages

Parameters

mesh_id [ID]: mesh identifier
num_instances [INTEGER]: number of instances

Return Values

This function has no return value(s).

Code sample


-- mesh instancing requires separate vertex arrays.
separate_vertex_arrays = 1
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

Description

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 )

Languages

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

This function has no return value(s).

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

Description

Sets the color of a particular instance.

Syntax

gh_mesh.instancing_set_color( mesh_id, index, r, g, b, a )

Languages

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

This function has no return value(s).

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

Description

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

Syntax

gh_mesh.instancing_set_orientation( mesh_id, index, pitch, yaw, roll )

Languages

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

This function has no return value(s).

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

Description

Sets the orientation of a particular instance with a quaternion.

Syntax

gh_mesh.instancing_set_orientation_v2( mesh_id, index, x, y, z, w )

Languages

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

This function has no return value(s).

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

Description

Sets the position of a particular instance.

Syntax

gh_mesh.instancing_set_position( mesh_id, index, x, y, z )

Languages

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

This function has no return value(s).

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

Description

Sets the position of a particular instance.

Syntax

gh_mesh.instancing_set_position_v2( mesh_id, index, x, y, z, w )

Languages

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

This function has no return value(s).

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

Description

Sets the scaling factor of a particular instance.

Syntax

gh_mesh.instancing_set_scale( mesh_id, index, x, y, z )

Languages

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

This function has no return value(s).

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

Description

Updates the size of the mesh box (update the position of all vertices).

Syntax

gh_mesh.resize_box( width, height, depth, mesh_id )

Languages

Parameters

width, height, depth [REAL]: size of the box
mesh_id [ID]: mesh identifier

Return Values

This function has no return value(s).

Code sample


gh_mesh.resize_box(mesh_id, 10.0, 10.0, 10.0)

resize_plane

Description

Updates the width and height of a mesh plane.

Syntax

gh_mesh.resize_plane( mesh_id, width, height )

Languages

Parameters

mesh_id [ID]: mesh identifier
width, height [REAL]: size of the quad in the XY plane

Return Values

This function has no return value(s).

Code sample


gh_mesh.resize_plane(mesh_id, 20.0, 15.0)

resize_quad

Description

Updates the width and height of a mesh quad.

Syntax

gh_mesh.resize_quad( mesh_id, width, height )

Languages

Parameters

mesh_id [ID]: mesh identifier
width, height [REAL]: size of the quad in the XY plane

Return Values

This function has no return value(s).

Code sample


gh_mesh.resize_quad(mesh_id, 20.0, 15.0)

ribbon_add_point

Description

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 )

Languages

Parameters

mesh_id [ID]: mesh identifier
x, y, z, w [REAL]: position of the new point

Return Values

This function has no return value(s).

Code sample


gh_mesh.ribbon_add_point(mesh_id, x, y, z, 1.0)

ribbon_create

Description

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 )

Languages

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

Description

Sets the cross vector that tunes the orientation of the ribbon.

Syntax

gh_mesh.ribbon_set_cross_vector( mesh_id, x, y, z, w )

Languages

Parameters

mesh_id [ID]: mesh identifier
x, y, z, w [REAL]: vector coordinates

Return Values

This function has no return value(s).

Code sample


gh_mesh.ribbon_set_cross_vector(mesh_id, x, y, z)

set_face_vertex_indices

Description

Sets the vertex indices of a particular face.

Syntax

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

Languages

Parameters

mesh_id [ID]: mesh identifier
face_index [INTEGER]: index of the face
a, b, c [INTEGER]: vertex indices

Return Values

This function has no return value(s).

Code sample


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

set_vertex_color

Description

Sets the RGBA color of a particular vertex.

Syntax

gh_mesh.set_vertex_color( mesh_id, vertex_index, r, g, b, a )

Languages

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

This function has no return value(s).

Code sample


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

set_vertex_normal

Description

Sets the normal vector of a particular vertex.

Syntax

gh_mesh.set_vertex_normal( mesh_id, vertex_index, x, y, z )

Languages

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

This function has no return value(s).

Code sample


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

set_vertex_position

Description

Sets the relative position of a particular vertex.

Syntax

gh_mesh.set_vertex_position( mesh_id, vertex_index, x, y, z, w )

Languages

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

This function has no return value(s).

Code sample


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

set_vertex_tangent

Description

Sets the tangent vector of a particular vertex.

Syntax

gh_mesh.set_vertex_tangent( mesh_id, vertex_index, x, y, z, w )

Languages

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

This function has no return value(s).

Code sample


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

set_vertex_uv

Description

Sets the texcoord of a particular vertex.

Syntax

gh_mesh.set_vertex_uv( mesh_id, vertex_index, x, y, z, w, tex_unit )

Languages

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

This function has no return value(s).

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

Description

Sets the RGBA color of all vertices.

Syntax

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

Languages

Parameters

mesh_id [ID]: mesh identifier
r, g, b, a [REAL]: RGBA color of the vertex

Return Values

This function has no return value(s).

Code sample


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

voxelize

Description

Voxelizes a mesh.

Syntax

gh_mesh.voxelize( mesh_id, voxelsizex, voxelsizey, voxelsizez )

Languages

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

This function has no return value(s).

Code sample


gh_mesh.voxelize(mesh_id, 4, 4, 4)

meshlet_generate

Description

Meshletizes (generates meshlets from) a regular mesh. Useful with mesh shaders.

Syntax

ret = gh_mesh.meshlet_generate( mesh_id, max_vertices, max_indices )

Languages

Parameters

mesh_id [ID]: mesh identifier
max_vertices [INTEGER]: max vertices of a meshlet
max_indices [INTEGER]: max indices of a meshlet. 3 indices make a triangular face.

Return Values

ret [INTEGER]: 1 if ok, 0 if error.

Code sample


ret = gh_mesh.meshlet_generate(mesh_id, 64, 126)

meshlet_get_count

Description

Returns the number of meshlets of a mesh.

Syntax

n = gh_mesh.meshlet_get_count( mesh_id )

Languages

Parameters

mesh_id [ID]: mesh identifier

Return Values

n [INTEGER]: number of meshlets

Code sample


n = gh_mesh.meshlet_get_count(mesh_id)

meshlet_get_vertex_count

Description

Returns the number of vertices of a particular meshlet.

Syntax

num_meshlet_vertices = gh_mesh.meshlet_get_vertex_count( mesh_id, meshlet_index )

Languages

Parameters

mesh_id [ID]: mesh identifier
meshlet_index [INTEGER]: meshlet index (0 to num_meshlets-1)

Return Values

num_meshlet_vertices [INTEGER]: number of vertices

Code sample


num_meshlet_vertices = gh_mesh.meshlet_get_vertex_count(mesh_id)

meshlet_get_index_count

Description

Returns the number of indices of a particular meshlet.

Syntax

num_meshlet_indices = gh_mesh.meshlet_get_index_count( mesh_id, meshlet_index )

Languages

Parameters

mesh_id [ID]: mesh identifier
meshlet_index [INTEGER]: meshlet index (0 to num_meshlets-1)

Return Values

num_meshlet_indices [INTEGER]: number of indices

Code sample


num_meshlet_indices = gh_mesh.meshlet_get_index_count(mesh_id)

meshlet_get_vertex

Description

Returns a index relative to the mesh (yes mesh) vertices list. This index is usually used to fill a GPU buffer for rendering with mesh shaders

Syntax

mesh_vertex_index = gh_mesh.meshlet_get_vertex( mesh_id, meshlet_index, meshlet_vertex_index )

Languages

Parameters

mesh_id [ID]: mesh identifier
meshlet_index [INTEGER]: meshlet index (0 to num_meshlets-1)
meshlet_vertex_index [INTEGER]: vertex in the meshlet vertices list (0 to num_meshlet_vertices-1)

Return Values

mesh_vertex_index [INTEGER]: index relative to the mesh vertices list

Code sample


mesh_vertex_index = gh_mesh.meshlet_get_vertex(mesh_id, meshlet_index, meshlet_vertex_index)

meshlet_get_index

Description

Returns a index relative to the meshlet (yes meshlet) indices list. This index is usually used to fill a GPU buffer for rendering with mesh shaders.

Syntax

mesh_face_index = gh_mesh.meshlet_get_index( mesh_id, meshlet_index, meshlet_primitive_index )

Languages

Parameters

mesh_id [ID]: mesh identifier
meshlet_index [INTEGER]: meshlet index (0 to num_meshlets-1)
meshlet_primitive_index [INTEGER]: index in the meshlet indices list (0 to num_meshlet_indices-1)

Return Values

mesh_face_index [INTEGER]: index relative to the meshlet indices list

Code sample


mesh_face_index = gh_mesh.meshlet_get_index(mesh_id, meshlet_index, meshlet_primitive_index)

set_vertex_alloc_params_separate_vertex_arrays

Description

Tells GeeXLab to create the next meshes with separate vertex arrays (state=1) or with an interleaved vertex array (state=0).

Syntax

gh_mesh.set_vertex_alloc_params_separate_vertex_arrays( state )

Languages

Parameters

state [INTEGER]: 1 (separate vertex arrays) or 0 (interleaved vertex array) - Default is separate vertex arrays.

Return Values

This function has no return value(s).

Code sample


gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0)
...
mesh = gh_mesh.create_plane(128, 128, 10, 10)
...
gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(1)

vertices_to_gpu_buffer

Description

Copies the whole vertex array of a mesh to a GPU buffer. The mesh must have been created with an interleaved vertex array. Call gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0) before creating the mesh. The GPU buffer must use a an interleaved vertex structure too.

Syntax

gh_mesh.vertices_to_gpu_buffer( mesh_id, gpu_buffer_id, gpu_buffer_offset )

Languages

Parameters

mesh_id [ID]: mesh identifier
gpu_buffer_id [ID]: gpu buffer identifier
gpu_buffer_offset [INTEGER]: offset in the gpu buffer in bytes

Return Values

This function has no return value(s).

Code sample


gh_mesh.vertices_to_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset)

vertices_from_gpu_buffer

Description

Copies the vertex array from a GPU buffer to the mesh. The mesh must have been created with an interleaved vertex array. Call gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0) before creating the mesh. The GPU buffer must use a an interleaved vertex structure too.

Syntax

gh_mesh.vertices_from_gpu_buffer( mesh_id, gpu_buffer_id, gpu_buffer_offset, size, update_cpu, update_gpu )

Languages

Parameters

mesh_id [ID]: mesh identifier
gpu_buffer_id [ID]: gpu buffer identifier
gpu_buffer_offset [INTEGER]: offset in the gpu buffer in bytes
size [INTEGER]: size of the copy in bytes
update_cpu [BOOLEAN]: update the mesh vertex array in CPU memory: 1 (YES) or 0 (NO)
update_gpu [BOOLEAN]: update the mesh vertex array in GPU memory: 1 (YES) or 0 (NO)

Return Values

This function has no return value(s).

Code sample


gh_mesh.vertices_from_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset, size, update_cpu, update_gpu)

vertices_position_to_gpu_buffer

Description

Copies the position of all vertices to a GPU buffer. The mesh can have an interleaved vertex array or separate vertex arrays.

Syntax

gh_mesh.vertices_position_to_gpu_buffer( mesh_id, gpu_buffer_id, gpu_buffer_offset, gpu_buffer_stride )

Languages

Parameters

mesh_id [ID]: mesh identifier
gpu_buffer_id [ID]: gpu buffer identifier
gpu_buffer_offset [INTEGER]: offset in the gpu buffer in bytes
gpu_buffer_stride [INTEGER]: stride value: size in bytes between to consecutive positions in the gpu buffer

Return Values

This function has no return value(s).

Code sample


gpu_buffer_stride = 16   # 16 bytes = size of a vec4. 			
gpu_buffer_offset = 0
gh_mesh.vertices_position_to_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset, gpu_buffer_stride)

vertices_position_from_gpu_buffer

Description

Updates the position attribute of the mesh from a GPU buffer. The mesh can have an interleaved vertex array or separate vertex arrays.

Syntax

gh_mesh.vertices_position_from_gpu_buffer( mesh_id, gpu_buffer_id, gpu_buffer_offset, gpu_buffer_stride, size, update_cpu, update_gpu )

Languages

Parameters

mesh_id [ID]: mesh identifier
gpu_buffer_id [ID]: gpu buffer identifier
gpu_buffer_offset [INTEGER]: offset in the gpu buffer in bytes
gpu_buffer_stride [INTEGER]: stride value: size in bytes between to consecutive positions in the gpu buffer
size [INTEGER]: size of the copy in bytes
update_cpu [BOOLEAN]: update the mesh vertex array in CPU memory: 1 (YES) or 0 (NO)
update_gpu [BOOLEAN]: update the mesh vertex array in GPU memory: 1 (YES) or 0 (NO)

Return Values

This function has no return value(s).

Code sample


gpu_buffer_stride = 16   # 16 bytes = size of a vec4. 			
gpu_buffer_offset = 0
gh_mesh.vertices_position_from_gpu_buffer(mesh_id, gpu_buffer_id, gpu_buffer_offset, gpu_buffer_stride, size, update_cpu, update_gpu)

set_vertex_source

Description

Sets a GPU buffer as the source of vertices for a mesh. The mesh must have been created with an interleaved vertex array. Call gh_mesh.set_vertex_alloc_params_separate_vertex_arrays(0) before creating the mesh. The GPU buffer must use a an interleaved vertex structure too.

Syntax

gh_mesh.set_vertex_source( mesh_id, gpu_buffer_id )

Languages

Parameters

mesh_id [ID]: mesh identifier
gpu_buffer_id [ID]: gpu buffer identifier

Return Values

This function has no return value(s).

Code sample


gh_mesh.set_vertex_source(mesh_id, gpu_buffer_id)

GeeXLab Rootard Guide | Downloads | Contact