freetype2/docs/convntns.txt

          Conventions and Design in the FreeType 2 library
          ------------------------------------------------


Table of Contents

Introduction

I. Style and Formatting

  1. Naming
  2. Declarations & Statements
  3. Blocks
  4. Macros
  5. Conventions

II. Design conventions

  1. Modularity and Components Layout
  2. Configuration and Debugging

III. Usage conventions

  1. Error handling
  2. Font File I/O
  3. Memory management
  4. Support for threaded environments
  5. Object Management



Introduction
============

This text introduces the many conventions used within the FreeType 2
library  code.  Please read  it before  trying any  modifications or
extensions of the source code.



I. Style and Formatting
=======================

The  following coding  rules  are extremely  important  to keep  the
library's  source code  homogeneously.  Keep  in mind  the following
points:

  - `Humans read source code, not machines' (Donald Knuth)

    The library source code should  be as readable as possible, even
    by non-C experts.  With `readable', two things are meant: First,
    the source code  should be pleasant to the  eye, with sufficient
    whitespace  and newlines,  to not  look like  a boring  stack of
    characters stuck  to each other.   Second, the source  should be
    _expressive_ enough  about its goals.   This convention contains
    rules that  can help the source  focus on its purpose,  not on a
    particular implementation.

  - `Paper is the _ultimate_ debugger' (David Turner :-)

    There is  nothing like  sheets of paper  (and a large  floor) to
    help you understand the design of a library you're new to, or to
    debug it.   The formatting style  presented here is  targeted at
    printing.  For  example, it is  more than highly  recommended to
    never produce a source line that is wider than 78 columns.  More
    on this below.


1. Naming
---------

  a. Long and expressive labels

    Never  hesitate to use  long labels  for your  types, variables,
    etc.!   Except maybe  for things  like very  trivial  types, the
    longest   is   the   best,   as  it   increases   the   source's
    _expressiveness_.  Never forget  that the role of a  label is to
    express  the `function'  of the  entity it  represents,  not its
    implementation!

    NOTE: Hungarian  notation is  NOT expressive,  as it  sticks the
          `type' of  a variable to  its name.  A label  like `usFoo'
          rarely tells the use of the variable it represents.

          And  the state  of  a variable  (global, static,  dynamic)
          isn't helpful anymore.

    Conclusion: Avoid Hungarian Notation in FreeType 2.


    When     forging      a     name     with      several     nouns
    (e.g. `number-of-points'), use an uppercase letter for the first
    letter of each word (except the first), like:

      numberOfPoints

    You  are  also welcome  to  introduce  underscores  `_' in  your
    labels,  especially when  sticking large  nouns together,  as it
    `airs' the code greatly.  E.g.:

      `numberOfPoints' or `number_Of_Points'

      `IncredibleFunction' or `Incredible_Function'
       
    And finally,  always put a  capital letter after  an underscore,
    except in variable labels that are all lowercase:

     `number_of_points' is OK for a variable (_all_ lowercase label)

     `incredible_function' is NOT for a function!
      ^          ^

     `Microsoft_windows' is a *shame*!
      ^         ^

     `Microsoft_Windows' isn't  really better,  but at  least  its a
      ^         ^        correct   function    label   within   this
                         convention ;-)

  b. Data types

    Try  to use  C  types to  the  very least!   Rely on  internally
    defined  equivalent   types  instead.   For   example,  not  all
    compilers  agree on the  sign of  `char'; the  size of  `int' is
    platform-specific, etc.

    There  are   equivalents  to  the  most  common   types  in  the
    `fttypes.h'  public header  file, like  `FT_Short', `FT_UShort',
    etc.   Using the internal  types will  guarantee that  you won't
    need  to replace  every occurence  of `short'  or  whatever when
    compiling  on a  weird platform  or with  a weird  compiler, and
    there are many more than you could think of...

  c. Functions

    The  name of  a  function  should always  begin  with a  capital
    letter, as  lowercase first letters are  reserved for variables.
    The name  of a function  should be, again,  _expressive_!  Never
    hesitate to put  long function names in your  code: It will make
    the code much more readable.

    Expressiveness doesn't necessarily imply lengthiness though; for
    instance,  reading various  data  types from  a  file stream  is
    performed   using  the  following   functions  defined   in  the
    `ftstream.c' file of the `base' module:

      FT_Get_Char(), FT_Get_Short(), FT_Get_Long(), etc.

    Which is somewhat more readable than:

      cget, sget, usget, lget, etc.

  d. Variables

    Variable names (at least  meant for the public interface) should
    always begin  with a lowercase letter.   Lowercase first letters
    are reserved  for variables in  this convention, as it  has been
    already explained above.  You are  still welcome to use long and
    expressive variable names.

    Something  like `numP' can  express a  number of  pixels, porks,
    pancakes, and much more...  Something like `num_points' won't.

    Unfortunately (mostly  due to  the lazyness of  the developers),
    short  variable  names are  still  used  in  many parts  of  the
    library.  Volunteers are highly welcome to improve this...

    As a side note, a field name of a structure counts as a variable
    name  too.


