4. Mesh Viewer 

Introduction 

This tutorial will take you through the process of utilizing HOOPS Exchange’s enhanced API to achieve a basic CAD model viewing experience.

This guide will walk you through the necessary steps to retrieve mesh coordinates and topology, empowering you to establish a solid foundation for rendering and navigating CAD models within your applications. By the end of the tutorial, you’ll confidently present CAD models with precision, setting the stage for exploring advanced functionalities.

Code Overview 

The code we will be writing in this document first loads a model file using A3DAsmModelFileLoadFromFile(). Once loaded, we traverse the model file from the root to the representation item where we use A3DRiComputeMesh() to obtain a mesh from each of them. This function returns an A3DMeshData that we will use to build OpenGL Buffer Objects. For the sake of simplicity, this tutorial will focus on vertex coordinates and normals only.

The rest of the code uses OpenGL and GLFW to provide a window and display the geometry on screen.

Prerequisites 

Before you start, ensure you have:

Installed HOOPS Exchange 2023 SP2 U1 or later.
The development environment matching your platform.
A clear knowledge of using the OpenGL API.

Preparing the Environment 

Before we start coding, we need to prepare the project environment.

First, create a folder called basic_viewer. This folder will contain your project configuration, your code, and the dependencies it uses.

Adding Dependencies

While HOOPS Exchange serves as our tool for loading and manipulating tessellation data, the task of displaying it in a 3D scene is left to the renowned OpenGL API. Consequently, our project will require a few essential dependencies:

GLFW

GLFW is a multi-platform library that we will use for creating our window and communicating with the OpenGL API. In this tutorial, we will be taking GLFW directly from the sources, but GLFW is provided in many ways. Click here to download GLFW 3.3.8. Once the package is downloaded, extract it and move its contents to the root of your folder basic_viewer.

Glad

Since we will be using OpenGL 4.2 for this tutorial, we want to ensure your environment has access to all OpenGL functions for this version. As such, we will be using the Glad loader which conveniently fits well with the GLFW ecosystem. Go to this page and click on the Generate button (don’t edit the form). On the next page, download glad.zip. Once the package is downloaded, extract and place all the files at the root of your project.

linmath.h

linmath.h is a single header-only dependency that we will use for basic math operations. Go to the project page, and download the file linmath.h. Place the file at the root of your project.

Base Source Code

We will start with a simple code that initializes HOOPS Exchange. At the root of your project, create a file called main.cpp and fill it with the following code:

#include <cassert>
#include <cstdio>
#include <cstdlib>

#define INITIALIZE_A3D_API
#include <A3DSDKIncludes.h>

int main(int argc, char* argv[])
{
    A3DBool loaded = A3DSDKLoadLibraryA("/path/to/exchange");
    assert(loaded);

    A3DStatus result = A3DLicPutUnifiedLicense(HOOPS_LICENSE);
    assert(result == A3D_SUCCESS);

    result = A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MINORVERSION);
    assert(result == A3D_SUCCESS);

    printf("HOOPS Exchange is ready!\n");

    A3DDllTerminate();

    // Unload the library
    A3DSDKUnloadLibrary();

    return EXIT_SUCCESS;
}

For more details on how to initialize HOOPS Exchange, see Initializing HOOPS Exchange.

Configuring CMake

At the root of your project, create a file called CMakeLists.txt and fill it with the following code:

cmake_minimum_required(VERSION 3.18)
project(MeshViewer C)

set(GLFW_BUILD_EXAMPLES OFF)
set(GLFW_BUILD_TESTS OFF)
set(GLFW_BUILD_DOCS OFF)
add_subdirectory(glfw-3.3.8)

set(EXCHANGE_PACKAGE_PATH "" CACHE PATH "Path to Exchange")
if(NOT EXCHANGE_PACKAGE_PATH)
    message(FATAL_ERROR "EXCHANGE_PACKAGE_PATH must be set to a valid folder path.")
endif()

add_executable(MeshViewer main.cpp glad.c)
target_include_directories(MeshViewer PRIVATE
    "${EXCHANGE_PACKAGE_PATH}/include"
    "${CMAKE_CURRENT_SOURCE_DIR}"
)
target_link_libraries(MeshViewer PRIVATE glfw)

This CMake file is similar to the one provided in Setting Up a CMake Project with the addition of the above-mentioned libraries.

Check Your Environment

At the end of this configuration, your folder should look like this:

basic_viewer/
├── glfw-3.3.8
│   ├── include
│   ├── src
│   ├── CMakeLists.txt
│   └── ...
├── CMakeLists.txt
├── glad.c
├── glad.h
├── khrplatform.h
├── linmath.h
└── main.cpp

Go to Compile and Run the Project to test your environment. At this point of the tutorial, running your executable should display “HOOPS Exchange is ready!” in your standard output.

Load the Model File 

First, we will create a function that loads a model file passed in parameter and return the result. In case of error, the model file is not created and the function returns a null handle:

A3DAsmModelFile* load_model_file(const char* path)
{
    A3DAsmModelFile*    model_file                           = 0;
    A3DRWParamsLoadData load_params;
    A3D_INITIALIZE_DATA(A3DRWParamsLoadData, load_params);
    load_params.m_sGeneral.m_bReadSolids                     = A3D_TRUE;
    load_params.m_sAssembly.m_bUseRootDirectory              = A3D_TRUE;
    load_params.m_sAssembly.m_bRootDirRecursive              = A3D_TRUE;
    load_params.m_sGeneral.m_eReadGeomTessMode               = kA3DReadGeomAndTess;
    load_params.m_sTessellation.m_eTessellationLevelOfDetail = kA3DTessLODHigh;
    load_params.m_sGeneral.m_bReadSurfaces                   = A3D_TRUE;
    load_params.m_sMultiEntries.m_bLoadDefault               = A3D_TRUE;

    code = A3DAsmModelFileLoadFromFile(path, &load_params, &model_file);
    if (code  != A3D_SUCCESS) {
        printf("Error %d while loading '%s'\n", code, path);
    }
    return model_file;
}

