Tech/GLGeom/Documentation

From Athile

API Overview

The API overview documentation is designed to give a quick, general, pseudo-code overview to the library. It should give you a lay of the land, so that you know what GLGeom can do and where to look for more specific information. The intended workflow is this: use the API Overview to determine if the code use need exists, then check the header file for specific information on that function or type.

This document is very new and currently provided as a simple text file! The goal is to eventually provide a well-formatted HTML document.

• Current API Overview

See the Releases for links to the API overview for a specific version of the library.

Organization

Module Structure

The GLGeom is organized as a single library with different modules of functionality within the library. The modules represent a set of closely related classes and/or functions. For example, the "color" module adds functions and classes for storing and manipulating colors in various formats and the "intersection" module contains collection of functions and data structures for finding the intersections between objects.

These modules are then categorized into one of three groups:

• Core - modules that common, well-tested, and 'standard'
• Extension - modules that are less common but still represent well-tested, robust code
• Prototype - experimental code highly subject to change

The individual modules are given a fully qualified name such as "glgeom_core_color".

File Structure

The project uses a "lots of small files" approach. The directory structure mirrors the module layout. Each class definition is given it's own hpp file. The corresponding inl file contains the method definitions and any functions that use only that class (note: this is a purely template library, so there are no cpp files).

The functions.inl file is reserved for functions using multiple classes within the module.

The upper-level module.hpp file includes all the sub-headers and inline files for the module, thus including the whole module.

glgeom\
    core\
        module1\
            class1.hpp
            class1.inl
            class2.hpp
            class2.hpp
            functions.inl
        module1.hpp
    extension\
        module1\
            ...
        module1.hpp
    prototype\
        module1\
            ...
        module1.hpp

Namespace Structure

The namespace structure mirrors the module layout as well:

namespace glgeom
{
    namespace core
    {
        namespace module
        {
        }
    }
}

Therefore any element can be referenced via fully qualified name to the module element.

Any internal methods are kept within a "detail" namespace within the module namespace.

However, to avoid having to type out the fully qualified name every time, each module is imported into the glgeom outer namespace:

namespace glgeom
{
    using namespace core::module;
}

Coding Style

The library favors functions over methods.

Naming Conventions

• no suffix - calls the presumed best implementation of the function
• _simd suffix - a function written specifically to use SIMD instructions
• _generic suffix - a function using standard C++ code

• type_from() - provides a constructor like function for type

User Manual

Error Handling

GLGeom is a low-level library that does not do extensive error-checking. The caller is expected to validate arguments before making a call to GLGeom. This is done for efficiency.

Internal errors are handled by calling:

glgeom::error(const char* message)

The default behavior is to output the message to std::cerr and then call assert.

The default behavior can be overridden by providing a custom handler via the function:

glgeom::set_error_handler(std::function<void (const char* message)>)

Warning: GLGeom is not exception-aware. If providing a custom error handler that throws an exception, there is a risk the GLGeom code may not properly clean-up any data from functions that were currently in progress.