2. Declarations & Statements
----------------------------

  Try to align declarations and assignments in columns, if it proves
  logically.  For example (taken from `ttraster.c'):

    struct  TProfile_
    {
      FT_F26Dot6  X;      /* current coordinate during sweep        */
      PProfile    link;   /* link to next profile - various purpose */
      PLong       offset; /* start of profile's data in render pool */
      Int         flow;   /* profile orientation: asc/descending    */
      Long        height; /* profile's height in scanlines          */
      Long        start;  /* profile's starting scanline            */

      UShort      countL; /* number of lines to step before this    */
                          /* profile becomes drawable               */

      PProfile    next;   /* next profile in same contour, used     */
                          /* during drop-out control                */
    };
 
  instead of

    struct  TProfile_
    {
      FT_F26Dot6 X;  /* current coordinate during sweep        */
      PProfile link; /* link to next profile - various purpose */
      PLong offset;  /* start of profile's data in render pool */
      Int flow;      /* profile orientation: asc/descending    */
      Long height;   /* profile's height in scanlines          */
      Long start;    /* profile's starting scanline            */
      UShort countL; /* number of lines to step before this    */
                     /* profile becomes drawable               */
      PProfile next; /* next profile in same contour, used     */
                     /* during drop-out control                */
    };
 
  This comes from the fact that you are more interested in the field
  and its function than in its type.

  Or:

    x   = i + 1;
    y  += j;
    min = 100;

  instead of

    x=i+1;
    y+=j;
    min=100;

  And  don't  hesitate  to  separate  blocks  of  declarations  with
  newlines to `distinguish' logical sections.

  E.g., taken  from an old source  file, in the  declarations of the
  CMap loader:

    long             n, num_SH;
    unsigned short   u;
    long             off;
    unsigned short   l;
    long             num_Seg;
    unsigned short*  glArray;
    long             table_start;
    int              limit, i;

    TCMapDir         cmap_dir;
    TCMapDirEntry    entry_;
    PCMapTable       Plcmt;
    PCMap2SubHeader  Plcmsub;
    PCMap4           Plcm4;
    PCMap4Segment    segments;

  instead of

    long n, num_SH;
    unsigned short u;
    long off;
    unsigned short l;
    long num_Seg;
    unsigned short *glArray;
    long table_start;
    int limit, i;
    TCMapDir cmap_dir;
    TCMapDirEntry entry_;
    PCMapTable Plcmt;
    PCMap2SubHeader Plcmsub;
    PCMap4 Plcm4;
    PCMap4Segment segments;


3. Blocks
---------

  Block separation is done with `{'  and `}'.  We do not use the K&R
  convention  which becomes  only useful  with an  extensive  use of
  tabs.  The `{'  and its corresponding `}' should  always be on the
  same column.  It makes it easier to separate a block from the rest
  of the source,  and it helps your _brain_  associate the accolades
  easily (ask any Lisp programmer on the topic!).
  
  Use two spaces for the next indentation level.

  Never  use tabs in  FreeType 2  code; their  widths may  vary with
  editors and systems.

  Example:

    if (condition_test) {
            waow mamma;
            I'm doing K&R format;
            just like the Linux kernel;
    } else {
            This test failed poorly;
    }

  should be rather formatted as

    if ( condition_test )
    {
      This code isn't stuck to the condition;
      read it on paper, you will find it more;
      pleasant to the eye;
    }
    else
    {
       Of course, this is a matter of taste;
       This is just the way it is in this convention;
       and you should follow it to be homogenuous with;
       the rest of the FreeType code;
    }