This function follows the usual loading workflow of a model file with no particularities. Note that m_sTessellation::m_eReadGeomTessMode is set to kA3DReadGeomAndTess.

This function returns the handle to the loaded model file. The function will be called from main().

Now that we have our file loaded, let’s initialize our graphics context.

Initialize the Graphics Context 

This operation has been delegated to OpenGL and GLFW. For the latter, we define glfw_prepare(). This function creates a new window, specifies a few callback functions, and initializes the OpenGL context. It also returns the handle to our windows, which we will use later on.

GLFWwindow* glfw_prepare()
{
    glfwSetErrorCallback(glfw_error_callback);

    if (!glfwInit())
        exit(EXIT_FAILURE);

    glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 4);
    glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 2);
    glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);

    GLFWwindow* window = glfwCreateWindow(800, 600, "MeshViewer", NULL, NULL);
    if (!window)
    {
        glfwTerminate();
        exit(EXIT_FAILURE);
    }

    glfwSetKeyCallback(window, glfw_key_callback);

    glfwMakeContextCurrent(window);
    gladLoadGL();
    glfwSwapInterval(1);

    return window;
}

glfw_error_callback() and glfw_key_callback() must also be defined:

void glfw_error_callback(int error, const char* description)
{
    fprintf(stderr, "Error: %s\n", description);
}

void glfw_key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
{
    if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS)
        glfwSetWindowShouldClose(window, GLFW_TRUE);
}

Preparing OpenGL is mainly about compiling the shader program. In gl_prepare_program(), we write our programs and compile them. The function then stores the name of some vertex attributes for later purposes and returns the program that we will be using later on:

GLuint gl_prepare_program()
{
    glEnable(GL_DEPTH_TEST);
    glEnable(GL_CULL_FACE);
    glCullFace(GL_BACK);

    const char* vertex_shader_text =
   "#version 420 core\n"
   "layout (location = 0) in vec3 vPos;\n"
   "layout (location = 1) in vec3 vNorm;\n"
   "out vec3 FragNormal;\n"
   "uniform mat4 M;\n"
   "uniform mat4 V;\n"
   "uniform mat4 P;\n"
   "void main()\n"
   "{\n"
       "gl_Position = P * V * M * vec4(vPos, 1.0f);\n"
       "FragNormal = normalize(mat3(transpose(inverse(M))) * vNorm);\n"
   "}\n";


    const char* fragment_shader_text =
   "#version 420 core\n"
   "out vec4 FragColor;\n"
   "\n"
   "in vec3 FragNormal;\n"
     "\n"
   "void main()\n"
   "{\n"
       "vec3 normal = normalize(FragNormal);\n"
       "vec3 lightDirection = normalize(vec3(1.0, 1.0, 1.0));\n"
       "float diff = max(dot(normal, lightDirection), 0.0);\n"
       "vec4 diffuseColor = vec4(0.7, 0.7, 0.7, 1.0);\n"
       "FragColor = diff * diffuseColor;\n"
   "}\n";

    GLuint vertex_shader = glCreateShader(GL_VERTEX_SHADER);
    glShaderSource(vertex_shader, 1, &vertex_shader_text, NULL);
    glCompileShader(vertex_shader);

    GLuint fragment_shader = glCreateShader(GL_FRAGMENT_SHADER);
    glShaderSource(fragment_shader, 1, &fragment_shader_text, NULL);
    glCompileShader(fragment_shader);

    GLuint program = glCreateProgram();
    glAttachShader(program, vertex_shader);
    glAttachShader(program, fragment_shader);
    glLinkProgram(program);

    glDeleteShader(vertex_shader);
    glDeleteShader(fragment_shader);

    return program;
}

Now the two functions can be called from main() with:

GLFWwindow* window  = glfw_prepare();
GLuint      program = gl_prepare_program(&gl_scene);

Don’t forget to add new requirements at the top of the file:

#include <glad.h>
#define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h>

Custom Data 

While traversing the model file and building the buffer objects, we will be accumulating data that we need for later purposes. Our code then needs two structures.

SceneObject represents a drawable object in our OpenGL scene. It consists of the Vertex Array Object (VAO) it is made of as well as the number of vertex indices the Vertex Buffer Object (VBO) has. On top of that, a transform matrix is provided to place the model in space.

A SceneObject is created for each drawable element in our PRC while a Vertex Array Object will be created once for each Representation Item. It is not uncommon in CAD that an element is present more than one time in a scene, but with different positioning (for example, bolts or screws). Thus, we may have distinct SceneObject instances that contain the same Vertex Array Object identifier.

typedef struct {
    mat4x4  mat_transform_model;
    GLuint  gl_vao;
    GLsizei gl_indices_count;
} SceneObject;

SceneObject’s are created one by one, for each resulting A3DMeshData or A3DRiComputeMesh(). Then, all along traversal, it is stored in a TraverseData with other fields.

typedef struct {
    std::vector<SceneObject> objects;

    std::unordered_map<A3DRiRepresentationItem*, std::pair<GLuint, GLsizei>> ri_to_gl;
    std::vector<GLuint> gl_vaos;
    std::vector<GLuint> gl_vbos;
} TraverseData;

The TraverseData structure is used to keep track of important information while traversing the model file.

In addition to objects that is the actual result of the traversal, ri_to_gl is an associative map that links representation items to their respective VAO identifier. This is used during traversal to avoid recreating a buffer objects set for representation items we already have one.

gl_vaos and gl_vbos are cleanup resources. They store all the VAO and VBO identifiers to delete them properly at the end of our main() function.

The two structures above add the following requirements at the top of our code:

#include <unordered_map>
#include <utility>
#include <vector>

Creating the Buffer Objects 

This function is crucial for this tutorial as it marks the moment when we combine HOOPS Exchange structures with OpenGL. In this context, we use the A3DMeshData to construct the lists of coordinates, normals, and indices required to build our OpenGL buffer objects.

The gl_make_buffers() function takes an A3DMeshData as a parameter and processes the vertex and normal coordinates to construct an OpenGL-ready buffer. The function returns a pair consisting of a VAO (Vertex Array Object) identifier and the number of indices in the mesh. It also takes a TraverseData object as an argument to keep track of OpenGL objects that will be deleted at the end of our program.

