< GeeXLab Reference Guide />

gh_material library

Description

gh_material is the module that manages materials: creation, destruction, parameters setting. The fundamental goal of material is to define the final appearence of an object surface. A material is made up of one or several textures and a GPU program.

Number of functions: 22

gh_material.add_texture ()
gh_material.bind ()
gh_material.create ()
gh_material.set_opacity ()
gh_material.get_opacity ()
gh_material.set_shininess ()
gh_material.get_shininess ()
gh_material.set_ambient ()
gh_material.get_ambient ()
gh_material.set_diffuse ()
gh_material.get_diffuse ()
gh_material.set_specular ()
gh_material.get_specular ()
gh_material.get_gpu_program ()
gh_material.set_gpu_program ()
gh_material.get_num_textures ()
gh_material.get_texture ()
gh_material.remove_texture ()
gh_material.vk_descriptorset_add_all_textures ()
gh_material.vk_descriptorset_add_texture ()
gh_material.vk_descriptorset_copy ()
gh_material.vk_descriptorset_update_all_textures ()

add_texture

Description

Adds a texture to the material.

Syntax

gh_material.add_texture( mat_id, tex_id )

Languages

Parameters

mat_id [ID]: material identifier
tex_id [ID]: texture identifier

Return Values

This function has no return value(s).

Code sample


gh_material.add_texture(mat_id, tex_id)

bind

Description

Bind the material to the renderer: textures and GPU programs are bound.

Syntax

gh_material.bind( mat_id )

Languages

Parameters

mat_id [ID]: material identifier

Return Values

This function has no return value(s).

Code sample


gh_material.bind(mat_id)

create

Description

Creates a material.

Syntax

mat_id = gh_material.create()

Languages

Parameters

This function has no input parameter(s).

Return Values

mat_id [ID]: material identifier

Code sample


mat_id = gh_material.create()

set_opacity

Description

Set the opacity of the material.

Syntax

gh_material.set_opacity( mat_name, opacity )

Languages

Parameters

mat_name [ID]: material identifier
opacity [REAL]: opacity value (range: 0.0 - 1.0)

Return Values

This function has no return value(s).

Code sample


gh_material.set_opacity(mat_id, opacity)

get_opacity

Description

Get the opacity of the material.

Syntax

opacity = gh_material.get_opacity( mat_name )

Languages

Parameters

mat_name [ID]: material identifier

Return Values

opacity [REAL]: opacity value (range: 0.0 - 1.0)

Code sample


opacity = gh_material.get_opacity(mat_id)

set_shininess

Description

Set the shininess of the material.

Syntax

gh_material.set_shininess( mat_name, shininess )

Languages

Parameters

mat_name [ID]: material identifier
shininess [REAL]: shininess value

Return Values

This function has no return value(s).

Code sample


shininess = 24.0			
gh_material.set_shininess(mat_id, shininess)

get_shininess

Description

Get the shininess of the material.

Syntax

shininess = gh_material.get_shininess( mat_name )

Languages

Parameters

mat_name [ID]: material identifier

Return Values

shininess [REAL]: shininess value

Code sample


shininess = gh_material.get_shininess(mat_id)

set_ambient

Description

Set the ambiant reflection factor of the material.

Syntax

gh_material.set_ambient( mat_name, r, g, b, a )

Languages

Parameters

mat_name [ID]: material identifier
r, g, b, a [REAL]: RGBA value

Return Values

This function has no return value(s).

Code sample


gh_material.set_ambient(mat_id, r, g, b, a)

get_ambient

Description

Get the ambiant reflection factor of the material.

Syntax

r, g, b, a = gh_material.get_ambient( mat_name )

Languages

Parameters

mat_name [ID]: material identifier

Return Values

r, g, b, a [REAL]: RGBA value

Code sample


r, g, b, a = gh_material.get_ambient(mat_id)

set_diffuse

Description

Set the diffuse reflection factor of the material.

Syntax

gh_material.set_diffuse( mat_name, r, g, b, a )

Languages

Parameters

mat_name [ID]: material identifier
r, g, b, a [REAL]: RGBA value

Return Values

This function has no return value(s).

Code sample


gh_material.set_diffuse(mat_id, r, g, b, a)

get_diffuse

Description

Get the diffuse reflection factor of the material.

Syntax

r, g, b, a = gh_material.get_diffuse( mat_name )

Languages

Parameters

mat_name [ID]: material identifier

Return Values

r, g, b, a [REAL]: RGBA value

Code sample


r, g, b, a = gh_material.get_diffuse(mat_id)

set_specular

Description

Set the specular reflection factor of the material.

Syntax

gh_material.set_specular( mat_name, r, g, b, a )

Languages

Parameters

mat_name [ID]: material identifier
r, g, b, a [REAL]: RGBA value

Return Values

This function has no return value(s).

Code sample


gh_material.set_specular(mat_id, r, g, b, a)

get_specular

Description

Get the specular reflection factor of the material.

Syntax

r, g, b, a = gh_material.get_specular( mat_name )

Languages

Parameters

mat_name [ID]: material identifier

Return Values

r, g, b, a [REAL]: RGBA value

Code sample


r, g, b, a = gh_material.get_specular(mat_id)

