== Hacking ==

In this section we look at coding conventions and some of the design models used in coding graphiteng.

=== Compiling and Integrating ===

To compile the graphite2 library for integration into another application framework, there are some
useful utilities and also various definitions that need to be defined. The file src/files.mk will create
three make variables containing lists of files that someone will want to build in order to build
graphite2 from source as part of an application build. The variable names are controlled by setting
_NS to a prefix that is then applied to the variable names _SOURCES, _PRIVATE_HEADERS and _PUBLIC_HEADERS.
All files are listed relative to the variable _BASE (with its _NS expansion prefix). The _MACHINE variable
with its _NS expansion prefix, must be set to 'call' or 'direct' depending on which kind of virtual
machine to use inside the engine. gcc supports direct call, while all other compilers without a computed
goto should use the call style virtual machine. See src/direct_machine.cpp and src/call_machine.cpp for details.

Various C preprocessor definitions are also used as part of compiling graphite2:

GRAPHITE2_EXPORTING::
    Needs to be set when building the library source if your are build it as a DLL.
    When unset the graphite header API will be marked dllimport for use in client code.

GRAPHITE2_STATIC::
    If set removes all dllimport or dllexport declspecs on the Graphtie2 API functions and makes them 
    exportable for a clean static library build on Windows. 

GRAPHITE2_NSEGCACHE::
    If set, the segment caching code is not compiled into the library. This can be used to save space
    if the engine is under space constraints both for code and memory. The default is that this is not
    defined.

GRAPHITE2_NFILEFACE::
    If set, the code to support creating a face directly from a font file is not included in the library.
    By default this is not set.

GRAPHITE2_NTRACING::
    If set, the code to support tracing segment creation and logging to a json output file is not built.
    However the API remains, it just won't do anything.

GRAPHITE2_CUSTOM_HEADER::
    If set, then the value of this macro will be included as a header in Main.h (in effect, all source files). See Main.h for details.

=== Memory Allocation ===

+++While GraphiteNG is written in C++, it is targetted at environments where
libstdc++ is not present. While this can be problematic since functions used in
C++ may be arbitrarily placed in libc and libstdc++, there are general
approaches that can help. To this end we use a mixed memory allocation model.
For graphiteng classes, we declare our own new() methods and friends, allowing
the use of C++ new() and all that it gives us in terms of constructors. For
types that are not classes we use malloc() or the type safe version gralloc().+++

=== Missing Features ===

There are various facilities that silgraphite provides that graphite2 as yet does not. The primary motivation in developing graphite2 is that it be use case driven. Thus only those facilities that have a proven use case in the target applications into which graphite is to be integrated will be implemented.

Justification::
    Silgraphite has the ability to handle complex justification. This is not
    part of graphite2 yet. But then neither were any external applications making use
    of this facility within silgraphite.

Line End Contextuals::
    The cost of implementing line end contextuals is high and no fonts actually make use of it or need to make use of it. If the need were to rearise, line end contextuals could be integrated with a justification pass.

Ligature Components::
    Graphite has the ability to track ligature components and this feature is used in some fonts. But application support has yet to be proven and this is an issue looking for a use case and appropriate API.

SegmentPainter::
    Silgraphite provides a helper class to do range selection, cursor hitting and
    support text editing within a segment. These facilities were not being used in
    applications. Graphite2 does not preclude the addition of such a helper class
    if it would be of help to different applications, since it would be layered
    on top of graphite2.

Hinted Attachment Points::
    No use has been made of hinted attachment points, and so until a real use case requirement is proven, these are not in the font api. They can be added should a need be proven.

=== Hunting Speed ===

Graphite2 is written based on experience of using SilGraphite. SilGraphite was written primarily to be feature complete in terms of all features that may be needed. Graphite2 takes the experience of using SilGraphite and starts from a use case requirement before a feature is added to the engine. Thus a number of features that have not been used in SilGraphite have been removed, although the design is such that they can be replaced in future.

In addition, a number of techniques were used to speed up the engine. Some of these are discussed here.

Slot Stream::
    Rather than copying slots from one stream to another, the slot stream is allocated in blocks of slots and the processing is done in place. This means that each pass is executed to completion in sequence rather than using a pull model that SilGraphite uses. In addition, the slot stream is held as a linked list to keep the cost of insertion and deletion down for large segments.

Virtual Machine::
    The virtual machine that executes action and condition code is optimised for speed with different versions of the core engine code being used dependent upon compiler. The interpretted code is also pre-analysed for checking purposes and even some commands are added necessary for the inplace editing of the slot stream.

Design Space Positioning::
    The nature of the new processing model is that all concrete positioning is done in a final finalisation process. This means that all passes can be run in design space and then only at finalisation positioned in pixel space.

