lib/freetype/include/freetype/cache/ftcsbits.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcsbits.h                                                             */
   4 /*                                                                         */
   5 /*    A small-bitmap cache (specification).                                */
   6 /*                                                                         */
   7 /*  Copyright 2000-2001, 2002 by                                           */
   8 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
   9 /*                                                                         */
  10 /*  This file is part of the FreeType project, and may only be used,       */
  11 /*  modified, and distributed under the terms of the FreeType project      */
  12 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  13 /*  this file you indicate that you have read the license and              */
  14 /*  understand and accept it fully.                                        */
  15 /*                                                                         */
  16 /***************************************************************************/
  17
  18
  19 #ifndef __FTCSBITS_H__
  20 #define __FTCSBITS_H__
  21
  22
  23 #include <ft2build.h>
  24 #include FT_CACHE_H
  25 #include FT_CACHE_IMAGE_H
  26
  27
  28 FT_BEGIN_HEADER
  29
  30
  31   /*************************************************************************/
  32   /*                                                                       */
  33   /* <Section>                                                             */
  34   /*    cache_subsystem                                                    */
  35   /*                                                                       */
  36   /*************************************************************************/
  37
  38
  39   /*************************************************************************/
  40   /*                                                                       */
  41   /* <Type>                                                                */
  42   /*    FTC_SBit                                                           */
  43   /*                                                                       */
  44   /* <Description>                                                         */
  45   /*    A handle to a small bitmap descriptor.  See the @FTC_SBitRec       */
  46   /*    structure for details.                                             */
  47   /*                                                                       */
  48   typedef struct FTC_SBitRec_*  FTC_SBit;
  49
  50
  51   /*************************************************************************/
  52   /*                                                                       */
  53   /* <Struct>                                                              */
  54   /*    FTC_SBitRec                                                        */
  55   /*                                                                       */
  56   /* <Description>                                                         */
  57   /*    A very compact structure used to describe a small glyph bitmap.    */
  58   /*                                                                       */
  59   /* <Fields>                                                              */
  60   /*    width     :: The bitmap width in pixels.                           */
  61   /*                                                                       */
  62   /*    height    :: The bitmap height in pixels.                          */
  63   /*                                                                       */
  64   /*    left      :: The horizontal distance from the pen position to the  */
  65   /*                 left bitmap border (a.k.a. `left side bearing', or    */
  66   /*                 `lsb').                                               */
  67   /*                                                                       */
  68   /*    top       :: The vertical distance from the pen position (on the   */
  69   /*                 baseline) to the upper bitmap border (a.k.a. `top     */
  70   /*                 side bearing').  The distance is positive for upwards */
  71   /*                 Y coordinates.                                        */
  72   /*                                                                       */
  73   /*    format    :: The format of the glyph bitmap (monochrome or gray).  */
  74   /*                                                                       */
  75   /*    max_grays :: Maximum gray level value (in the range 1 to 255).     */
  76   /*                                                                       */
  77   /*    pitch     :: The number of bytes per bitmap line.  May be positive */
  78   /*                 or negative.                                          */
  79   /*                                                                       */
  80   /*    xadvance  :: The horizontal advance width in pixels.               */
  81   /*                                                                       */
  82   /*    yadvance  :: The vertical advance height in pixels.                */
  83   /*                                                                       */
  84   /*    buffer   :: A pointer to the bitmap pixels.                        */
  85   /*                                                                       */
  86   typedef struct  FTC_SBitRec_
  87   {
  88     FT_Byte   width;
  89     FT_Byte   height;
  90     FT_Char   left;
  91     FT_Char   top;
  92
  93     FT_Byte   format;
  94     FT_Byte   max_grays;
  95     FT_Short  pitch;
  96     FT_Char   xadvance;
  97     FT_Char   yadvance;
  98
  99     FT_Byte*  buffer;
 100
 101   } FTC_SBitRec;
 102
 103
 104   /*************************************************************************/
 105   /*                                                                       */
 106   /* <Type>                                                                */
 107   /*    FTC_SBitCache                                                      */
 108   /*                                                                       */
 109   /* <Description>                                                         */
 110   /*    A handle to a small bitmap cache.  These are special cache objects */
 111   /*    used to store small glyph bitmaps (and anti-aliased pixmaps) in a  */
 112   /*    much more efficient way than the traditional glyph image cache     */
 113   /*    implemented by @FTC_ImageCache.                                    */
 114   /*                                                                       */
 115   typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;
 116
 117
 118   /*************************************************************************/
 119   /*                                                                       */
 120   /* <Type>                                                                */
 121   /*    FTC_SBit_Cache                                                     */
 122   /*                                                                       */
 123   /* <Description>                                                         */
 124   /*    DEPRECATED.  Use @FTC_SBitCache instead.                           */
 125   /*                                                                       */
 126   typedef FTC_SBitCache  FTC_SBit_Cache;
 127
 128
 129   /*************************************************************************/
 130   /*                                                                       */
 131   /* <Function>                                                            */
 132   /*    FTC_SBitCache_New                                                  */
 133   /*                                                                       */
 134   /* <Description>                                                         */
 135   /*    Creates a new cache to store small glyph bitmaps.                  */
 136   /*                                                                       */
 137   /* <Input>                                                               */
 138   /*    manager :: A handle to the source cache manager.                   */
 139   /*                                                                       */
 140   /* <Output>                                                              */
 141   /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
 142   /*                                                                       */
 143   /* <Return>                                                              */
 144   /*    FreeType error code.  0 means success.                             */
 145   /*                                                                       */
 146   FT_EXPORT( FT_Error )
 147   FTC_SBitCache_New( FTC_Manager     manager,
 148                      FTC_SBitCache  *acache );
 149
 150
 151   /*************************************************************************/
 152   /*                                                                       */
 153   /* <Function>                                                            */
 154   /*    FTC_SBitCache_Lookup                                               */
 155   /*                                                                       */
 156   /* <Description>                                                         */
 157   /*    Looks up a given small glyph bitmap in a given sbit cache and      */
 158   /*    "lock" it to prevent its flushing from the cache until needed      */
 159   /*                                                                       */
 160   /* <Input>                                                               */
 161   /*    cache  :: A handle to the source sbit cache.                       */
 162   /*                                                                       */
 163   /*    type   :: A pointer to the glyph image type descriptor.            */
 164   /*                                                                       */
 165   /*    gindex :: The glyph index.                                         */
 166   /*                                                                       */
 167   /* <Output>                                                              */
 168   /*    sbit   :: A handle to a small bitmap descriptor.                   */
 169   /*                                                                       */
 170   /*    anode  :: Used to return the address of of the corresponding cache */
 171   /*              node after incrementing its reference count (see note    */
 172   /*              below).                                                  */
 173   /*                                                                       */
 174   /* <Return>                                                              */
 175   /*    FreeType error code.  0 means success.                             */
 176   /*                                                                       */
 177   /* <Note>                                                                */
 178   /*    The small bitmap descriptor and its bit buffer are owned by the    */
 179   /*    cache and should never be freed by the application.  They might    */
 180   /*    as well disappear from memory on the next cache lookup, so don't   */
 181   /*    treat them as persistent data.                                     */
 182   /*                                                                       */
 183   /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
 184   /*    glyph bitmap.                                                      */
 185   /*                                                                       */
 186   /*    If "anode" is _not_ NULL, it receives the address of the cache     */
 187   /*    node containing the bitmap, after increasing its reference count.  */
 188   /*    This ensures that the node (as well as the image) will always be   */
 189   /*    kept in the cache until you call @FTC_Node_Unref to "release" it.  */
 190   /*                                                                       */
 191   /*    If "anode" is NULL, the cache node is left unchanged, which means  */
 192   /*    that the bitmap could be flushed out of the cache on the next      */
 193   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
 194   /*    is persistent!                                                     */
 195   /*                                                                       */
 196   FT_EXPORT( FT_Error )
 197   FTC_SBitCache_Lookup( FTC_SBitCache    cache,
 198                         FTC_ImageType    type,
 199                         FT_UInt          gindex,
 200                         FTC_SBit        *sbit,
 201                         FTC_Node        *anode );
 202
 203
 204   /* */
 205
 206
 207   /*************************************************************************/
 208   /*                                                                       */
 209   /* <Function>                                                            */
 210   /*    FTC_SBit_Cache_New                                                 */
 211   /*                                                                       */
 212   /* <Description>                                                         */
 213   /*    DEPRECATED.  Use @FTC_SBitCache_New instead.                       */
 214   /*                                                                       */
 215   /*    Creates a new cache to store small glyph bitmaps.                  */
 216   /*                                                                       */
 217   /* <Input>                                                               */
 218   /*    manager :: A handle to the source cache manager.                   */
 219   /*                                                                       */
 220   /* <Output>                                                              */
 221   /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
 222   /*                                                                       */
 223   /* <Return>                                                              */
 224   /*    FreeType error code.  0 means success.                             */
 225   /*                                                                       */
 226   FT_EXPORT( FT_Error )
 227   FTC_SBit_Cache_New( FTC_Manager      manager,
 228                       FTC_SBit_Cache  *acache );
 229
 230
 231   /*************************************************************************/
 232   /*                                                                       */
 233   /* <Function>                                                            */
 234   /*    FTC_SBit_Cache_Lookup                                              */
 235   /*                                                                       */
 236   /* <Description>                                                         */
 237   /*    DEPRECATED.  Use @FTC_SBitCache_Lookup instead.                    */
 238   /*                                                                       */
 239   /*    Looks up a given small glyph bitmap in a given sbit cache.         */
 240   /*                                                                       */
 241   /* <Input>                                                               */
 242   /*    cache  :: A handle to the source sbit cache.                       */
 243   /*                                                                       */
 244   /*    desc   :: A pointer to the glyph image descriptor.                 */
 245   /*                                                                       */
 246   /*    gindex :: The glyph index.                                         */
 247   /*                                                                       */
 248   /* <Output>                                                              */
 249   /*    sbit   :: A handle to a small bitmap descriptor.                   */
 250   /*                                                                       */
 251   /* <Return>                                                              */
 252   /*    FreeType error code.  0 means success.                             */
 253   /*                                                                       */
 254   /* <Note>                                                                */
 255   /*    The small bitmap descriptor and its bit buffer are owned by the    */
 256   /*    cache and should never be freed by the application.  They might    */
 257   /*    as well disappear from memory on the next cache lookup, so don't   */
 258   /*    treat them as persistent data.                                     */
 259   /*                                                                       */
 260   /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
 261   /*    glyph bitmap.                                                      */
 262   /*                                                                       */
 263   FT_EXPORT( FT_Error )
 264   FTC_SBit_Cache_Lookup( FTC_SBit_Cache   cache,
 265                          FTC_Image_Desc*  desc,
 266                          FT_UInt          gindex,
 267                          FTC_SBit        *sbit );
 268
 269
 270 FT_END_HEADER
 271
 272 #endif /* __FTCSBITS_H__ */
 273
 274
 275 /* END */