get_gpu_program

Description

Gets the GPU program of the material.

Syntax

gpuprog_id = gh_material.get_gpu_program( mat_id )

Languages

Parameters

mat_id [ID]: material identifier

Return Values

gpuprog_id [ID]: gpu program identifier

Code sample


gpuprog_id = gh_material.get_gpu_program(mat_id)

set_gpu_program

Description

Sets the GPU program of the material.

Syntax

gh_material.set_gpu_program( mat_id, gpuprog_id )

Languages

Parameters

mat_id [ID]: material identifier
gpuprog_id [ID]: gpu program identifier

Return Values

This function has no return value(s).

Code sample


gh_material.set_gpu_program(mat_id, gpuprog_id)

get_num_textures

Description

Gets the number of textures of the material.

Syntax

n = gh_material.get_num_textures( mat_id )

Languages

Parameters

mat_id [ID]: material identifier

Return Values

n [INTEGER]: number of textures

Code sample


n = gh_material.get_num_textures(mat_id)

get_texture

Description

Gets a particular texture of the material.

Syntax

tid = gh_material.get_texture( mat_id, texture_index )

Languages

Parameters

mat_id [ID]: material identifier
texture_index [INTEGER]: texture index from 0 to get_num_textures()-1

Return Values

tid [ID]: texture identifier

Code sample


n = gh_material.get_num_textures(mat_id)
for i=0, n-1 do
	tid = gh_material.get_texture(mat_id, i)
	DoSomething(tid)
end

remove_texture

Description

Removes a texture from the material.

Syntax

gh_material.remove_texture( mat_id, tex_id )

Languages

Parameters

mat_id [ID]: material identifier
tex_id [ID]: texture identifier

Return Values

This function has no return value(s).

Code sample


gh_material.remove_texture(mat_id, tex_id)

vk_descriptorset_add_all_textures

Description

Vulkan only - Adds all textures of a material to a vulkan descriptor set.

Syntax

gh_material.vk_descriptorset_add_all_textures( mat_id, descriptorset_id, binding_point_start, shader_stages, sampler_id )

Languages

Parameters

mat_id [ID]: material identifier
descriptorset_id [ID]: descriptor set identifier
binding_point_start [INTEGER]: binding point start
shader_stages [INTEGER]: shader stages: SHADER_STAGE_VERTEX, SHADER_STAGE_FRAGMENT, ... All shader stages values are in the vk.lua file
sampler_id [ID]: texture sampler identifier

Return Values

This function has no return value(s).

Code sample


binding_point_start = 1			
shader_stages = SHADER_STAGE_FRAGMENT
gh_material.vk_descriptorset_add_all_textures(mat_id, descriptorset_id, binding_point_start, shader_stages, sampler)

vk_descriptorset_add_texture

Description

Vulkan only - Adds a texture of a material to a vulkan descriptor set.

Syntax

resource_index = gh_material.vk_descriptorset_add_texture( mat_id, descriptorset_id, texture_index, binding_point, shader_stages, sampler_id )

Languages

Parameters

mat_id [ID]: material identifier
descriptorset_id [ID]: descriptor set identifier
texture_index [INTEGER]: texture index: from 0 to get_num_textures()-1
binding_point [INTEGER]: binding point
shader_stages [INTEGER]: shader stages: SHADER_STAGE_VERTEX, SHADER_STAGE_FRAGMENT, ... All shader stages values are in the vk.lua file
sampler_id [ID]: texture sampler identifier

Return Values

resource_index [INTEGER]: resource index in the descriptor set. This index can be used with gh_vk.descriptorset_update_resource_texture().

Code sample


binding_point = 1			
texture_index = 0
shader_stages = SHADER_STAGE_FRAGMENT
resource_index = gh_material.vk_descriptorset_add_texture(mat_id, descriptorset_id, texture_index, binding_point, shader_stages, sampler)

binding_point = 2			
texture_index = 1
shader_stages = SHADER_STAGE_FRAGMENT
resource_index = gh_material.vk_descriptorset_add_texture(mat_id, descriptorset_id, texture_index, binding_point, shader_stages, sampler)

vk_descriptorset_copy

Description

Vulkan only - copies the information of a vulkan descriptor set from a source material to a destination material. This function does not update the Vulkan descriptor set referenced by the source material. This function is useful if you have several materials with same texture layout (same number and type of textures) that have to share the same descriptor set.

Syntax

gh_material.vk_descriptorset_copy( material_src_id, material_dst_id )

Languages

Parameters

material_src_id [ID]: source material identifier
material_dst_id [ID]: destination material identifier

Return Values

This function has no return value(s).

Code sample


gh_material.vk_descriptorset_copy(material_src_id, material_dst_id)

vk_descriptorset_update_all_textures

Description

Vulkan only - updates a vulkan descriptor set with the textures of a material. This function is automatically called when a model is rendered.

Syntax

gh_material.vk_descriptorset_update_all_textures( material_id )

Languages

Parameters

material_id [ID]: material identifier

Return Values

This function has no return value(s).

Code sample


gh_material.vk_descriptorset_update_all_textures(material_id)

GeeXLab Rootard Guide | Downloads | Contact