std::pair<GLuint, GLsizei> gl_make_buffers(A3DMeshData* const data_mesh, TraverseData* const data_traverse)
{
     // Code
}

Converting the Mesh Data

A difference exists between how A3DMeshData and OpenGL organize indices in memory. While A3DMeshData uses separate lists of indices for each vertex attribute (one for coordinates and another for normals), OpenGL requires a single set of indices that reference both the coordinates and normals. Therefore, our first step is to convert the mesh data so that both vertex attributes share the same indices.

We create two std::vector’s to store the final buffer data before sending it to the GPU:

std::vector<GLdouble> vertex_buffer;
std::vector<GLuint>   index_buffer;

The vertex_buffer will hold both the vertex coordinates and normals interleaved in this layout:

vertex_buffer = {
     // Coordinates         , Normals
     Vx0, Vy0, Vz0, Nx0, Ny0, Nz0, // Vertex 0
     Vx1, Vy1, Vz1, Nx1, Ny1, Nz1, // Vertex 1
     Vx2, Vy2, Vz2, Nx2, Ny2, Nz2, // Vertex 2
     ...
};

This interleaving is not necessary, but since we are already reorganizing the index buffer data from A3DMeshData, this is an opportunity to use a single VBO (Vertex Buffer Object) identifier for vertex attributes instead of two.

The index_buffer will contain the list of all indices that reference the vertex attributes in the vertex_buffer. The indices are ordered considering we will render triangles.

The first thing we need to do is determine the total number of indices in our mesh. For this, we iterate through A3DMeshData::m_puiTriangleCountPerFace, where each value corresponds to the number of triangles in a face. Since each triangle has 3 vertices, our total number of indices is the sum of three times each value in the array:

size_t n_indices = 0;
for (A3DUns32 face_i = 0; face_i < data_mesh->m_uiFaceSize; ++face_i) {
    n_indices += 3 * data_mesh->m_puiTriangleCountPerFace[face_i];
}

n_indices will eventually be the size of index_buffer.

Our next algorithm does the following:

It iterates through A3DMeshData::m_ppuiPointIndicesPerFace and A3DMeshData::m_ppuiNormalIndicesPerFace simultaneously to obtain the coordinate and normal indices.
For each pair of indices, it retrieves the X, Y, and Z coordinates from A3DMeshData::m_pdCoords and the X, Y, and Z normals from A3DMeshData::m_pdNormals. All six values are appended to the vertex_buffer.
This operation creates a new index to add to the index_buffer.

To prevent memory redundancy, we also identify every unique pair of coordinate/normal indices and store them in an associative map called index_cache. This way, whenever we encounter the same pair of A3DMeshData indices, we reuse the index from the cache.

The final algorithm looks like this:

std::unordered_map<uint64_t, GLuint> index_cache;

for (A3DUns32 face_i = 0; face_i < data_mesh->m_uiFaceSize; ++face_i) {
    A3DUns32 n_triangles = data_mesh->m_puiTriangleCountPerFace[face_i];
    if (n_triangles == 0) {
        continue;
    }
    const A3DUns32* ptr_coord_index = data_mesh->m_ppuiPointIndicesPerFace[face_i];
    const A3DUns32* ptr_normal_index = data_mesh->m_ppuiNormalIndicesPerFace[face_i];

    for (size_t vertex_i = 0 ; vertex_i < n_triangles * 3 ; ++vertex_i) {
        A3DUns32 coord_index = *ptr_coord_index++;
        A3DUns32 normal_index = *ptr_normal_index++;

        uint64_t cache_key = ((uint64_t)coord_index << 32) | normal_index;
        auto insertion = index_cache.insert({cache_key, vertex_buffer.size() / 6});

        GLuint vertex_index = insertion.first->second;
        if (insertion.second) {
            // Retrieve the coordinates and normals
            auto x = data_mesh->m_pdCoords[coord_index];
            auto y = data_mesh->m_pdCoords[coord_index + 1];
            auto z = data_mesh->m_pdCoords[coord_index + 2];

            // Append the coordinates and normals to the vertex_buffer
            vertex_buffer.insert(vertex_buffer.end(), {
                data_mesh->m_pdCoords[coord_index],
                data_mesh->m_pdCoords[coord_index + 1],
                data_mesh->m_pdCoords[coord_index + 2],
                data_mesh->m_pdNormals[normal_index],
                data_mesh->m_pdNormals[normal_index + 1],
                data_mesh->m_pdNormals[normal_index + 2]
            });
        }
        // Add the index to the index_buffer
        index_buffer.push_back(vertex_index);
    }
}

Sending the Data to the GPU

The next step in the gl_make_buffers() function is to send the vertex_buffer and index_buffer data to the GPU’s memory, allowing OpenGL to access them during rendering.

We create two Vertex Buffer Objects: gl_bo_vertex, which will contain the vertex attributes (coordinates and normals), and gl_bo_index for the indices. Additionally, we create a Vertex Array Object (VAO) named gl_vao. The VAO is used to enable/disable both gl_bo_vertex and gl_bo_index simultaneously when rendering. Essentially, the entire mesh is referenced using the gl_vao.

The following code creates the buffer objects and populates them with data from vertex_buffer and index_buffer. It also enables various OpenGL states that are tied to our Vertex Array Object:

GLuint gl_vao = 0;
glGenVertexArrays(1, &gl_vao);
glBindVertexArray(gl_vao);

GLuint gl_bo_vertex = 0;
glGenBuffers(1, &gl_bo_vertex);
glBindBuffer(GL_ARRAY_BUFFER, gl_bo_vertex);
glBufferData(GL_ARRAY_BUFFER, vertex_buffer.size() * sizeof(GLdouble), vertex_buffer.data(), GL_STATIC_DRAW);

GLuint gl_bo_index = 0;
glGenBuffers(1, &gl_bo_index);
glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, gl_bo_index);
glBufferData(GL_ELEMENT_ARRAY_BUFFER, index_buffer.size() * sizeof(GLuint), index_buffer.data(), GL_STATIC_DRAW);

