# GL Geometry C++ Library(GLGeom)

## Overview

GL Geometry (GLGeom) is C++ template library for graphics software that adds common geometry primitives and operations. The library builds upon and follows many of the conventions of the OpenGL Mathematics (GLM) library, allowing developers familiar with GLM or GLSL to easily become comfortable with GLGeom. It is intended for use in ray-tracing, rasterization, computational geometry, physics, simulation, and other such geometrically-based applications.

The library provides strongly typed classes for such concepts as degrees, radians, points, vectors, and colors. GLGeom provides classes such as lines, rays, line segments, circles, arcs, curves, surfaces. Likewise cube, spheres, and generalized solids have classes. Useful concepts such as axis-aligned bounding boxes, oriented bounding boxes, bounding spheres, and other common types are provided. Functions are provided for mathematical operations on all these types and their interactions, such as distances, intersections, approximations, etc. Both 2D and 3D variations of all relevant classes and operations are available, and furthermore GLGeom supports all of GLM's various data precision types.

GLGeom builds upon the conventions of OpenGL, but is a pure C++ library with no dependencies on OpenGL or any graphics rendering. The classes and functions provided by GLGeom are mathematical in nature and do not provide rendering, serialization, or any other services outside the computational domain. There are no direct mesh data structures or spatial indexing classes provided within GLGeom.

The GLGeom library design favors convenience and clarity over raw efficiency when the two are mutually exclusive: in other words, while the library provides efficient implementations, applications bottlenecks may require hand-coded alternatives to the GLGeom provided functions and types. That said, GLGeom does aim to provide as efficient implementations as possible that can be done without sacrificing the API cleanliness.

The library is intended primarily for graphics, physics, and other simulation applications.

The source code is available under the MIT License.

## Documentation

See the Documentation page and see the API Documentation below for the relevant version in question.

## Changelog

### Version 0.0.6 (2012.04.12)

General Notes

• GLGeom requires a compiler with C++0x support. The code currently has only been tested on Visual Studio 2010 and gcc 4.6.
• GLGeom relies on the GLM library, the headers of which should be placed in extern/include/glm directory in order to build the unit tests

Summary of Changes

It's been a long time since the last release. This list is not complete. See the API documentation for the most accurate information about the library functionality.

• Added glgeom_core_interpolation for interpolation functions
• Added glgeom_extension_samplers for generating a set of samples over a given domain
• Added glgeom::error() and glgeom::set_error_handler() to handle errors
• Added a lot more functions for use with glgeom::primitive_buffer
• Added stub for disc primitive
• Added perpendicular_axis_fast() to find an arbitrary vector perpendicular to the input
• Added perpendicular_axis_smooth() like the above but returns a vector that various continously (no jumps) across the domain of all vectors, at the cost of some run-time speed
• Added overloads of perpendicular_axis_fast/smooth() to find a pairs vectors perpendicular to the input
• Added several methods to abbox
• Fixed various defects with the swizzle code (const-correctness, missing on some classes)
• Improved Doxygen API documentation formatting slightly (via some JQuery hacks)
• A bunch more minor things...

### Version 0.0.5 (2011.09.09)

General Notes

• GLGeom requires a compiler with C++0x support. The code currently has only been tested on Visual Studio 2010 and gcc 4.6.
• GLGeom relies on the GLM library, the headers of which should be placed in extern/include/glm directory in order to build the unit tests

Summary of Changes

• Restructuring of source files into folders by module
• Add preliminary mapper and pattern extensions
• Add swizzle operators for point, vector, and color
• Add cube map image type
• Many, many minor additions to flesh out the code

### Version 0.0.4 (2011.05.18)

This release adds support for gcc 4.6, fixes a few defects in the cone intersection code, and adds support for cylinders and cubes.

Note: GLGeom requires a compiler with C++0x support. The code currently has only been tested on Visual Studio 2010 and gcc 4.6.

### Version 0.0.3 (2011.05.11)

This release adds the first pass at API documentation. This includes some custom jquery code to attempt to make the Doxygen generated docs more usable. Various source code changes were made across the library.

