Geometry

Functions
C_INTERFACE	LoadOBJ (const char *obj_path, HF::Geometry::GROUP_METHOD gm, float xrot, float yrot, float zrot, HF::Geometry::MeshInfo< float > ***out_data_array, int *num_meshes)
	Load an obj from the given path then rotate it by x,y, and z. More...
C_INTERFACE	StoreMesh (HF::Geometry::MeshInfo< float > **out_info, const int *indices, int num_indices, const float *vertices, int num_vertices, const char *name, int id)
	Store a mesh in a format usable with DHARTAPI. More...
C_INTERFACE	RotateMesh (HF::Geometry::MeshInfo< float > *mesh_to_rotate, float xrot, float yrot, float zrot)
	Rotate an existing mesh (HF::Geometry::MeshInfo) More...
C_INTERFACE	GetVertsAndTris (const HF::Geometry::MeshInfo< float > *MI, int **index_out, int *num_triangles, float **vertex_out, int *num_vertices)
	Get a pointer to and the size of a mesh's triangle and vertex arrays. More...
C_INTERFACE	GetMeshName (const HF::Geometry::MeshInfo< float > *MI, char **out_name)
	Get the name of a mesh. More...
C_INTERFACE	GetMeshID (const HF::Geometry::MeshInfo< float > *MI, int *out_id)
	Get the ID of a mesh. More...
C_INTERFACE	DestroyMeshInfo (HF::Geometry::MeshInfo< float > *mesh_to_destroy)
	Free the memory addressed by mesh_to_destroy, which was allocated by either LoadOBJ or StoreMesh. More...
C_INTERFACE	DestroyMeshInfoPtrArray (HF::Geometry::MeshInfo< float > **data_array)

Detailed Description

Read and manipulate meshes

Mesh setup

First, we prepare the relative path to the mesh. (.obj file)

// Status code variable, value returned by C Interface functions
// See documentation for HF::Exceptions::HF_STATUS for error code definitions.
int status = 0;
// Get model path
// This is a relative path to your obj file.
const std::string obj_path_str = "plane.obj";
 
// Size of obj file string (character count)
const int obj_length = static_cast<int>(obj_path_str.size());

Then, we prepare a pointer to a vector<HF::Geometry::MeshInfo>.

// This will point to memory on free store.
// The memory will be allocated inside the LoadOBJ function,
// and it must be freed using DestroyMeshInfo.
std::vector<HF::Geometry::MeshInfo>* loaded_obj = nullptr;

We pass the address of this pointer to LoadOBJ .

// Load mesh
// The array rot will rotate the mesh 90 degrees with respect to the x-axis,
// i.e. makes the mesh 'z-up'.
//
// Notice that we pass the address of the loaded_obj pointer
// to LoadOBJ. We do not want to pass loaded_obj by value, but by address --
// so that we can dereference it and assign it to the address of (pointer to)
// the free store memory allocated within LoadOBJ.
const float rot[] = { 90.0f, 0.0f, 0.0f };  // Y up to Z up
status = LoadOBJ(obj_path_str.c_str(), obj_length, rot[0], rot[1], rot[2], &loaded_obj);
 
if (status != 1) {
    // All C Interface functions return a status code.
    // Error!
    std::cerr << "Error at LoadOBJ, code: " << status << std::endl;
}
 
//
// loaded_obj contains the mesh.
//

loaded_obj points to the loaded mesh.

Mesh teardown

When you are finished with the mesh, you must then relinquish its memory resources:

// destroy vector<MeshInfo>
status = DestroyMeshInfo(loaded_obj);
 
if (status != 1) {
    std::cerr << "Error at DestroyMeshInfo, code: " << status << std::endl;
}

>>> LoadOBJ loaded mesh successfully into loaded_obj at address 000001DBFADFAF50, code: 1

The client is responsible for releasing the memory for
the mesh (vector<HF::Geometry::MeshInfo> *).
Every example for each function should be followed up by the 'teardown' code described above.

