1 /****************************************************************************
   2  *
   3  * ftbitmap.h
   4  *
   5  *   FreeType utility functions for bitmaps (specification).
   6  *
   7  * Copyright (C) 2004-2019 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 FTBITMAP_H_
  20 #define FTBITMAP_H_
  21 
  22 
  23 #include <ft2build.h>
  24 #include FT_FREETYPE_H
  25 #include FT_COLOR_H
  26 
  27 #ifdef FREETYPE_H
  28 #error "freetype.h of FreeType 1 has been loaded!"
  29 #error "Please fix the directory search order for header files"
  30 #error "so that freetype.h of FreeType 2 is found first."
  31 #endif
  32 
  33 
  34 FT_BEGIN_HEADER
  35 
  36 
  37   /**************************************************************************
  38    *
  39    * @section:
  40    *   bitmap_handling
  41    *
  42    * @title:
  43    *   Bitmap Handling
  44    *
  45    * @abstract:
  46    *   Handling FT_Bitmap objects.
  47    *
  48    * @description:
  49    *   This section contains functions for handling @FT_Bitmap objects,
  50    *   automatically adjusting the target's bitmap buffer size as needed.
  51    *
  52    *   Note that none of the functions changes the bitmap's 'flow' (as
  53    *   indicated by the sign of the `pitch` field in @FT_Bitmap).
  54    *
  55    *   To set the flow, assign an appropriate positive or negative value to
  56    *   the `pitch` field of the target @FT_Bitmap object after calling
  57    *   @FT_Bitmap_Init but before calling any of the other functions
  58    *   described here.
  59    */
  60 
  61 
  62   /**************************************************************************
  63    *
  64    * @function:
  65    *   FT_Bitmap_Init
  66    *
  67    * @description:
  68    *   Initialize a pointer to an @FT_Bitmap structure.
  69    *
  70    * @inout:
  71    *   abitmap ::
  72    *     A pointer to the bitmap structure.
  73    *
  74    * @note:
  75    *   A deprecated name for the same function is `FT_Bitmap_New`.
  76    */
  77   FT_EXPORT( void )
  78   FT_Bitmap_Init( FT_Bitmap  *abitmap );
  79 
  80 
  81   /* deprecated */
  82   FT_EXPORT( void )
  83   FT_Bitmap_New( FT_Bitmap  *abitmap );
  84 
  85 
  86   /**************************************************************************
  87    *
  88    * @function:
  89    *   FT_Bitmap_Copy
  90    *
  91    * @description:
  92    *   Copy a bitmap into another one.
  93    *
  94    * @input:
  95    *   library ::
  96    *     A handle to a library object.
  97    *
  98    *   source ::
  99    *     A handle to the source bitmap.
 100    *
 101    * @output:
 102    *   target ::
 103    *     A handle to the target bitmap.
 104    *
 105    * @return:
 106    *   FreeType error code.  0~means success.
 107    *
 108    * @note:
 109    *   `source->buffer` and `target->buffer` must neither be equal nor
 110    *   overlap.
 111    */
 112   FT_EXPORT( FT_Error )
 113   FT_Bitmap_Copy( FT_Library        library,
 114                   const FT_Bitmap  *source,
 115                   FT_Bitmap        *target );
 116 
 117 
 118   /**************************************************************************
 119    *
 120    * @function:
 121    *   FT_Bitmap_Embolden
 122    *
 123    * @description:
 124    *   Embolden a bitmap.  The new bitmap will be about `xStrength` pixels
 125    *   wider and `yStrength` pixels higher.  The left and bottom borders are
 126    *   kept unchanged.
 127    *
 128    * @input:
 129    *   library ::
 130    *     A handle to a library object.
 131    *
 132    *   xStrength ::
 133    *     How strong the glyph is emboldened horizontally.  Expressed in 26.6
 134    *     pixel format.
 135    *
 136    *   yStrength ::
 137    *     How strong the glyph is emboldened vertically.  Expressed in 26.6
 138    *     pixel format.
 139    *
 140    * @inout:
 141    *   bitmap ::
 142    *     A handle to the target bitmap.
 143    *
 144    * @return:
 145    *   FreeType error code.  0~means success.
 146    *
 147    * @note:
 148    *   The current implementation restricts `xStrength` to be less than or
 149    *   equal to~8 if bitmap is of pixel_mode @FT_PIXEL_MODE_MONO.
 150    *
 151    *   If you want to embolden the bitmap owned by a @FT_GlyphSlotRec, you
 152    *   should call @FT_GlyphSlot_Own_Bitmap on the slot first.
 153    *
 154    *   Bitmaps in @FT_PIXEL_MODE_GRAY2 and @FT_PIXEL_MODE_GRAY@ format are
 155    *   converted to @FT_PIXEL_MODE_GRAY format (i.e., 8bpp).
 156    */
 157   FT_EXPORT( FT_Error )
 158   FT_Bitmap_Embolden( FT_Library  library,
 159                       FT_Bitmap*  bitmap,
 160                       FT_Pos      xStrength,
 161                       FT_Pos      yStrength );
 162 
 163 
 164   /**************************************************************************
 165    *
 166    * @function:
 167    *   FT_Bitmap_Convert
 168    *
 169    * @description:
 170    *   Convert a bitmap object with depth 1bpp, 2bpp, 4bpp, 8bpp or 32bpp to
 171    *   a bitmap object with depth 8bpp, making the number of used bytes per
 172    *   line (a.k.a. the 'pitch') a multiple of `alignment`.
 173    *
 174    * @input:
 175    *   library ::
 176    *     A handle to a library object.
 177    *
 178    *   source ::
 179    *     The source bitmap.
 180    *
 181    *   alignment ::
 182    *     The pitch of the bitmap is a multiple of this argument.  Common
 183    *     values are 1, 2, or 4.
 184    *
 185    * @output:
 186    *   target ::
 187    *     The target bitmap.
 188    *
 189    * @return:
 190    *   FreeType error code.  0~means success.
 191    *
 192    * @note:
 193    *   It is possible to call @FT_Bitmap_Convert multiple times without
 194    *   calling @FT_Bitmap_Done (the memory is simply reallocated).
 195    *
 196    *   Use @FT_Bitmap_Done to finally remove the bitmap object.
 197    *
 198    *   The `library` argument is taken to have access to FreeType's memory
 199    *   handling functions.
 200    *
 201    *   `source->buffer` and `target->buffer` must neither be equal nor
 202    *   overlap.
 203    */
 204   FT_EXPORT( FT_Error )
 205   FT_Bitmap_Convert( FT_Library        library,
 206                      const FT_Bitmap  *source,
 207                      FT_Bitmap        *target,
 208                      FT_Int            alignment );
 209 
 210 
 211   /**************************************************************************
 212    *
 213    * @function:
 214    *   FT_Bitmap_Blend
 215    *
 216    * @description:
 217    *   Blend a bitmap onto another bitmap, using a given color.
 218    *
 219    * @input:
 220    *   library ::
 221    *     A handle to a library object.
 222    *
 223    *   source ::
 224    *     The source bitmap, which can have any @FT_Pixel_Mode format.
 225    *
 226    *   source_offset ::
 227    *     The offset vector to the upper left corner of the source bitmap in
 228    *     26.6 pixel format.  It should represent an integer offset; the
 229    *     function will set the lowest six bits to zero to enforce that.
 230    *
 231    *   color ::
 232    *     The color used to draw `source` onto `target`.
 233    *
 234    * @inout:
 235    *   target ::
 236    *     A handle to an `FT_Bitmap` object.  It should be either initialized
 237    *     as empty with a call to @FT_Bitmap_Init, or it should be of type
 238    *     @FT_PIXEL_MODE_BGRA.
 239    *
 240    *   atarget_offset ::
 241    *     The offset vector to the upper left corner of the target bitmap in
 242    *     26.6 pixel format.  It should represent an integer offset; the
 243    *     function will set the lowest six bits to zero to enforce that.
 244    *
 245    * @return:
 246    *   FreeType error code.  0~means success.
 247    *
 248    * @note:
 249    *   This function doesn't perform clipping.
 250    *
 251    *   The bitmap in `target` gets allocated or reallocated as needed; the
 252    *   vector `atarget_offset` is updated accordingly.
 253    *
 254    *   In case of allocation or reallocation, the bitmap's pitch is set to
 255    *   `4 * width`.  Both `source` and `target` must have the same bitmap
 256    *   flow (as indicated by the sign of the `pitch` field).
 257    *
 258    *   `source->buffer` and `target->buffer` must neither be equal nor
 259    *   overlap.
 260    *
 261    * @since:
 262    *   2.10
 263    */
 264   FT_EXPORT( FT_Error )
 265   FT_Bitmap_Blend( FT_Library         library,
 266                    const FT_Bitmap*   source,
 267                    const FT_Vector    source_offset,
 268                    FT_Bitmap*         target,
 269                    FT_Vector         *atarget_offset,
 270                    FT_Color           color );
 271 
 272 
 273   /**************************************************************************
 274    *
 275    * @function:
 276    *   FT_GlyphSlot_Own_Bitmap
 277    *
 278    * @description:
 279    *   Make sure that a glyph slot owns `slot->bitmap`.
 280    *
 281    * @input:
 282    *   slot ::
 283    *     The glyph slot.
 284    *
 285    * @return:
 286    *   FreeType error code.  0~means success.
 287    *
 288    * @note:
 289    *   This function is to be used in combination with @FT_Bitmap_Embolden.
 290    */
 291   FT_EXPORT( FT_Error )
 292   FT_GlyphSlot_Own_Bitmap( FT_GlyphSlot  slot );
 293 
 294 
 295   /**************************************************************************
 296    *
 297    * @function:
 298    *   FT_Bitmap_Done
 299    *
 300    * @description:
 301    *   Destroy a bitmap object initialized with @FT_Bitmap_Init.
 302    *
 303    * @input:
 304    *   library ::
 305    *     A handle to a library object.
 306    *
 307    *   bitmap ::
 308    *     The bitmap object to be freed.
 309    *
 310    * @return:
 311    *   FreeType error code.  0~means success.
 312    *
 313    * @note:
 314    *   The `library` argument is taken to have access to FreeType's memory
 315    *   handling functions.
 316    */
 317   FT_EXPORT( FT_Error )
 318   FT_Bitmap_Done( FT_Library  library,
 319                   FT_Bitmap  *bitmap );
 320 
 321 
 322   /* */
 323 
 324 
 325 FT_END_HEADER
 326 
 327 #endif /* FTBITMAP_H_ */
 328 
 329 
 330 /* END */