4. Macros
---------

  Macros should be  made of uppercase letters.  If  a macro label is
  forged from several words, it  is possible to only uppercasify the
  first word,  using an underscore  to separate the nouns.   This is
  used in in some files for macros like

    GET_UShort(), USE_Stream(), etc.

  The role of  macros used throughout the engine  is explained later
  in this document.


5. Conventions
--------------

  Currently, FreeType  2 source  code uses the  following formatting
  rules:

  . The  data type is separated  with two spaces  from the variable,
    structure, or function name:

      const char  foo;

    Usually, the `*' operator is concatenated to the data type:

      FT_Int*  pointer;

    As  mentioned   above,  multiple  declarations   are  vertically
    aligned:

      FT_Short      foo;
      FT_Long       bar;
      FT_GlyphSlot  slot;

  . Declarations  are  separated  with  two  blank  lines  from  the
    following code.   This intentionally  disturbs the code  flow to
    make variable definitions more visible.

      {
        char  x, y;


        x = 3;
        y = 5;
      }

  . An  opening  parenthesis  follows  a function  directly  without
    space; after a built-in C keyword, one space is used:

      x = sin( y );
      y = sizeof ( long );

    Except for casts, parentheses are surrounded with space:

      x = (char*)( foo + bar );

  . Binary operators are surrounded by spaces; unary operators have
    no space after it:

      x =  ( 3 + 4 ) / ( 7 - 2 );
      y = -( 3 + 4 ) * 7;

  . Array arguments are not surrounded by spaces:

      array[3] = array[1] + array[2];
      array[4] = array[1 + 3];

  . Comma and semicolon have only space at the right side:

      if ( x = 0; x < y; x++, y-- )
        do_something();

  . Don't use

      if ( x == y ) a = b;

    but

      if ( x == y )
        a = b;

    in general.

  . Preprocessor  directives are never indented and  always start in
    the first column.

  . All  function/structure/variable  definitions  start  at  column
    three.

  . All  full-line comments (except the  header of a  file) start at
    column three (even comments for preprocessor directives).

  . Labels are sticking out two positions to the left:

      switch ( x )
      {
      case 1:
        do_something();
        break;
      default:
        do_nothing();
        break;
      }



II. Design Conventions
======================


1. Modularity and Components Layout
-----------------------------------

  The FreeType 2 engine has  been designed with portability in mind.
  This implies the ability to compile  and run it on a great variety
  of systems and weird  environments, unlike many packages where the
  word strictly  means `runs on  a bunch of Unix-like  systems'.  We
  have thus decided to stick to the following restrictions:

  - The C version is written  entirely in ANSI C.
  
  - The library,  if compiled with gcc, doesn't  produce any warning
    with the  `-ansi -pedantic' flags.  Other  compilers with better
    checks  may produce  ANSI warnings -- please report.
     
    (NOTE: It can of course  be compiled by an `average' C compiler,
           and even by a C++ one.)

  - It only requires  in its simplest form an  ANSI libc to compile,
    and  no utilities  other than  a C  preprocessor,  compiler, and
    linker.

  - It  consists of  modules, starting  with a  `base'  module which
    provides  the  API, some  auxiliary  modules  used  by the  font
    drivers,  the font  driver  modules itself,  and the  rasterizer
    modules.

  - The  very  low-level  components   can  be  easily  replaced  by
    system-specific  ones that  do not  rely on  the  standard libc.
    These  components  deal  mainly  with  i/o,  memory,  and  mutex
    operations.

  - A client application only needs to include one header file named
    `freetype.h' to use the  engine.  Other public header files like
    `ftglyph.h' or `ftimage.h' provide functional extensions.

  - All   configuration   options  are   gathered   in  two   files,
    `ftconfig.h'   and  `ftoption.h'.    The  former   contains  the
    processor  and  OS  specific  configuration options,  while  the
    latter treats  options that  may be enabled  or disabled  by the
    user to enable and disable various features.