Notes on MeshInfo::PerformRotation

LoadOBJ and RotateMesh both call
HF::Geometry::MeshInfo::PerformRotation, which contains the following:

        // Assert that we didn't create any NANS or infinite values
        assert(rotation_matrix.allFinite());
 
        // Apply the rotation matrix to verts
        verts = (rotation_matrix * verts);
 
        // Once again assert that we didn't create any nans or infinite numbers.
        assert(verts.allFinite());

rotation_matrix is a local variable in PerformRotation,
and verts is a private field within HF::Geometry::MeshInfo.

These assertion statements may evaluate false (which will halt execution)
if NANs (not-a-number) or infinity values were created
from the xrot, yrot, or zrot values passed to LoadOBJ or RotateMesh.

Function Documentation

DestroyMeshInfo()

C_INTERFACE DestroyMeshInfo

(

HF::Geometry::MeshInfo< float > *

mesh_to_destroy

)

#include <Cinterface/objloader_C.h>

Free the memory addressed by mesh_to_destroy, which was allocated by either LoadOBJ or StoreMesh.

Parameters

mesh_to_destroy

The HF::Geometry::MeshInfo * whose memory will be released

Returns

HF_STATUS::OK

See also

Mesh setup (how to create a mesh), Mesh teardown (how to destroy a mesh)

Definition at line 126 of file objloader_C.cpp.

References DeleteRawPtr(), and HF::Exceptions::OK.

Here is the call graph for this function:

DestroyMeshInfoPtrArray()

C_INTERFACE DestroyMeshInfoPtrArray

(

HF::Geometry::MeshInfo< float > **

data_array

)

#include <Cinterface/objloader_C.h>

Definition at line 132 of file objloader_C.cpp.

References HF::Exceptions::OK.

GetMeshID()

C_INTERFACE GetMeshID	(	const HF::Geometry::MeshInfo< float > *	MI,
		int *	out_id
	)

#include <Cinterface/objloader_C.h>

Get the ID of a mesh.

Parameters

MI	Instance of MeshInfo to get the name of
out_name	Pointer to the integer to write output to. This must be a valid pointer

Returns

HF_STATUS::OK

Definition at line 119 of file objloader_C.cpp.

References HF::Geometry::MeshInfo< numeric_type >::meshid.

Referenced by LoadOBJ().

Here is the caller graph for this function:

GetMeshName()

C_INTERFACE GetMeshName	(	const HF::Geometry::MeshInfo< float > *	MI,
		char **	out_name
	)

#include <Cinterface/objloader_C.h>

Get the name of a mesh.

Parameters

MI	Instance of MeshInfo to get the name of
out_name	Pointer to the char array to write output to. This must be a valid pointer

Returns

HF_STATUS::OK

Definition at line 108 of file objloader_C.cpp.

References HF::Geometry::MeshInfo< numeric_type >::name.

GetVertsAndTris()

C_INTERFACE GetVertsAndTris	(	const HF::Geometry::MeshInfo< float > *	MI,
		int **	index_out,
		int *	num_triangles,
		float **	vertex_out,
		int *	num_vertices
	)

#include <Cinterface/objloader_C.h>

Get a pointer to and the size of a mesh's triangle and vertex arrays.

Parameters

index_out	Output parameter for a pointer to the mesh's vertex array
num_triangles	Number of triangles in the index array. Every 3 indices is a new triangle, so this is equal to the length of index_out divided by 3.
vertex_out	Output parameter for a pointer to the mesh's index array.
num_vertices	Number of vertices in the vertex array. Every 3 floats is a new vertex, so this is equal to the length of vertex_out divided by 3.

Returns

HF_STATUS::OK

Definition at line 94 of file objloader_C.cpp.

References HF::Geometry::MeshInfo< numeric_type >::GetIndexPointer(), and HF::Geometry::MeshInfo< numeric_type >::GetVertexPointer().

Here is the call graph for this function:

LoadOBJ()

C_INTERFACE LoadOBJ	(	const char *	obj_path,
		HF::Geometry::GROUP_METHOD	gm,
		float	xrot,
		float	yrot,
		float	zrot,
		HF::Geometry::MeshInfo< float > ***	out_data_array,
		int *	num_meshes
	)

#include <Cinterface/objloader_C.h>

Load an obj from the given path then rotate it by x,y, and z.

Parameters

obj_path	Filepath to the obj file to load.
gm	Method to use for dividing a single obj file into multiple meshes.
xrot	Degrees to rotate the mesh on the x axis.
yrot	Degrees to rotate the mesh on the y axis.
zrot	Degrees to rotate the mesh on the z axis.
out_data_array	Output parameter for the new array of meshinfo
num_meshes	Output parameter for size of out_data_array

Returns

HF_STATUS::OK If the input was a valid mesh and the function completed successfully

HF_STATUS::GENERIC_ERROR If the input was empty.

HF_STATUS::INVALID_OBJ if the path didn't lead to a valid OBJ file

HF_STATUS::NOT_FOUND if the file at the given path couldn't be found.

Attention

Call DestroyMeshInfoPtrArray to deallocate out_data_array, and call DestroyMeshInfo on each instance of MeshInfo to deallocate them individually. Failure to do any of this will result in memory leaks. In the case that HF_STATUS::OK is not called, no memory is allocated, and as such no memory must be deallocated.

See also

Mesh setup (how to create a mesh), Notes on MeshInfo::PerformRotation (assertion statement)

Definition at line 13 of file objloader_C.cpp.

References GetMeshID(), and HF::Geometry::LoadMeshObjects().

Here is the call graph for this function:

RotateMesh()

C_INTERFACE RotateMesh	(	HF::Geometry::MeshInfo< float > *	mesh_to_rotate,
		float	xrot,
		float	yrot,
		float	zrot
	)

#include <Cinterface/objloader_C.h>

Rotate an existing mesh (HF::Geometry::MeshInfo)

Parameters

mesh_to_rotate	An operand vector<HF::Geometry::MeshInfo> * that addresses memory allocated by LoadOBJ or StoreMesh
xrot	Degrees to rotate the mesh about the x axis. 0.0f would mean no rotation about the x axis.
yrot	Degrees to rotate the mesh about the y axis. 0.0f would mean no rotation about the y axis.
zrot	Degrees to rotate the mesh about the z axis. 0.0f would mean no rotation about the z axis.

Returns

HF_STATUS::OK on return

See also

Mesh setup (how to create a mesh), StoreMesh (creating a mesh from arrays), Mesh teardown (how to destroy a mesh), Notes on MeshInfo::PerformRotation (assertion statement)

        // Prepare the desired rotation values.
        // A value of 0.0f means no rotation about the given axis.
        const float x_rot = 90.0f;
        const float y_rot = 0.0f;
        const float z_rot = 0.0f;
 
        // Rotate the mesh. Here, we are rotating the mesh so that it is 'z-up'.
        status = RotateMesh(info, x_rot, y_rot, z_rot);
 
        if (status != 1) {
            std::cerr << "Error at RotateMesh, code: " << status << std::endl;
        }

Definition at line 84 of file objloader_C.cpp.

References HF::Geometry::MeshInfo< numeric_type >::meshid, and HF::Geometry::MeshInfo< numeric_type >::PerformRotation().

Here is the call graph for this function:

StoreMesh()

C_INTERFACE StoreMesh	(	HF::Geometry::MeshInfo< float > **	out_info,
		const int *	indices,
		int	num_indices,
		const float *	vertices,
		int	num_vertices,
		const char *	name,
		int	id
	)

#include <Cinterface/objloader_C.h>

Store a mesh in a format usable with DHARTAPI.

Parameters

