tor-browser

ftbitmap.h (9051B)

---

/****************************************************************************
*
* ftbitmap.h
*
*   FreeType utility functions for bitmaps (specification).
*
* Copyright (C) 2004-2025 by
* David Turner, Robert Wilhelm, and Werner Lemberg.
*
* This file is part of the FreeType project, and may only be used,
* modified, and distributed under the terms of the FreeType project
* license, LICENSE.TXT.  By continuing to use, modify, or distribute
* this file you indicate that you have read the license and
* understand and accept it fully.
*
*/


#ifndef FTBITMAP_H_
#define FTBITMAP_H_


#include <freetype/freetype.h>
#include <freetype/ftcolor.h>

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif


FT_BEGIN_HEADER


 /**************************************************************************
  *
  * @section:
  *   bitmap_handling
  *
  * @title:
  *   Bitmap Handling
  *
  * @abstract:
  *   Handling FT_Bitmap objects.
  *
  * @description:
  *   This section contains functions for handling @FT_Bitmap objects,
  *   automatically adjusting the target's bitmap buffer size as needed.
  *
  *   Note that none of the functions changes the bitmap's 'flow' (as
  *   indicated by the sign of the `pitch` field in @FT_Bitmap).
  *
  *   To set the flow, assign an appropriate positive or negative value to
  *   the `pitch` field of the target @FT_Bitmap object after calling
  *   @FT_Bitmap_Init but before calling any of the other functions
  *   described here.
  */


 /**************************************************************************
  *
  * @function:
  *   FT_Bitmap_Init
  *
  * @description:
  *   Initialize a pointer to an @FT_Bitmap structure.
  *
  * @inout:
  *   abitmap ::
  *     A pointer to the bitmap structure.
  *
  * @note:
  *   A deprecated name for the same function is `FT_Bitmap_New`.
  */
 FT_EXPORT( void )
 FT_Bitmap_Init( FT_Bitmap  *abitmap );


 /* deprecated */
 FT_EXPORT( void )
 FT_Bitmap_New( FT_Bitmap  *abitmap );


 /**************************************************************************
  *
  * @function:
  *   FT_Bitmap_Copy
  *
  * @description:
  *   Copy a bitmap into another one.
  *
  * @input:
  *   library ::
  *     A handle to a library object.
  *
  *   source ::
  *     A handle to the source bitmap.
  *
  * @output:
  *   target ::
  *     A handle to the target bitmap.
  *
  * @return:
  *   FreeType error code.  0~means success.
  *
  * @note:
  *   `source->buffer` and `target->buffer` must neither be equal nor
  *   overlap.
  */
 FT_EXPORT( FT_Error )
 FT_Bitmap_Copy( FT_Library        library,
                 const FT_Bitmap  *source,
                 FT_Bitmap        *target );


 /**************************************************************************
  *
  * @function:
  *   FT_Bitmap_Embolden
  *
  * @description:
  *   Embolden a bitmap.  The new bitmap will be about `xStrength` pixels
  *   wider and `yStrength` pixels higher.  The left and bottom borders are
  *   kept unchanged.
  *
  * @input:
  *   library ::
  *     A handle to a library object.
  *
  *   xStrength ::
  *     How strong the glyph is emboldened horizontally.  Expressed in 26.6
  *     pixel format.
  *
  *   yStrength ::
  *     How strong the glyph is emboldened vertically.  Expressed in 26.6
  *     pixel format.
  *
  * @inout:
  *   bitmap ::
  *     A handle to the target bitmap.
  *
  * @return:
  *   FreeType error code.  0~means success.
  *
  * @note:
  *   The current implementation restricts `xStrength` to be less than or
  *   equal to~8 if bitmap is of pixel_mode @FT_PIXEL_MODE_MONO.
  *
  *   If you want to embolden the bitmap owned by a @FT_GlyphSlotRec, you
  *   should call @FT_GlyphSlot_Own_Bitmap on the slot first.
  *
  *   Bitmaps in @FT_PIXEL_MODE_GRAY2 and @FT_PIXEL_MODE_GRAY@ format are
  *   converted to @FT_PIXEL_MODE_GRAY format (i.e., 8bpp).
  */
 FT_EXPORT( FT_Error )
 FT_Bitmap_Embolden( FT_Library  library,
                     FT_Bitmap*  bitmap,
                     FT_Pos      xStrength,
                     FT_Pos      yStrength );


 /**************************************************************************
  *
  * @function:
  *   FT_Bitmap_Convert
  *
  * @description:
  *   Convert a bitmap object with depth 1bpp, 2bpp, 4bpp, 8bpp or 32bpp to
  *   a bitmap object with depth 8bpp, making the number of used bytes per
  *   line (a.k.a. the 'pitch') a multiple of `alignment`.
  *
  * @input:
  *   library ::
  *     A handle to a library object.
  *
  *   source ::
  *     The source bitmap.
  *
  *   alignment ::
  *     The pitch of the bitmap is a multiple of this argument.  Common
  *     values are 1, 2, or 4.
  *
  * @output:
  *   target ::
  *     The target bitmap.
  *
  * @return:
  *   FreeType error code.  0~means success.
  *
  * @note:
  *   It is possible to call @FT_Bitmap_Convert multiple times without
  *   calling @FT_Bitmap_Done (the memory is simply reallocated).
  *
  *   Use @FT_Bitmap_Done to finally remove the bitmap object.
  *
  *   The `library` argument is taken to have access to FreeType's memory
  *   handling functions.
  *
  *   `source->buffer` and `target->buffer` must neither be equal nor
  *   overlap.
  */
 FT_EXPORT( FT_Error )
 FT_Bitmap_Convert( FT_Library        library,
                    const FT_Bitmap  *source,
                    FT_Bitmap        *target,
                    FT_Int            alignment );


 /**************************************************************************
  *
  * @function:
  *   FT_Bitmap_Blend
  *
  * @description:
  *   Blend a bitmap onto another bitmap, using a given color.
  *
  * @input:
  *   library ::
  *     A handle to a library object.
  *
  *   source ::
  *     The source bitmap, which can have any @FT_Pixel_Mode format.
  *
  *   source_offset ::
  *     The offset vector to the upper left corner of the source bitmap in
  *     26.6 pixel format.  It should represent an integer offset; the
  *     function will set the lowest six bits to zero to enforce that.
  *
  *   color ::
  *     The color used to draw `source` onto `target`.
  *
  * @inout:
  *   target ::
  *     A handle to an `FT_Bitmap` object.  It should be either initialized
  *     as empty with a call to @FT_Bitmap_Init, or it should be of type
  *     @FT_PIXEL_MODE_BGRA.
  *
  *   atarget_offset ::
  *     The offset vector to the upper left corner of the target bitmap in
  *     26.6 pixel format.  It should represent an integer offset; the
  *     function will set the lowest six bits to zero to enforce that.
  *
  * @return:
  *   FreeType error code.  0~means success.
  *
  * @note:
  *   This function doesn't perform clipping.
  *
  *   The bitmap in `target` gets allocated or reallocated as needed; the
  *   vector `atarget_offset` is updated accordingly.
  *
  *   In case of allocation or reallocation, the bitmap's pitch is set to
  *   `4 * width`.  Both `source` and `target` must have the same bitmap
  *   flow (as indicated by the sign of the `pitch` field).
  *
  *   `source->buffer` and `target->buffer` must neither be equal nor
  *   overlap.
  *
  * @since:
  *   2.10
  */
 FT_EXPORT( FT_Error )
 FT_Bitmap_Blend( FT_Library         library,
                  const FT_Bitmap*   source,
                  const FT_Vector    source_offset,
                  FT_Bitmap*         target,
                  FT_Vector         *atarget_offset,
                  FT_Color           color );


 /**************************************************************************
  *
  * @function:
  *   FT_GlyphSlot_Own_Bitmap
  *
  * @description:
  *   Make sure that a glyph slot owns `slot->bitmap`.
  *
  * @input:
  *   slot ::
  *     The glyph slot.
  *
  * @return:
  *   FreeType error code.  0~means success.
  *
  * @note:
  *   This function is to be used in combination with @FT_Bitmap_Embolden.
  */
 FT_EXPORT( FT_Error )
 FT_GlyphSlot_Own_Bitmap( FT_GlyphSlot  slot );


 /**************************************************************************
  *
  * @function:
  *   FT_Bitmap_Done
  *
  * @description:
  *   Destroy a bitmap object initialized with @FT_Bitmap_Init.
  *
  * @input:
  *   library ::
  *     A handle to a library object.
  *
  *   bitmap ::
  *     The bitmap object to be freed.
  *
  * @return:
  *   FreeType error code.  0~means success.
  *
  * @note:
  *   The `library` argument is taken to have access to FreeType's memory
  *   handling functions.
  */
 FT_EXPORT( FT_Error )
 FT_Bitmap_Done( FT_Library  library,
                 FT_Bitmap  *bitmap );


 /* */


FT_END_HEADER

#endif /* FTBITMAP_H_ */


/* END */