include/freetype/ftbitmap.h

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