glEnableVertexAttribArray(GL_SHADER_COORD_LOCATION);
glVertexAttribPointer(GL_SHADER_COORD_LOCATION, 3, GL_DOUBLE, GL_FALSE, 6 * sizeof(GLdouble), (void*)0);
glEnableVertexAttribArray(GL_SHADER_NORMAL_LOCATION);
glVertexAttribPointer(GL_SHADER_NORMAL_LOCATION, 3, GL_DOUBLE, GL_FALSE, 6 * sizeof(GLdouble), (void*)(3 * sizeof(GLdouble)));

glBindVertexArray(0);
glBindBuffer(GL_ARRAY_BUFFER, 0);
glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, 0);

Now that our GPU data is created, we no longer need vertex_buffer and index_buffer. We add the created buffers to our TraverseData object for later deletion, and gl_make_buffers() returns two values: gl_vao and the size of index_buffer, cast to GLsizei. These values will be used by the caller function.

Here is the full code for gl_make_buffers():

std::pair<GLuint, GLsizei> gl_make_buffers(A3DMeshData* const data_mesh, TraverseData* const data_traverse)
{
    std::vector<GLuint> index_buffer;
    std::vector<GLdouble> vertex_buffer;

    // Count the total number of indices
    // The buffer objects will have at max n_indices indices
    size_t n_indices = 0;
    for (A3DUns32 face_i = 0; face_i < data_mesh->m_uiFaceSize; ++face_i) {
        n_indices += 3 * data_mesh->m_puiTriangleCountPerFace[face_i];
    }

    // This map will serve as a cache for the OpenGL indices
    // vertex_index|normal_index -> gl_index
    std::unordered_map<uint64_t, GLuint> index_cache;

    for (A3DUns32 face_i = 0; face_i < data_mesh->m_uiFaceSize; ++face_i) {
        A3DUns32 n_triangles = data_mesh->m_puiTriangleCountPerFace[face_i];
        if (n_triangles == 0) {
            continue;
        }
        const A3DUns32* ptr_coord_index = data_mesh->m_ppuiPointIndicesPerFace[face_i];
        const A3DUns32* ptr_normal_index = data_mesh->m_ppuiNormalIndicesPerFace[face_i];

        for (size_t vertex_i = 0; vertex_i < n_triangles * 3; ++vertex_i) {
            A3DUns32 coord_index = *ptr_coord_index++;
            A3DUns32 normal_index = *ptr_normal_index++;

            uint64_t cache_key = ((uint64_t)coord_index << 32) | normal_index;
            auto insertion = index_cache.insert({ cache_key, vertex_buffer.size() / 6 });

            GLuint vertex_index = insertion.first->second;
            if (insertion.second) {
                // Retrieve the coordinates and normals
                auto x = data_mesh->m_pdCoords[coord_index];
                auto y = data_mesh->m_pdCoords[coord_index + 1];
                auto z = data_mesh->m_pdCoords[coord_index + 2];

                // Append the coordinates and normals to the vertex_buffer
                vertex_buffer.insert(vertex_buffer.end(), {
                    data_mesh->m_pdCoords[coord_index],
                    data_mesh->m_pdCoords[coord_index + 1],
                    data_mesh->m_pdCoords[coord_index + 2],
                    data_mesh->m_pdNormals[normal_index],
                    data_mesh->m_pdNormals[normal_index + 1],
                    data_mesh->m_pdNormals[normal_index + 2]
                });
            }
            // Add the index to the index_buffer
            index_buffer.push_back(vertex_index);
        }
    }

    GLuint gl_vao = 0;
    glGenVertexArrays(1, &gl_vao);
    glBindVertexArray(gl_vao);

    GLuint gl_bo_vertex = 0;
    glGenBuffers(1, &gl_bo_vertex);
    glBindBuffer(GL_ARRAY_BUFFER, gl_bo_vertex);
    glBufferData(GL_ARRAY_BUFFER, vertex_buffer.size() * sizeof(GLdouble), vertex_buffer.data(), GL_STATIC_DRAW);

    GLuint gl_bo_index = 0;
    glGenBuffers(1, &gl_bo_index);
    glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, gl_bo_index);
    glBufferData(GL_ELEMENT_ARRAY_BUFFER, index_buffer.size() * sizeof(GLuint), index_buffer.data(), GL_STATIC_DRAW);

    glEnableVertexAttribArray(GL_SHADER_COORD_LOCATION);
    glVertexAttribPointer(GL_SHADER_COORD_LOCATION, 3, GL_DOUBLE, GL_FALSE, 6 * sizeof(GLdouble), (void*)0);
    glEnableVertexAttribArray(GL_SHADER_NORMAL_LOCATION);
    glVertexAttribPointer(GL_SHADER_NORMAL_LOCATION, 3, GL_DOUBLE, GL_FALSE, 6 * sizeof(GLdouble), (void*)(3 * sizeof(GLdouble)));

    glBindVertexArray(0);
    glBindBuffer(GL_ARRAY_BUFFER, 0);
    glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, 0);

    // Store the created buffers for later deletion
    data_traverse->gl_vaos.push_back(gl_vao);
    data_traverse->gl_vbos.push_back(gl_bo_vertex);
    data_traverse->gl_vbos.push_back(gl_bo_index);

    return { gl_vao, static_cast<GLsizei>(index_buffer.size()) };
}

Traversing the Model File 

We start from the “leaf” of our operation: creating the OpenGL buffer from an A3DMeshData object. Now, our goal is to traverse the entire model file to the representation items where we call gl_make_buffers().

Our traversal has 3 main functions: traverse_representation_item(), traverse_part_definition(), and traverse_product_occurrence(). They are called whenever our traversal respectively encounters a representation item, a part definition, and a product occurrence.

All 4 functions take 4 arguments:

A handle to the traversed entity
The accumulated cascaded attributes, computed while traversing the parent entities
A model matrix, computed during traversal to establish the final model matrix of each object
A unique instance of TraverseData used to hold the results of our traversal.

