5.1 Overview

GEOMLIB is the geometrical library of the VRR project.

5.1.1 Purpose

Geometrical library (GEOMLIB) consists of the following modules:

• General numerical algorithms such as polynomial solver or linear system solver.
• Simple geometrical computation with points, vectors and affine transformations.
• General geometrical data structures such as R*-Tree.
• Objective programming emulation for C99 standard.
• Hierarchy of geometrical classes, especially various curve types. Computations can be accessed through (virtual) methods.

The library is almost independent part of VRR project and uses only VRRLIB definitions. See VRRLIB for description of VRRLIB.

5.1.2 Error handling

Many functions in GEOMLIB can fail because of floating point error or a different reason. Each error type is described by its unique error code (a negative integer constant), for example GEOM_ERR_NUMERIC. Full list of error codes can be found in the file geomlib/err.h.

Most of possibly failing routines follow these calling conventions:

• If a function returns integer type, zero or positive result means success, while negative result means one of defined error codes.
• If a function returns floating point type, it succeedes, when result is finite number. It fails otherwise.
• If a function returning pointer type fails, result is NULL.

In some cases the error code is stored in global variable geom_errno. To simplify long error testing and code debugging, there are many basic macros defined in the file geomlib/base.h. For historical reasons, some older parts of GEOMLIB do not return predefined integer error codes and only return undefined negative values.

5.1.3 Floating-point arithmetic

The library mainly uses real floating-point type defined in VRRLIB, which can be of float or double precision. Some more ambitious computations (i.e. polynomial solver) are fixed to the double precision. NaN (not a number) or infinities are usually considered as invalid values and produce the GEOM_ERR_NUMERIC error.

5.1.4 Functions input and output

If nothing else is said in function description, all parameters must contain valid data (floating-point types must contain finite numbers, pointers must not be NULL and structures must agree with their definitions).

Successfully finished functions always return valid or explicitly described results. Pointers to resulting structures should not overlap with other parameters. The result of failed function is undefined.

5.1.5 Header files

The main GEOMLIB header is geomlib/geomlib.h. By including this file, all structures, functions and macros can be used. It is also possible to include only a smaller subset of definitions by including the appropriate header file. There are no inclusion dependencies, because necessary headers are used recursively. Most of identifiers in GEOMLIB starts with geom_ or GEOM_ prefix. Some shorter internal aliases may be enabled by defining macro GEOM_SOURCE before the first header inclusion.

5.1.6 Self-testing code

GEOMLIB contains a script, which should help to find errors in the library implementation by applying some automated random tests. These testing routines are located in the file geomlib/geomlibtest.c and are compiled together with GEOMLIB. There are many tests of object-oriented programming emulation and correctness of numerical algorithms. Floating point results are tested to a small epsilon constant.