doc/core_common.txt

   1 Common code in Core
   2 -------------------
   3
   4 NOTE: Some of the interfaces described here (most notably the allocator) are
   5       semi-internal interfaces and as such API is not considered stable.
   6
   7 Common Macros and Inline Functions
   8 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   9
  10 [source,c]
  11 -------------------------------------------------------------------------------
  12 #include <core/GP_Common.h>
  13 /* or */
  14 #include <GP.h>
  15
  16 GP_MIN(a, b);
  17
  18 GP_MAX(a, b);
  19
  20 GP_MAX3(a, b, c);
  21
  22 GP_ABS(a);
  23
  24 GP_SWAP(a, b);
  25
  26 GP_SIGN(a);
  27
  28 GP_ARRAY_SIZE(arr);
  29
  30 GP_CONTAINER_OF(ptr, structure, member);
  31
  32 -------------------------------------------------------------------------------
  33
  34 These common macros implements basic functions such as minimum, maximum,
  35 absolute value, swap and sign.
  36
  37 All macros use 'typeof()' in order to evaluate their arguments exactly once.
  38
  39 The 'GP_ARRAY_SIZE()' macro computes size of statically defined array (i.e.
  40 returns +sizeof(array) / sizeof(elem)+).
  41
  42 The 'GP_CONTAINER_OF()' macro computes pointer to a structure given pointer to
  43 its member.
  44
  45 [source,c]
  46 -------------------------------------------------------------------------------
  47 #include <core/GP_Clamp.h>
  48
  49 /*
  50  * Clamps integer value to 8 bit unsigned value.
  51  */
  52 GP_CLAMP_INT_0_255(val);
  53
  54 /*
  55  * Clamps integer value.
  56  */
  57 GP_CLAMP(val, min, max);
  58
  59 -------------------------------------------------------------------------------
  60
  61 Value clamping macros.
  62
  63 NOTE: this header is not included by including the 'GP.h' header.
  64
  65 Temporary Buffer Allocator
  66 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  67
  68 Temporary buffer allocator is used to allocate temporary buffer needed for
  69 certain operations (mostly used in image filters).
  70
  71 The intended usage of temporary buffers is:
  72
  73 * Count sum of the size needed for all buffers
  74 * Allocate temporary buffer of this size
  75 * Partition the buffer into smaller blocks
  76 * Use the blocks as needed
  77 * Once operation is done, free the buffer
  78
  79 The allocator code greatly simplifies these steps. Moreover it avoids memory
  80 fragmentation by creating small buffers on the process stack (current theshold
  81 is set to 2kB) and by grouping the temporary buffers into one continuous
  82 region.
  83
  84 NOTE: The allocator itself does not align the resulting blocks. It's your
  85       responsibility to allocate the buffers in a way that the result is
  86       adequately aligned (hint: the start of the block is aligned, so
  87       get blocks that needs to be aligned first).
  88
  89 [source,c]
  90 -------------------------------------------------------------------------------
  91 #include <core/GP_TempAlloc.h>
  92
  93 /*
  94  * A macro that creates block allocator.
  95  *
  96  * The name must be unique among variable and functions names.
  97  *
  98  * The bsize is actual size of the block allocated.
  99  */
 100 GP_TempAllocCreate(name, bsize);
 101
 102 /*
 103  * A macro that returns pointer to the start of a block of a bsize
 104  * partioned from the block allocator passed as self argument.
 105  */
 106 GP_TempAllocGet(self, bsize);
 107
 108 /*
 109  * Free the allocator memory.
 110  */
 111 GP_TempAllocFree(self);
 112 -------------------------------------------------------------------------------
 113
 114 Example usage of the allocator:
 115
 116 [source,c]
 117 -------------------------------------------------------------------------------
 118 #include <core/GP_TempAlloc.h>
 119
 120 int foo(...)
 121 {
 122         GP_TempAllocCreate(tmp, 3 * img->width);
 123
 124         uint8_t *R = GP_TempAllocGet(tmp, img->width);
 125         uint8_t *G = GP_TempAllocGet(tmp, img->width);
 126         uint8_t *B = GP_TempAllocGet(tmp, img->width);
 127
 128         /* start of the code that uses the buffers */
 129
 130         ...
 131
 132         if (error) {
 133                 GP_TempAllocFree(tmp);
 134                 return -1;
 135         }
 136
 137         ...
 138
 139         /* end of the code that uses the buffers */
 140
 141         GP_TempAllocFree(tmp);
 142
 143         return 0;
 144 }
 145 -------------------------------------------------------------------------------
 146