Let’s start with the representation item first and go up to the model file.

Representation Item

The goal of traversing a representation item is to end up having a new SceneObject pushed into TraverseData::object.

void traverse_representation_item(A3DAsmProductOccurrence* const hnd_ri, A3DMiscCascadedAttributes* const hnd_attrs_part, const mat4x4 mat_transform_world, TraverseData* const data_traverse)
{
     // Code
}

Within a PRC, a representation item can be a single object or itself an aggregate of representation items. When this happens, the entity type of the representation item is set as kA3DTypeRiSet. In this case, we need to recursively traverse the list of representation items.

A3DEEntityType ri_type = kA3DTypeUnknown;
A3DEntityGetType(hnd_ri, &ri_type);

if (ri_type == kA3DTypeRiSet) {
   A3DRiSetData data_ri_set;
   A3D_INITIALIZE_DATA(A3DRiSetData, data_ri_set);
   code = A3DRiSetGet(hnd_ri, &data_ri_set);
   assert(code == A3D_SUCCESS);

   for(A3DUns32 ri_i = 0 ; ri_i < data_ri_set.m_uiRepItemsSize ; ++ri_i) {
       traverse_representation_item(data_ri_set.m_ppRepItems[ri_i], hnd_attrs_part, mat_transform_world, data_traverse);
   }

   A3DRiSetGet(0, &data_ri_set);
} else
     // ...

Now that we are sure we are dealing with a single representation item, we use A3DRiComputeMesh() to query a new A3DMeshData from our representation item. As seen in Getting Tessellation using A3DMeshData, a first call to our function can result in an invalid return code if the tessellation has not been computed before. In this case, we call A3DRiRepresentationItemComputeTessellation() before recomputing the mesh data:

A3DMeshData data_mesh;
A3D_INITIALIZE_DATA(A3DMeshData, data_mesh);
code = A3DRiComputeMesh(hnd_ri, hnd_attrs_part, &data_mesh);
if (code != A3D_SUCCESS)
{
    A3DRWParamsTessellationData data_params_tess;
    A3D_INITIALIZE_DATA(A3DRWParamsTessellationData, data_params_tess);
    data_params_tess.m_eTessellationLevelOfDetail = kA3DTessLODMedium;
    A3DRiRepresentationItemComputeTessellation(hnd_ri, &data_params_tess);
    code = A3DRiComputeMesh(hnd_ri, hnd_attrs_part, &data_mesh);
}
assert(code == A3D_SUCCESS);

Now that we have our instance of A3DMeshData, we can use gl_make_buffers() to generate the buffer object. However, we want to save some GPU memory here. In a PRC, a single representation item is often used many times (think about a model representing a bolt or a screw). We want to be sure we don’t generate buffer objects for representation items we already have.

Hence TraverseData::ri_to_gl. This associative container maps a representation item handle (hnd_ri) to a pair of values: the OpenGL vertex array object and the number of indices to render upon drawing the screen. Both values happen to be returned by our function gl_make_buffers().

traverse_representation_item() first searches in ri_to_gl if the representation item is already registered. If it’s the case, we use the mapped pair of values. If not, gl_make_buffers() is called, and its result is used to insert a new object.

auto gl_iterator = data_traverse->ri_to_gl.find(hnd_ri);
if(gl_iterator == data_traverse->ri_to_gl.end()) {
    auto pair = gl_make_buffers(&data_mesh, data_traverse);
    gl_iterator = data_traverse->ri_to_gl.insert({hnd_ri, pair}).first;
}

After this code, we have:

A Vertex Array Object (gl_iterator->second.first)
A number of indices to draw (gl_iterator->second.second)
A model matrix for this instance of the VAO (mat_transform_world)

We can create a new scene object and push it into our collection (set in TraverseData):

SceneObject object;
mat4x4_dup(object.mat_transform_model, mat_transform_world);
object.gl_vao = gl_iterator->second.first;
object.gl_indices_count = gl_iterator->second.second;
data_traverse->objects.push_back(object);

The function does not return anything, since the resulting scene object now lies in TraverseData::objects. The full function code is available here:

void traverse_representation_item(A3DRiRepresentationItem* const hnd_ri, A3DMiscCascadedAttributes* const hnd_attrs_part, const mat4x4 mat_transform_world, TraverseData* const data_traverse)
{
    A3DEEntityType ri_type = kA3DTypeUnknown;
    A3DEntityGetType(hnd_ri, &ri_type);

    if (ri_type == kA3DTypeRiSet) {
        A3DRiSetData data_ri_set;
        A3D_INITIALIZE_DATA(A3DRiSetData, data_ri_set);
        code = A3DRiSetGet(hnd_ri, &data_ri_set);
        assert(code == A3D_SUCCESS);

        for(A3DUns32 ri_i = 0 ; ri_i < data_ri_set.m_uiRepItemsSize ; ++ri_i) {
            traverse_representation_item(data_ri_set.m_ppRepItems[ri_i], hnd_attrs_part, mat_transform_world, data_traverse);
        }

        A3DRiSetGet(0, &data_ri_set);
    } else {
        A3DMeshData data_mesh;
        A3D_INITIALIZE_DATA(A3DMeshData, data_mesh);
        code = A3DRiComputeMesh(hnd_ri, hnd_attrs_part, &data_mesh);
        if (code != A3D_SUCCESS)
        {
            A3DRWParamsTessellationData data_params_tess;
            A3D_INITIALIZE_DATA(A3DRWParamsTessellationData, data_params_tess);
            data_params_tess.m_eTessellationLevelOfDetail = kA3DTessLODMedium;
            A3DRiRepresentationItemComputeTessellation(hnd_ri, &data_params_tess);
            code = A3DRiComputeMesh(hnd_ri, hnd_attrs_part, &data_mesh);
        }
        assert(code == A3D_SUCCESS);

        auto gl_iterator = data_traverse->ri_to_gl.find(hnd_ri);
        if(gl_iterator == data_traverse->ri_to_gl.end()) {
            auto pair = gl_make_buffers(&data_mesh, data_traverse);
            gl_iterator = data_traverse->ri_to_gl.insert({hnd_ri, pair}).first;
        }

        SceneObject object;
        mat4x4_dup(object.mat_transform_model, mat_transform_world);
        object.gl_vao = gl_iterator->second.first;
        object.gl_indices_count = gl_iterator->second.second;
        data_traverse->objects.push_back(object);

    }
}

