< prev index next >
src/java.desktop/share/native/libfreetype/include/freetype/ftbitmap.h
Print this page
@@ -1,29 +1,30 @@
-/***************************************************************************/
-/* */
-/* ftbitmap.h */
-/* */
-/* FreeType utility functions for bitmaps (specification). */
-/* */
-/* Copyright 2004-2018 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. */
-/* */
-/***************************************************************************/
+/****************************************************************************
+ *
+ * ftbitmap.h
+ *
+ * FreeType utility functions for bitmaps (specification).
+ *
+ * Copyright (C) 2004-2019 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 <ft2build.h>
#include FT_FREETYPE_H
+#include FT_COLOR_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."
@@ -31,201 +32,290 @@
FT_BEGIN_HEADER
- /*************************************************************************/
- /* */
- /* <Section> */
- /* bitmap_handling */
- /* */
- /* <Title> */
- /* Bitmap Handling */
- /* */
- /* <Abstract> */
- /* Handling FT_Bitmap objects. */
- /* */
- /* <Description> */
- /* This section contains functions for handling @FT_Bitmap objects. */
- /* Note that none of the functions changes the bitmap's `flow' (as */
- /* indicated by the sign of the `pitch' field in `FT_Bitmap'). */
- /* */
- /*************************************************************************/
-
-
- /*************************************************************************/
- /* */
- /* <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'. */
- /* */
+ /**************************************************************************
+ *
+ * @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. */
- /* */
+ /**************************************************************************
+ *
+ * @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). */
- /* */
+ /**************************************************************************
+ *
+ * @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 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 */
- /* parameter. 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. */
- /* */
+ /**************************************************************************
+ *
+ * @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_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. */
- /* */
+ /**************************************************************************
+ *
+ * @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. */
- /* */
+ /**************************************************************************
+ *
+ * @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 );
< prev index next >