Note: GLGeom requires a compiler with C++0x support. The library has currently only been tested with Microsoft Visual Studio 2010.

### Version 0.0.2 (2011.05.08)

This is the first downloadable release. The code has been refactored out of LxEngine so that it builds independently and has its own CMake setup. It's version 0.0.2 so the completeness and documentation of the library are sorely lacking. At such an early stage, directly using the source from the GLGeom git repository is probably the best option.

### Version 0.0.1 (2011.05.07)

The LxEngine SDK now contains the beginnings of a ray tracer sample. The ray tracer does basic casting and intersections with GLGeom primitives. This seems to be sufficient real world testing to declare an arbitrary version bump to 0.01.

### Version 0.0.0 (2011.04.21)

The version 0.0.0 announcement marks the start of the GLGeom project. The relevant code will be extracted out of the LxEngine codebase into an independent template library following the conventions of GLM.

• triangle
• mesh
• voxel

### Algorithms

• Patterns - i.e. tile, wave, checker,
• Mappers - spherical, cube, etc.

• BSP
• grid
• octree

## Design Issues

### Open

#### Should GLGeom reflect all glm classes and functions in the glgeom namespace?

Details: This would avoid confusion about which namespace a class belongs to: e.g. mat4 in glm, but point3 in glgeom. This also would allow consistent naming, e.g. mat4f could be the glgeom imported name. This would also allow for tailoring the glm namespace restrictions: e.g. moving glm::detail::tvec3 to glgeom::vec3t (which could be more convenient given how often the templatized version is used).

On the other hand, this might not display proper attribution to the glm native classes: i.e. it would look like glgeom::mat4 was implemented by the glgeom library, where in fact the glm library should get proper attribution for the implementation.

#### Should GLGeom include a tuple type or should glm::vec be used instead?

Response: If so, glm::mat4 should likely be used rather than GLGeom::matrix4.

Response: There are arguments both ways. It is a bit confusing and inconvenient swapping between glm and glgeom namespaces and functions (e.g. do you call glm::normalize() or glgeom::normalize() on a given variable?). However, mirroring all the functionality of glm::vec directly into a new class with minimal differences seems it would be a maintenance headache with little benefit. Might importing the glgeom classes into the glm namespace help? --Arthur 12:20, 8 May 2011 (CDT)

### Pending

#### Should GLGeom be made into a static library?

Details: Here's the idea: rather than simply use typedefs for the templates, use inheritance for all the common types (float, double, etc.). Build these types into a library so that the compiler does not have to deal with templates, thus potentially improving compilation time. The templates are, of course, still accessible directly for any unique types that might need to be instanciated.

Response: Postpone acting on this until the library is a bit more mature. Then run some tests to see if this would in fact improve compilation times noticeably.

#### Should color be split into rgb, hsv, etc. varieties?

Response: Possibly in a future release. --Arthur 09:19, 26 June 2011 (CDT)

### Closed

#### Should GLGeom include a matrix type or use glm::mat directly?

Details: Is glm::mat lacking anything that requires a custom matrix class?

Response: Use glm directly. glm::mat seems fully sufficient. --Arthur 12:01, 8 July 2011 (CDT)

Response: Given that glm has it's own matrix class and GLGeom is not yet complete, development of a custom matrix class should at least be made a lower priority than classes that are clearly unique to GLGeom.

#### Why does GLGeom differentiate between points and vectors?

a.k.a.: Why not use glm::vec all the time?

Response: Consider the case of transforming a ray. A ray is composed of a point (a 3-tuple) and a vector (also a 3-tuple). However, the algorithm to transform a point is different from the code to transform a vector as translation applies in the case of a point and not a vector. By making the types distinct, a single overloaded transform() function can be trusted to 'do the right thing' or at least 'not do the wrong thing' in most cases.

There's also nothing preventing the client from accessing points and vectors as glm::vecs via the vec field or from simply using glm::vec instead. GLGeom provides strictly typed classes for points and vectors, but is fully interoperable when using generic 2, 3, and 4 float tuples.

--Arthur 03:34, 11 May 2011 (CDT)