traverse_representation_item() is either called recursively by another traverse_representation_item() or upon visiting a part definition in traverse_part_definition().

Part Definition

Traversing the part definition is a pass-through function that does the following:

Updates the accumulated cascaded attributes (see Updating the Cascaded Attributes in the next function below).
Calls traverse_representation_item() for each representation item in the entity.

void traverse_part_definition(A3DAsmPartDefinition* const hnd_part, A3DMiscCascadedAttributes* const hnd_attrs_po, const mat4x4 mat_transform_world, TraverseData* const data_traverse)
{
    if(hnd_part == 0) {
        return;
    }

    A3DMiscCascadedAttributes* hnd_attrs_part = 0;
    A3DMiscCascadedAttributesCreate(&hnd_attrs_part);
    A3DMiscCascadedAttributesPush(hnd_attrs_part, hnd_part, hnd_attrs_po);

    A3DAsmPartDefinitionData data_part;
    A3D_INITIALIZE_DATA(A3DAsmPartDefinitionData, data_part);
    code = A3DAsmPartDefinitionGet(hnd_part, &data_part);
    assert(code == A3D_SUCCESS);

    for (A3DUns32 ri_i = 0 ; ri_i < data_part.m_uiRepItemsSize ; ++ri_i) {
        traverse_representation_item(data_part.m_ppRepItems[ri_i], hnd_attrs_part, mat_transform_world, data_traverse);
    }

    A3DAsmPartDefinitionGet(0, &data_part);
}

traverse_part_definition() is called whenever we find a new part definition from traverse_product_occurrence().

Product Occurrence

Going one level up in our PRC hierarchy, we find traverse_product_occurrence().

Updating the Cascaded Attributes

The first thing the function does is stack up the cascaded attributes of our current product occurrence onto the cascaded attributes stack. For this, we use A3DMiscCascadedAttributesCreate() to create a new instance of A3DMiscCascadedAttributes. Then we push it onto the stack with A3DMiscCascadedAttributesPush(). Finally, we need to attach the new cascaded attributes entity to our current product occurrence with A3DMiscCascadedAttributesEntityReferencePush(). This function is necessary to preserve the propagation of cascaded attributes upstream when the product occurrence is an assembly.

A3DMiscCascadedAttributes* hnd_attrs_po = 0;
A3DMiscCascadedAttributesCreate(&hnd_attrs_po);
A3DMiscCascadedAttributesPush(hnd_attrs_po, hnd_po, hnd_attrs_parent);
A3DMiscCascadedAttributesEntityReferencePush(hnd_attrs_po, hnd_po, 0);

Computing the Model Matrix

After fetching the product occurrence data with A3DAsmProductOccurrenceGet(), the next thing we do is compute the current model matrix. The computation is done by generating the 4x4 transform matrix of the current transformation and multiplying it by the current one passed as a parameter to our function:

A3DMiscTransformation* hnd_po_transformation = get_product_occurrence_transformation(hnd_po);
mat4x4 mat_transform_po_local, mat_transform_po_world;
mat4x4_from_transformation(hnd_po_transformation, mat_transform_po_local);
mat4x4_mul(mat_transform_po_world, mat_transform_world, mat_transform_po_local);

This code uses two custom functions that we also need to define:

First, retrieving the correct A3DMiscTransformation is not a direct operation. If the current product occurrence doesn’t have one and happens to be a prototype product occurrence, we want to retrieve the transformation entity from the prototype instead. This leads to the creation of get_product_occurrence_transformation() that returns the correct transformation entity given how our product occurrence is defined:

A3DMiscTransformation* get_product_occurrence_transformation(A3DAsmProductOccurrence* hnd_po)
{
    if(hnd_po == 0) {
        return 0;
    }

    A3DAsmProductOccurrenceData data_po;
    A3D_INITIALIZE_DATA(A3DAsmProductOccurrenceData, data_po);
    code = A3DAsmProductOccurrenceGet(hnd_po, &data_po);
    assert(code == A3D_SUCCESS);

    A3DMiscTransformation* hnd_po_transformation = data_po.m_pLocation;
    if (hnd_po_transformation == 0) {
        A3DAsmProductOccurrence* hnd_po_reference = data_po.m_pPrototype ? data_po.m_pPrototype : data_po.m_pExternalData;
        hnd_po_transformation = get_product_occurrence_transformation(hnd_po_reference);
    }

    A3DAsmProductOccurrenceGet(0, &data_po);
    return hnd_po_transformation;
}

Then, A3DMiscTransformation needs to be converted into a column-major model matrix that can be manipulated by our math and graphics libraries (linmath and OpenGL):