2. Configuration and Debugging
------------------------------

  Configuration is covered by the `BUILD' documentation file.

  Debugging   is   controlled  by   two   macros  in   `ftoption.h',
  FT_DEBUG_LEVEL_ERROR and  FT_DEBUG_LEVEL_TRACE; don't use  them in
  code  to be  released.  Check  the source  code of  the `ftview.c'
  demonstration program (in the  `ft2demos' package) how tracing can
  be used and activated.



III. Usage conventions
======================


1. Error Handling
-----------------

  Most functions directly return an error code.  A return value of 0
  (FT_Err_Ok) means  that no error  occured, while a  non-zero other
  value indicates a failure of any kind.

  We use code like this in FreeType 2:

    if ( ( rc = Perform_Action_1( parms_of_1 ) ) ||
         ( rc = Perform_Action_2( parms_of_2 ) ) ||
         ( rc = Perform_Action_3( parms_of_3 ) ) )
      goto Fail;

  which is better but uses assignments within expressions, which are
  always  delicate to  manipulate in  C  (the risk  of writing  `=='
  exists,  and would  go unnoticed  by a  compiler).   Moreover, the
  assignments  are a  bit redundant  and don't  express  much things
  about  the  actions  performed  (they  only  speak  of  the  error
  management issue).

  That is why some macros  have been defined for the most frequently
  used functions.  They relate to low-level routines that are called
  very often (mainly i/o and memory handling functions).  Each macro
  produces an  implicit assignment to a variable  called `error' and
  can be used instead as a simple function call.  Example:

    if ( PERFORM_Action_1( parms_of_1 ) ||
         PERFORM_Action_2( parms_of_2 ) ||
         PERFORM_Action_3( parms_of_3 ) )
      goto Fail;

  with
      
    #define PERFORM_Action_1( parms_1 ) \
              ( error = Perform_Action_1( parms_1 ) )
    #define PERFORM_Action_2( parms_1 ) \
              ( error = Perform_Action_2( parms_1 ) )
    #define PERFORM_Action_3( parms_1 ) \
              ( error = Perform_Action_3( parms_1 ) )

  defined in some header file.

  There, the developer only needs to define a local `error' variable
  and use the macros directly  in the code, without caring about the
  actual error  handling performed.   Another advantage is  that the
  structure  of source files  remain very  similar, even  though the
  error handling may be different.
    
  This  convention  is  very  close  to the  use  of  exceptions  in
  languages  like  C++,  Pascal,  Java, etc.   where  the  developer
  focuses on the  actions to perform, and not  on every little error
  checking.


2. Font File I/O
----------------

  a. Streams

    The engine uses `streams' to access the font files.  A stream is
    a structure containing information  used to access files through
    a system-specific i/o library.

    The  default implementation of  streams uses  the ANSI  libc i/o
    functions.  However, for the  sake of embedding in light systems
    and  independence of  a complete  C library,  it is  possible to
    re-implement the component for  a specific system or OS, letting
    it use system calls.
    
  b. Frames

    TrueType is  tied to the  big-endian format, which  implies that
    reading shorts or longs from  the font file may need conversions
    depending on the target processor.   To be able to easily detect
    read  errors and allow  simple conversion  calls or  macros, the
    engine is able to access a font file using `frames'.

    A frame is simply a  sequence of successive bytes taken from the
    input file at the current  position.  A frame is pre-loaded into
    memory by a call to the `ACCESS_Frame()' macro.

    It  is then  possible  to read  all  sizes of  data through  the
    `GET_xxx()' macros described above.

    When all important data is read,  the frame can be released by a
    call to `FORGET_Frame()'.

    The  benefits  of  frames   are  various.   Consider  these  two
    approaches at extracting values:

      if ( ( error = Read_Short( &var1 ) ) ||
           ( error = Read_Long ( &var2 ) ) ||
           ( error = Read_Long ( &var3 ) ) ||
           ( error = Read_Short( &var4 ) ) )

        return FAILURE;

    and

                            /* Read the next 16 bytes */
      if ( ACCESS_Frame( 16L ) )
        return error;       /* The Frame could not be read */

      var1 = GET_Short();   /* extract values from the frame */
      var2 = GET_Long();
      var3 = GET_Long();
      var4 = GET_Short();

      FORGET_Frame();   /* release the frame */

    In the  first case, there  are four error assignments  with four
    checks of the file  read.  This unnecessarily increases the size
    of the generated  code.  Moreover, you must be  sure that `var1'
    and `var4' are short variables,  `var2' and `var3' long ones, if
    you want to avoid bugs and/or compiler warnings.

    In the second case, you perform only one check for the read, and
    exit immediately on failure.  Then the values are extracted from
    the frame, as the result of function calls.  This means that you
    can  use  automatic type  conversion;  there  is  no problem  if
    e.g. `var1' and `var4' are longs, unlike previously.

    Finally,  frames  are ideal  when  you  are using  memory-mapped
    files, as  the frame is  not really `pre-loaded' and  never uses
    any `heap' space.

    IMPORTANT: You  CANNOT nest  several frame  accesses.   There is
               only  one frame available  at a  time for  a specific
               instance.

               It is  also the programmer's  responsibility to never
               extract more  data than was pre-loaded  in the frame!
               (But  you usually know  how many  values you  want to
               extract from the file before doing so).


3. Memory Management
--------------------

  The library now has a component which uses an interface similar to
  malloc()/free().

  * FT_Alloc()

    To be used like malloc(),  except that it returns an error code,
    not an  address.  Its  arguments are the  size of  the requested
    block  and the  address of  the  target pointer  to the  `fresh'
    block.  An error  code is returned in case  of failure (and this
    will also set the target pointer to NULL), 0 in case of success.

    FT_Alloc() internally  calls the ft_alloc()  function defined in
    an FT_Memory  object.  All error checking is  done by FT_Alloc()
    itself so that ft_alloc() directly calls malloc().

  * FT_Realloc()

    Similar to FT_Alloc(); it calls realloc() by default.

  * FT_Free()

    As  you  may have  already  guessed,  FT_Free() is  FT_Alloc()'s
    counterpart.   It  takes   as  argument  the  _target  pointer's
    address_!  You should _never_ pass the block's address directly,
    i.e. the pointer, to FT_Free().

    Similar  to  FT_Alloc(),  FT_Free()  does  the  necessary  error
    checking and calls free() by default.

  As the pointers addresses  needed as arguments are typed `void**',
  ftmemory.h provides  some macros to  help use the  above functions
  more easily, these are:

    MEM_Alloc()   A  version of FT_Alloc()  that casts  the argument
                  pointer   to  (void**).   Similar   functions  are
                  MEM_Alloc_Array(),        MEM_Realloc(),       and
                  MEM_Realloc_Array()

    ALLOC()       Same as  MEM_Alloc(), but with an  assignment to a
                  variable called  `error'.  See the  section `error
                  handling'  above for more  info on  this.  Similar
                  functions   are   REALLOC(),  ALLOC_ARRAY(),   and
                  REALLOC_ARRAY().

    FREE()        A  version of  FT_Free() that  casts  the argument
                  pointer to (void**).

    MEM_Set()     An  alias  for  `memset()',  which can  be  easily
                  changed  to anything  else if  you wish  to  use a
                  different   memory  manager  than   the  functions
                  provided by the ANSI libc.

    MEM_Copy()    An alias  of `memcpy()' or `bcopy()'  used to move
                  blocks of memory.  You  may change it to something
                  different if necessary (e.g. not using libc).

    MEM_Move()    An alias of `memmove().'  Change its definition if
                  necessary.


4. Support for threaded environments
------------------------------------

  Thread  synchronisation  has  been  dropped in  FreeType  2.   The
  library is already re-entrant, and  if you really need two threads
  accessing  the  same  FT_Library  object, you  should  synchronize
  access to it yourself with a simple mutex.


--- end of convntns.txt ---