DI-Guy API Version 12.5.1

This file was automatically generated from diguyGraphicsMesh.h. Do not edit this file directly; the changes will be lost.

Contents:

• Accessor Functions
• Geometry Data Accessor Functions
  • Shader Accessor Functions
  • Vertex Buffer Data Accessor Functions
  • Index Buffer Data Accessor Functions
• Virtual Functions
• Deprecated Functions

Link against: libdiguy_graphics_api

class BDI_DECLSPEC_diguy diguyGraphicsMesh { public:     const char* get_name();     long get_uid();     diguyGraphicsState* get_state(int graphics_state_switch_index = 0);     diguyGraphicsState* get_current_graphics_state();     int get_num_switched_graphics_states();     int get_is_skinned_mesh();     int get_is_deformable();     void free_loader_memory();     diguyGraphicsShaderProgram* get_shader_program();     diguyGraphicsShaderInstance* get_shader_instance();     diguyGraphicsVertexFormat get_vertex_format();     int get_vertex_count();     int get_vertex_buffer_size(); #ifdef CPLUSPLUS_ONLY     void* get_vertex_buffer_data();     float* get_first_vertex();     int get_vertex_offset();     int get_vertex_stride();     float* get_first_normal();     int get_normal_offset();     int get_normal_stride();     float* get_first_texture_indices();     int get_texture_indices_offset();     int get_texture_indices_stride();     float* get_first_link_index();     int get_link_index_offset();     int get_link_index_stride();     float* get_first_link_weight();     int get_link_weight_offset();     int get_link_weight_stride();     float* get_first_tangent();     int get_tangent_offset();     int get_tangent_stride(); #endif     diguyGraphicsIndexType get_index_type();     int get_index_count(); #ifdef CPLUSPLUS_ONLY     int get_index_buffer_size();     void* get_index_buffer_data(); #endif #ifdef CPLUSPLUS_ONLY     virtual void build();     virtual void unbuild();     virtual void draw(); #endif #ifdef CPLUSPLUS_ONLY     int get_vertex_info(int* num_vertices,         float** vertex_array,         float** normal_array,         float** texture_array,         int* index_array_size,         unsigned short** index_array); #endif

The functions in this section provide access to data in this object. They are designed to be called by DI-Guy programmers.

Prototype:

const char* get_name();

Description:

Returns the name of the mesh. This pointer will never be NULL.

Returns:

name of the mesh

Prototype:

long get_uid();

Description:

All meshs are assigned a unique identifer (uid). This function returns the uid of the mesh.

Note: uids will change between DI-Guy runs.

Returns:

unique identifier of the object

Prototype:

diguyGraphicsState* get_state(int graphics_state_switch_index = 0);

Description:

This function returns the graphics state with which faces in this mesh should be drawn. Specific information about material and texture can then be accessed from this object.

Some meshes may have multiple possible graphics states associated with them. In effect this means that depending on a character's appearance, different textures or material settings may be used.

Call get_num_switched_graphics_states() to get the number of graphics states that are associated with this mesh.

This function is typically called during the Build stage for scene graph renderers, when geoset/mesh objects are being created and their graphics states set.

Returns:

object of type diguyGraphicsState; NULL on failure

Prototype:

diguyGraphicsState* get_current_graphics_state();

Description:

This function returns the last bound graphic state object this mesh used. There should always be at least one. This can be used by immediate mode renderers during draw calls to find out more about the properties of the mesh.

See get_state() for more information on switched graphics states.

Returns:

object of type diguyGraphicsState; NULL on failure

Prototype:

int get_num_switched_graphics_states();

Description:

This function returns the number of switched graphics states this mesh has. There should always be at least one.

See get_state() for more information on switched graphics states.

Returns:

number of switched graphics states this mesh has

Prototype:

int get_is_skinned_mesh();

Description:

This function returns whether or not the mesh is "skinned".

The position of vertices in a skinned mesh are determined at run-time by transforming them with multiple link transforms.

It is likely that some type of shader is required to render the mesh correctly. The shader recommended for this mesh can be obtained by calling get_shader_program().

Though they sound similar, skinned meshes and deformable meshes are different. The vertices in a deformable mesh have already been transformed when the draw() function is called; nothing more needs to be done. The vertices in a skinned are not ready to be drawn, as they must first be transformed by a shader.

Returns:

1 if mesh is skinned, 0 if not, -1 on failure

Prototype:

int get_is_deformable();

Description:

This function returns whether or not the mesh is deformable.

The position of vertices in a deformable mesh may shift from frame to frame and therefore should not be put into a renderer-specific object that cannot be updated. (For example, vertex buffer objects in OpenGL.)

The position of vertices in a non-deformable, non-skinned mesh remain fixed from frame to frame.

Though they sound similar, skinned meshes and deformable meshes are different. The vertices in a deformable mesh have already been transformed when the draw() function is called; nothing more needs to be done. The vertices in a skinned mesh are not ready to be drawn, as they must first be transformed by a shader.

Returns:

1 if mesh is deformable, 0 if not, -1 on failure

Prototype:

void free_loader_memory();

Description:

This function frees most memory allocated by the DI-Guy geometry loader for this object.

This function should only be called during or after the object's build() function has been called. After it has been called, calls to many accessor functions will fail.

The functions in this section provide access to geometry data of this mesh, including vertex positions, normals, texture indices, etc.

They are designed to be called by DI-Guy programmers during the Build Stage. Calling them before the Build Stage will return invalid results.

Functions that return pointers to data (get_vertex_buffer_data(), etc.) cannot be called after free_loader_memory() is called.

For in-depth examples of how these functions work, look at the following files in programming_examples/diguy_graphics_api:

• ogl_examplescommonoglGraphicsMesh.cpp
• osg_2_examplescommondiguyOsgGraphicsMesh.cpp

For more information on how the returned data is structured, refer to the documentation for the types diguyGraphicsVertexFormat and DIGUY_GRAPHICS_INDEX_TYPE_UINT.

Prototype:

diguyGraphicsShaderProgram*  get_shader_program();

Description:

This function returns a pointer to the shader program designated for this mesh, if any. Shader programs are shared objects usable by many meshes.

Returns:

pointer to diguyGraphicsShaderProgram, or NULL if this mesh does not have a shader specified

Prototype:

diguyGraphicsShaderInstance* get_shader_instance();

Description:

If this mesh has a shader program specified (see get_shader_program()), this function returns a pointer to the shader instance object specific to this mesh.

Returns:

pointer to diguyGraphicsShaderInstance, or NULL if this mesh does not have a shader specified

Prototype:

diguyGraphicsVertexFormat get_vertex_format();

Returns:

vertex format that describes the format of the data returned by the get_vertex_buffer_data() function

Prototype:

int get_vertex_count();

Returns:

how many vertices this mesh has

Prototype:

int get_vertex_buffer_size();

Returns:

size, in bytes, of the data buffer returned by get_vertex_buffer_data()

Prototype:

void* get_vertex_buffer_data();

Description:

This function returns a pointer to the raw vertex buffer data of this mesh. The format of the data can be obtained by calling get_vertex_format().

Type-correct pointers into the data can be obtained by calling get_first_vertex(), get_first_normal(), etc.

Returns:

pointer to raw vertex buffer data

Prototype:

float* get_first_vertex();

Description:

This function returns a pointer to vertex position data of the first vertex in the raw vertex buffer data returned by get_vertex_buffer_data().

The XYZ position of the first vertex is stored in the first three values of the returned pointer. The XYZ positions of subsequent vertices need to be obtained by consecutively adding the vertex stride to this returned pointer, as returned by get_vertex_stride().

NOTE: get_vertex_stride() returns a value in bytes, not sizeof(float), so be careful about pointer arithmetic.

This approach is also used for the first normal, texture indices, link index, and link weight of the vertex data.

An alternative approach to getting a pointer to the first vertex position is to use get_vertex_offset(). See that function for more information.

Returns:

pointer to vertex position of first vertex in vertex buffer data

Prototype:

int get_vertex_offset();

Description:

This function returns how many bytes the first vertex position is into the raw vertex buffer data returned by get_vertex_buffer_data().

The XYZ positions of subsequent vertices need to be obtained by consecutively adding the vertex stride to this offset, as returned by get_vertex_stride().

NOTE: get_vertex_stride() returns a value in bytes, not sizeof(float), so be careful about pointer arithmetic.

This approach is also used for the first normal, texture indices, link index, and link weight offsets into the vertex data.

An alternative approach to getting a pointer to the first vertex position is to use get_first_vertex() to get a type-correct pointer.

Returns:

offset in bytes of the first vertex position in raw vertex buffer data

Prototype:

int get_vertex_stride();

Description:

This function returns how many bytes there are between each vertex position in the raw data returned by get_vertex_buffer_data().

See get_first_vertex() and get_vertex_offset() for more information.

NOTE: this function returns a value in bytes, not sizeof(float), so be careful about pointer arithmetic.

Returns:

stride in bytes between each vertex position in raw vertex buffer data

Prototype:

float* get_first_normal();

Returns:

pointer to normal of first vertex in vertex buffer data; see get_first_vertex() for more information

Prototype:

int get_normal_offset();

Returns:

offset in bytes of the first normal in raw vertex buffer data; see get_vertex_offset() for more information

Prototype:

int get_normal_stride();

Returns:

stride in bytes between each normal in raw vertex buffer data; see get_vertex_stride() for more information

Prototype:

float* get_first_texture_indices();

Returns:

pointer to texture indices of first vertex in vertex buffer data

Prototype:

int get_texture_indices_offset();

Returns:

offset in bytes of the first texture indices in raw vertex buffer data; see get_vertex_offset() for more information

Prototype:

int get_texture_indices_stride();

Returns:

stride in bytes between each texture indices pair in raw vertex buffer data; see get_vertex_stride() for more information

Prototype:

float* get_first_link_index();

Returns:

pointer to link index of first vertex in vertex buffer data, in float form

Prototype:

int get_link_index_offset();

Returns:

offset in bytes of the first link index in raw vertex buffer data; see get_vertex_offset() for more information

Prototype:

int get_link_index_stride();

Returns:

stride in bytes between each link index in raw vertex buffer data; see get_vertex_stride() for more information

Prototype:

float* get_first_link_weight();

Returns:

pointer to link weight of first vertex in vertex buffer data

Prototype:

int get_link_weight_offset();

Returns:

offset in bytes of the first link offset in raw vertex buffer data; see get_vertex_offset() for more information

Prototype:

int get_link_weight_stride();

Returns:

stride in bytes between each link weight in raw vertex buffer data; see get_vertex_stride() for more information

Prototype:

float* get_first_tangent();

Description:

Returns a pointer to the UV tangent and flip bit of first vertex in the vertex buffer data.

There are 3 floats representing the tangent, and one for UV mirroring. See http://www.dhpoware.comdemosglslNormalMapping.html for an outline of how tangents are calculated. Binormals are calculated in the vertex shader making their storage unnecessary. Tangents should exist for all skinned/dae models.

See get_first_vertex() for more information about how to interpret tangent pointers and strides.

Prototype:

int get_tangent_offset();

Returns:

offset in bytes of the first tangent in raw vertex buffer data; see get_vertex_offset() for more information

Prototype:

int get_tangent_stride();

Returns:

stride in bytes between each tangent in raw vertex buffer data; see get_vertex_stride() for more information

Prototype:

diguyGraphicsIndexType get_index_type();

Returns:

index type used in data returned by the get_index_buffer_data() function

Prototype:

int get_index_count();

Description:

This function returns how many indices there are in this mesh. The number of triangles in this mesh can be derived by dividing this value by 3.

Note that indices in index buffer data are different than the indices contained in vertex buffer data. Index buffer indices specify which vertices in vertex buffer data are used to create polygons in a mesh (e.g., for the first triangle, use vertices 0, 1, and 2), while indices stored in vertex buffer data specify which links affect the final position of the vertex.

Returns:

number of indices in index buffer data returned by get_index_buffer_data()

Prototype:

int get_index_buffer_size();

Returns:

size, in bytes, of the data buffer returned by get_index_buffer_data()

Prototype:

void* get_index_buffer_data();

Description:

This function returns a pointer to the raw index buffer data of this mesh. The format of the data can be obtained by calling get_index_type().

Returns:

pointer to raw index buffer data

The functions in this section are all virtual functions that will be called by DI-Guy at various times during DI-Guy execution.

Because the functions are all virtual, DI-Guy programmers can create a subclass of this class and override them. Unless otherwise stated, the base class functions do not need to be called.

Prototype:

virtual void build();

Description:

This function will be called by DI-Guy when it is time for a renderer-specific mesh object to be created. All information necessary to build the mesh should be available via the Accessor Functions above when this function is called.

Immediate Mode:

Immediate mode renderers may override this function, to create an object that may be invoked by draw().

Scene Graph:

Scene graph renderers usually do override this function, to create a geometry object that gets associated with a diguyGraphicsState object obtained by calling get_state().

Callable From:

• N/A (automatically called by DI-Guy Graphics API during the Build Stage)

Prototype:

virtual void unbuild();

Description:

This function will be called by DI-Guy when it is time for a renderer-specific mesh object to be destroyed.

Immediate Mode:

Immediate mode renderers may override this function, to destroy any object that may have been created by build().

Scene Graph:

Scene graph renderers usually do override this function, to destroy any object that may have been created by build().

Callable From:

• N/A (automatically called by DI-Guy Graphics API during the Unbuild Stage)

Prototype:

virtual void draw();

Description:

This function will be called by DI-Guy when the mesh should be drawn. For scene graph renderers, most likely nothing more needs to be done by this function.

Callable From:

• N/A (automatically called by DI-Guy Graphics API during Draw Stage)

The following functions are deprecated.

As these functions may disappear in a future version of DI-Guy, it is recommended that you remove calls to these functions from your application.

Prototype:

int get_vertex_info(int* num_vertices,
    float** vertex_array,
    float** normal_array,
    float** texture_array,
    int* index_array_size,
    unsigned short** index_array);

Description:

Deprecated as of 10.0.0; use Geometry Data Accessor Functions instead. This function can't provide data for all vertex formats or index formats that DI-Guy now supports. This function assumes that vertex buffer data is in array format, and that indices in index buffer data are unsigned shorts. Data for skinned meshes can't be represented with this function.

Alphabetical Index

• build (diguyGraphicsMesh)
• diguyGraphicsMesh
• draw (diguyGraphicsMesh)
• free_loader_memory (diguyGraphicsMesh)
• get_current_graphics_state (diguyGraphicsMesh)
• get_first_link_index (diguyGraphicsMesh)
• get_first_link_weight (diguyGraphicsMesh)
• get_first_normal (diguyGraphicsMesh)
• get_first_tangent (diguyGraphicsMesh)
• get_first_texture_indices (diguyGraphicsMesh)
• get_first_vertex (diguyGraphicsMesh)
• get_index_buffer_data (diguyGraphicsMesh)
• get_index_buffer_size (diguyGraphicsMesh)
• get_index_count (diguyGraphicsMesh)
• get_index_type (diguyGraphicsMesh)
• get_is_deformable (diguyGraphicsMesh)
• get_is_skinned_mesh (diguyGraphicsMesh)
• get_link_index_offset (diguyGraphicsMesh)
• get_link_index_stride (diguyGraphicsMesh)
• get_link_weight_offset (diguyGraphicsMesh)
• get_link_weight_stride (diguyGraphicsMesh)
• get_name (diguyGraphicsMesh)
• get_normal_offset (diguyGraphicsMesh)
• get_normal_stride (diguyGraphicsMesh)
• get_num_switched_graphics_states (diguyGraphicsMesh)
• get_shader_instance (diguyGraphicsMesh)
• get_shader_program (diguyGraphicsMesh)
• get_state (diguyGraphicsMesh)
• get_tangent_offset (diguyGraphicsMesh)
• get_tangent_stride (diguyGraphicsMesh)
• get_texture_indices_offset (diguyGraphicsMesh)
• get_texture_indices_stride (diguyGraphicsMesh)
• get_uid (diguyGraphicsMesh)
• get_vertex_buffer_data (diguyGraphicsMesh)
• get_vertex_buffer_size (diguyGraphicsMesh)
• get_vertex_count (diguyGraphicsMesh)
• get_vertex_format (diguyGraphicsMesh)
• get_vertex_info (diguyGraphicsMesh)
• get_vertex_offset (diguyGraphicsMesh)
• get_vertex_stride (diguyGraphicsMesh)
• unbuild (diguyGraphicsMesh)