void mat4x4_from_transformation(const A3DMiscTransformation* hnd_transformation, mat4x4 mat_result)
{
    if (hnd_transformation == 0) {
        mat4x4_identity(mat_result);
    } else {
        A3DEEntityType entity_type = kA3DTypeUnknown;
        A3DEntityGetType(hnd_transformation, &entity_type);
        assert(entity_type == kA3DTypeMiscCartesianTransformation);

        A3DMiscCartesianTransformationData data;
        A3D_INITIALIZE_DATA(A3DMiscCartesianTransformationData, data);
        code = A3DMiscCartesianTransformationGet(hnd_transformation, &data);
        assert(code == A3D_SUCCESS);


        vec3 x_vector = {(float)data.m_sXVector.m_dX, (float)data.m_sXVector.m_dY, (float)data.m_sXVector.m_dZ};
        vec3 y_vector = {(float)data.m_sYVector.m_dX, (float)data.m_sYVector.m_dY, (float)data.m_sYVector.m_dZ};
        vec3 z_vector;
        vec3_mul_cross(z_vector, x_vector, y_vector);

        double mirror = ( data.m_ucBehaviour & kA3DTransformationMirror ) ? -1. : 1.;

        mat_result[0][0] = data.m_sXVector.m_dX * data.m_sScale.m_dX;
        mat_result[0][1] = data.m_sXVector.m_dY * data.m_sScale.m_dX;
        mat_result[0][2] = data.m_sXVector.m_dZ * data.m_sScale.m_dX;
        mat_result[0][3] = 0.;

        mat_result[1][0] = data.m_sYVector.m_dX * data.m_sScale.m_dY;
        mat_result[1][1] = data.m_sYVector.m_dY * data.m_sScale.m_dY;
        mat_result[1][2] = data.m_sYVector.m_dZ * data.m_sScale.m_dY;
        mat_result[1][3] = 0.;

        mat_result[2][0] = mirror * z_vector[0] * data.m_sScale.m_dZ;
        mat_result[2][1] = mirror * z_vector[1] * data.m_sScale.m_dZ;
        mat_result[2][2] = mirror * z_vector[2] * data.m_sScale.m_dZ;
        mat_result[2][3] = 0.;

        mat_result[3][0] = data.m_sOrigin.m_dX;
        mat_result[3][1] = data.m_sOrigin.m_dY;
        mat_result[3][2] = data.m_sOrigin.m_dZ;
        mat_result[3][3] = 1.;

        A3DMiscCartesianTransformationGet(0, &data);
    }
}

Traversing the Part Definition

Back to our traverse_product_occurrence() function, we now have everything we need to call traverse_part_definition():

A3DAsmPartDefinition* hnd_part = get_product_occurrence_part_definition(hnd_po);
traverse_part_definition(hnd_part, hnd_attrs_po, mat_transform_po_world, data_traverse);

Similarly to A3DMiscTransformations, get_product_occurrence_part_definition() returns the correct A3DAsmPartDefinition for a given product occurrence. The code is the same as for get_product_occurrence_transformation():

A3DAsmPartDefinition* get_product_occurrence_part_definition(A3DAsmProductOccurrence* hnd_po)
{
    if(hnd_po == 0) {
        return 0;
    }

    A3DAsmProductOccurrenceData data_po;
    A3D_INITIALIZE_DATA(A3DAsmProductOccurrenceData, data_po);
    code = A3DAsmProductOccurrenceGet(hnd_po, &data_po);
    assert(code == A3D_SUCCESS);

    A3DMiscTransformation* hnd_part = data_po.m_pPart;
    if (hnd_part == 0) {
        A3DAsmProductOccurrence* hnd_po_reference = data_po.m_pPrototype ? data_po.m_pPrototype : data_po.m_pExternalData;
        hnd_part = get_product_occurrence_part_definition(hnd_po_reference);
    }

    A3DAsmProductOccurrenceGet(0, &data_po);
    return hnd_part;
}

Recursively Traverse the Product Occurrences

PRC is a recursive structure where each product occurrence contains a set of child product occurrences. Thus, when we are done with our current product occurrence, we want to call traverse_product_occurrence() again for each of its children:

for (A3DUns32 po_i = 0 ; po_i < data_po.m_uiPOccurrencesSize ; ++po_i) {
    traverse_product_occurrence(data_po.m_ppPOccurrences[po_i], hnd_attrs_po, mat_transform_po_world, data_traverse);
}

The full code for traverse_product_occurrence() is available here:

void traverse_product_occurrence(A3DAsmProductOccurrence* const hnd_po, A3DMiscCascadedAttributes* const hnd_attrs_parent, const mat4x4 mat_transform_world, TraverseData* const data_traverse)
{

    A3DMiscCascadedAttributes* hnd_attrs_po = 0;
    A3DMiscCascadedAttributesCreate(&hnd_attrs_po);
    A3DMiscCascadedAttributesPush(hnd_attrs_po, hnd_po, hnd_attrs_parent);
    A3DMiscCascadedAttributesEntityReferencePush(hnd_attrs_po, hnd_po, 0);


    A3DAsmProductOccurrenceData data_po;
    A3D_INITIALIZE_DATA(A3DAsmProductOccurrenceData, data_po);
    code = A3DAsmProductOccurrenceGet(hnd_po, &data_po);
    assert(code == A3D_SUCCESS);

    // Accumulate the position
    A3DMiscTransformation* hnd_po_transformation = get_product_occurrence_transformation(hnd_po);
    mat4x4 mat_transform_po_local, mat_transform_po_world;
    mat4x4_from_transformation(hnd_po_transformation, mat_transform_po_local);
    mat4x4_mul(mat_transform_po_world, mat_transform_world, mat_transform_po_local);

    A3DAsmPartDefinition* hnd_part = get_product_occurrence_part_definition(hnd_po);
    traverse_part_definition(hnd_part, hnd_attrs_po, mat_transform_po_world, data_traverse);

    for (A3DUns32 po_i = 0 ; po_i < data_po.m_uiPOccurrencesSize ; ++po_i) {
        traverse_product_occurrence(data_po.m_ppPOccurrences[po_i], hnd_attrs_po, mat_transform_po_world, data_traverse);
    }

    A3DAsmProductOccurrenceGet(0, &data_po);
}

traverse_product_occurrence() is thus called either from a parent call of traverse_product_occurrence() or from traverse_model_file().

Model File

traverse_model_file() is the entry point of our traversal operation.

The function initializes the first cascaded attribute as well as the transform matrix and calls traverse_product_occurrence() for each product occurrence in the given model file:

void traverse_model_file(A3DAsmModelFile* const hnd_modelfile, TraverseData* const data_traverse)
{
    A3DMiscCascadedAttributes* hnd_attrs_modelfile = 0;
    A3DMiscCascadedAttributesCreate(&hnd_attrs_modelfile);

    A3DAsmModelFileData data_modelfile;
    A3D_INITIALIZE_DATA(A3DAsmModelFileData, data_modelfile);
    code = A3DAsmModelFileGet(hnd_modelfile, &data_modelfile);
    assert(code == A3D_SUCCESS);

    mat4x4 mat_transform;
    mat4x4_identity(mat_transform);

    for (A3DUns32 po_i = 0 ; po_i < data_modelfile.m_uiPOccurrencesSize ; ++po_i) {
        traverse_product_occurrence(data_modelfile.m_ppPOccurrences[po_i], hnd_attrs_modelfile, mat_transform, data_traverse);
    }

    A3DAsmModelFileGet(0, &data_modelfile);
    A3DMiscCascadedAttributesDelete(hnd_attrs_modelfile);
}

