libs/gil/doc/naming.rst

   1 Naming Conventions
   2 ==================
   3
   4 Description of established naming conventions used in source code of GIL,
   5 tests and examples.
   6
   7 Concrete Types
   8 --------------
   9
  10 Concrete (non-generic) GIL types follow this naming convention::
  11
  12   ColorSpace + BitDepth + [f | s]+ [c] + [_planar] + [_step] + ClassType + _t
  13
  14 where:
  15
  16 - ``ColorSpace`` indicates layout and ordering of components.
  17   For example, ``rgb``, ``bgr``, ``cmyk``, ``rgba``.
  18
  19 - ``BitDepth`` indicates the bit depth of the color channel.
  20   For example, ``8``,``16``,``32``.
  21
  22 - By default, type of channel is unsigned integral.
  23   The ``s`` tag indicates signed integral.
  24   The ``f`` tag indicates a floating point type, which is always signed.
  25
  26 - By default, objects operate on mutable pixels.
  27   The ``c`` tag indicates object operating over immutable pixels.
  28
  29 - ``_planar`` indicates planar organization (as opposed to interleaved).
  30
  31 - ``_step`` indicates special image views, locators and iterators which
  32   traverse the data in non-trivial way. For example, backwards or every other
  33   pixel.
  34
  35 - ``ClassType`` is ``_image`` (image), ``_view`` (image view), ``_loc`` (pixel
  36   2D locator) ``_ptr`` (pixel iterator), ``_ref`` (pixel reference),
  37   ``_pixel`` (pixel value).
  38
  39 - ``_t`` suffix indicaes it is a name of a type.
  40
  41 For example:
  42
  43 .. code-block:: cpp
  44
  45   bgr8_image_t             a;    // 8-bit interleaved BGR image
  46   cmyk16_pixel_t           b;    // 16-bit CMYK pixel value;
  47   cmyk16c_planar_ref_t     c(b); // const reference to a 16-bit planar CMYK pixel.
  48   rgb32f_planar_step_ptr_t d;    // step pointer to a 32-bit planar RGB pixel.