out_info	Output parameter to contain the new instance of meshinfo
indices	An array of indices for the triangles within the mesh. Each member in this array is an integer that corresponds to a set of 3 vertex coordinates, { x, y, z }. indices[0] represents { vertices[0], vertices[1], vertices[2] } indices[1] represents { vertices[3], vertices[4], vertices[5] }, etc. Every 3 array members in indices represents a complete triangle for the mesh.
num_indices	Member count (size) of the indices array. This value should be (size of vertices / 3) && (num_indices % 3 == 0)
vertices	An array of vertex coordinates, which represents the location of a mesh. Starting at i = 0, { vertices[i], vertices[i + 1], vertices[i + 2] } represents a point in space.
num_vertices	Member count (size) of the vertices array. This value should be (size of indices * 3) && (num_vertices % 3 == 0)
name	The desired name for the mesh (a human-readable identifier)
id	The desired ID for the mesh (an integral value)

Returns

HF_STATUS::OK, if the mesh was loaded successfully HF_STATUS::INVALID_OBJ if the values in indices and/or vertices did not create a valid mesh

See also

Mesh teardown (how to destroy a mesh)

First, we must prepare the values for the mesh to store.

        // Status code variable, value returned by C Interface functions
        // See documentation for HF::Exceptions::HF_STATUS for error code definitions.
        int status = 0;
 
        //
        // Prepare the mesh parameters
        //
 
        // Each member in this array represents a set of 3 vertex coordinates, { x, y, z }.
        // mesh_indices should begin at 0, be monotonically increasing,
        // and size of mesh_indices % 3 == 0, that is to say --
        // the member count of mesh_indices should be a multiple of 3.
        // Every three members in mesh_indices constitutes a complete triangle for the mesh.
        const std::array<int, 3> mesh_indices { 0, 1, 2 };  // v_0, v_1, v_2
        const int size_indices = static_cast<int>(mesh_indices.size());
 
        // This is an array of vertex coordinates. 
        // Every three members in mesh_vertices constitutes a vertex.
        // Every nine members constitutes a complete triangle for the mesh.
        // Size of mesh_vertices % 3 == 0, that is to say --
        // the member count of mesh_vertices should be a multiple of 3.
        const std::array<float, 9> mesh_vertices { 34.1f, 63.9f, 16.5f, 23.5f, 85.7f, 45.2f, 12.0f, 24.6f, 99.4f };
                                              // {  v_0x,  v_0y,  v_0z,  v_1x,  v_1y,  v_1z,  v_2x,  v_2y,  v_2z };
        const int size_vertices = static_cast<int>(mesh_vertices.size());
 
        // Give the mesh a name, and an ID.
        const auto mesh_name = "This mesh";
        const int mesh_id = 0;

We are now ready to call StoreMesh.

        // This will point to memory on free store.
        // The memory will be allocated inside the StoreMesh function,
        // and it must be freed using DestroyMeshInfo.
        std::vector<HF::Geometry::MeshInfo>* info = nullptr;
 
        // Call StoreMesh
        // If the values in mesh_indices and/or mesh_vertices did not create a valid mesh,
        // or the values size_indices and/or size_vertices are not in alignment with the arrays they represent
        // (or not multiples of 3) -- an error will occur.
        status = StoreMesh(&info, mesh_indices.data(), size_indices, mesh_vertices.data(), size_vertices, mesh_name, mesh_id);
 
        if (status != 1) {
            std::cerr << "Error at StoreMesh, code: " << status << std::endl;
        }
        
        //
        // Verify that the mesh, at info (vector<MeshInfo> *),
        // was stored properly by StoreMesh.
        //
        if (info == nullptr) {
            std::cerr << "Mesh was not stored properly." << std::endl;
        }
        else {
            std::cout << "The mesh was stored properly at address " << info << "." << std::endl;
        }

>>> The mesh was stored properly at address 0000029C6317BEB0.

Definition at line 59 of file objloader_C.cpp.

References HF::Exceptions::INVALID_OBJ, and HF::Exceptions::OK.