traverse_model_file() is directly called from main() once the model file has been loaded with load_model_file() and the OpenGL context is prepared.

The Main Loop 

Our main loop function is a mix of GLFW and OpenGL code.

Before we run the loop, we need to retrieve the shader locations for our transform matrices. We have 3 matrices (the model, the view, and the projection), thus we have 3 variables:

GLint p_location = glGetUniformLocation(program, "p");
GLint v_location = glGetUniformLocation(program, "v");
GLint m_location = glGetUniformLocation(program, "m");

Now, within the loop, we prepare the view and projection matrices. The projection matrix p never changes and corresponds to an orthographic view:

mat4x4_ortho(p, -150.f, 150.f, -150.f, 150.f, -1000, 1000.0);

The view matrix will simulate a rotating camera around our model:

mat4x4_identity(v);
float radius = 150.f;
float angle  = glfwGetTime();
vec3 eye     = {cosf(angle) * radius, cosf(angle / 100.0) * radius, sinf(angle) * radius};
vec3 center  = {0.0, 0.0, 0.0};
vec3 up      = {0.0, 1.0, 0.0};
mat4x4_look_at(v, eye, center, up);

Now, each object we created in traverse_representation_item() is drawn. The following loop goes through the array we previously populated in TraverseData. For each of the elements, we send the Vertex Array Object ID, the model matrix, as well as the number of indices the mesh is made of.

Eventually, we ask GLFW to swap our render buffer and enable window event listening:

glUseProgram(program);

for(const SceneObject* object = object_start ; object <= object_start + n_objects ; ++object) {
    glUniformMatrix4fv(p_location, 1, GL_FALSE, (const GLfloat*) p);
    glUniformMatrix4fv(v_location, 1, GL_FALSE, (const GLfloat*) v);
    glUniformMatrix4fv(m_location, 1, GL_FALSE, (const GLfloat*) object->mat_transform_model);

    glBindVertexArray(object->gl_vao);
    glDrawElements(GL_TRIANGLES, object->gl_indices_count, GL_UNSIGNED_INT, 0);
}

glfwSwapBuffers(window);
glfwPollEvents();

The full code for glfw_loop() is available here:

void glfw_loop(GLFWwindow* window, GLuint program, const SceneObject* object_start, size_t n_objects)
{
    GLint p_location = glGetUniformLocation(program, "P");
    GLint v_location = glGetUniformLocation(program, "V");
    GLint m_location = glGetUniformLocation(program, "M");

    while (!glfwWindowShouldClose(window))
    {
        int width, height;
        mat4x4 m, v, p;

        glfwGetFramebufferSize(window, &width, &height);
        glViewport(0, 0, width, height);

        glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

        mat4x4_ortho(p, -150.f, 150.f, -150.f, 150.f, -1000, 1000.0);

        mat4x4_identity(v);
        float radius = 150.f;
        float angle  = glfwGetTime();
        vec3 eye     = {cosf(angle) * radius, cosf(angle / 100.0) * radius, sinf(angle) * radius};
        vec3 center  = {0.0, 0.0, 0.0};
        vec3 up      = {0.0, 1.0, 0.0};
        mat4x4_look_at(v, eye, center, up);

        glUseProgram(program);

        for(const SceneObject* object = object_start ; object <= object_start + n_objects ; ++object) {
            glUniformMatrix4fv(p_location, 1, GL_FALSE, (const GLfloat*) p);
            glUniformMatrix4fv(v_location, 1, GL_FALSE, (const GLfloat*) v);
            glUniformMatrix4fv(m_location, 1, GL_FALSE, (const GLfloat*) object->mat_transform_model);

            glBindVertexArray(object->gl_vao);
            glDrawElements(GL_TRIANGLES, object->gl_indices_count, GL_UNSIGNED_INT, 0);
        }

        glfwSwapBuffers(window);
        glfwPollEvents();
    }
}

The Main Function 

The main() function wraps up everything by calling all the preparation functions and the loop:

int main(int argc, char* argv[])
{
    GLFWwindow* window  = glfw_prepare();
    GLuint      program = gl_prepare_program();

    A3DSDKLoadLibraryA(HE_BINARY_DIRECTORY);
    A3DLicPutUnifiedLicense(HOOPS_LICENSE);
    A3DDllInitialize(A3D_DLL_MAJORVERSION, A3D_DLL_MINORVERSION);

    A3DAsmModelFile* model_file = load_model_file(HE_DATA_DIRECTORY INPUT_FILE);

    TraverseData     data_traverse;
    traverse_model_file(model_file, &data_traverse);

    A3DAsmModelFileDelete(model_file);
    A3DDllTerminate();
    A3DSDKUnloadLibrary();

    printf("Starting Loop\n");
    glfw_loop(window, program, data_traverse.objects.data(), data_traverse.objects.size());

    // Clean up all resources
    glDeleteProgram(program);
    glDeleteVertexArrays(data_traverse.gl_vaos.size(), data_traverse.gl_vaos.data());
    glDeleteBuffers(data_traverse.gl_vaos.size(), data_traverse.gl_vaos.data());

    glfwDestroyWindow(window);
    glfwTerminate();

    return EXIT_SUCCESS;
}

A complete version of main.cpp is avaiable in the project repository.

Note that in our example, once the buffer objects have been eventually created from a call to traverse_model_file(), HOOPS Exchange is not needed anymore and can be closed.

Compile and Run the Project 

The project runs CMake and can be used with any supported platform.

From your environment, run CMake and select the project folder as the source directory. Then configure and generate the project.

Once generated, use your compiler’s environment to build and run the project.

For more information about using HOOPS Exchange with CMake, see Setting Up a CMake Project.