From 360fe27b55c93c9c6c86895dbbf5db3efc66cc43 Mon Sep 17 00:00:00 2001 From: Mike DePaulo Date: Sat, 28 Feb 2015 07:31:25 -0500 Subject: Updated to freetype 2.5.5 Conflicts: freetype/src/base/ftbdf.c freetype/src/base/fttype1.c freetype/src/pfr/pfrobjs.c --- freetype/docs/reference/ft2-raster.html | 732 ++++++++++++++------------------ 1 file changed, 329 insertions(+), 403 deletions(-) (limited to 'freetype/docs/reference/ft2-raster.html') diff --git a/freetype/docs/reference/ft2-raster.html b/freetype/docs/reference/ft2-raster.html index b94ef6541..3d4062124 100644 --- a/freetype/docs/reference/ft2-raster.html +++ b/freetype/docs/reference/ft2-raster.html @@ -3,81 +3,135 @@ -FreeType-2.5.3 API Reference +FreeType-2.5.5 API Reference - - -

-

FreeType-2.5.3 API Reference

+

+

FreeType-2.5.5 API Reference

-

-Scanline Converter -

+

Scanline Converter

Synopsis

- - - - - - -

	FT_Raster		FT_RASTER_FLAG_XXX		FT_Raster_SetModeFunc
	FT_Span		FT_Raster_Params		FT_Raster_RenderFunc
	FT_SpanFunc		FT_Raster_NewFunc		FT_Raster_Funcs
	FT_Raster_BitTest_Func		FT_Raster_DoneFunc
	FT_Raster_BitSet_Func		FT_Raster_ResetFunc

- -

+ + + + + + + +

FT_Raster		FT_Raster_Funcs
FT_Span	FT_Raster_NewFunc
FT_SpanFunc	FT_Raster_DoneFunc	FT_Raster_BitTest_Func
	FT_Raster_ResetFunc	FT_Raster_BitSet_Func
FT_Raster_Params	FT_Raster_SetModeFunc
FT_RASTER_FLAG_XXX	FT_Raster_RenderFunc

+ +

This section contains technical definitions.

-

-

-

FT_Raster

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+FT_Raster
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef struct FT_RasterRec_*  FT_Raster;
+
+
+An opaque handle (pointer) to a raster object. Each object can be used independently to convert an outline into a bitmap or pixmap.
 
-

-

-

A handle (pointer) to a raster object. Each object can be used independently to convert an outline into a bitmap or pixmap.

-

-

-

- - -

- -

-

FT_Span

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

+
+[Index] [Top] [TOC]
 
+
+FT_Span
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef struct  FT_Span_
   {
     short           x;
@@ -85,42 +139,34 @@ Defined in FT_IMAGE_H (ftimage.h).
     unsigned char   coverage;
 
   } FT_Span;
+
 
-

-

-

A structure used to model a single span of gray (or black) pixels when rendering a monochrome or anti-aliased bitmap.

-

-

fields

-

- -

x

+

A structure used to model a single span of gray pixels when rendering an anti-aliased bitmap.

+ +

fields

+ + - -

x	The span's horizontal start position.
len	+
len	The span's length in pixels.
coverage	- The span color/coverage, ranging from 0 (background) to 255 (foreground). Only used for anti-aliased rendering. +
coverage	+ The span color/coverage, ranging from 0 (background) to 255 (foreground).

-

-

note

+ +

note

This structure is used by the span drawing callback type named FT_SpanFunc that takes the y coordinate of the span as a parameter.

The coverage value is always between 0 and 255. If you want less gray values, the callback function has to reduce them.

-

-

-

- - -

- -

-

FT_SpanFunc

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+[Index] [Top] [TOC]
+
+
+FT_SpanFunc
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef void
   (*FT_SpanFunc)( int             y,
                   int             count,
@@ -128,439 +174,294 @@ Defined in FT_IMAGE_H (ftimage.h).
                   void*           user );
 
 #define FT_Raster_Span_Func  FT_SpanFunc
+
 
-

-

A function used as a call-back by the anti-aliased renderer in order to let client applications draw themselves the gray pixel spans on each scan line.

-

-

input

-

- -

y

+ +

input

+ + - - -

y	The scanline's y coordinate.
count	+
count	The number of spans to draw on this scanline.
spans	+
spans	A table of ‘count’ spans to draw on the scanline.
user	+
user	User-supplied data that is passed to the callback.

-

-

note

+ +

note

This callback allows client applications to directly render the gray spans of the anti-aliased bitmap to any kind of surfaces.

This can be used to write anti-aliased outlines directly to a given background bitmap, and even perform translucency.

Note that the ‘count’ field cannot be greater than a fixed value defined by the ‘FT_MAX_GRAY_SPANS’ configuration macro in ‘ftoption.h’. By default, this value is set to 32, which means that if there are more than 32 spans on a given scanline, the callback is called several times with the same ‘y’ parameter in order to draw all callbacks.

Otherwise, the callback is only called once per scan-line, and only for those scanlines that do have ‘gray’ pixels on them.

-

-

-

- - -

- -

-

FT_Raster_BitTest_Func

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
-  typedef int
-  (*FT_Raster_BitTest_Func)( int    y,
-                             int    x,
-                             void*  user );
-
-

-

-

THIS TYPE IS DEPRECATED. DO NOT USE IT.

-

A function used as a call-back by the monochrome scan-converter to test whether a given target pixel is already set to the drawing ‘color’. These tests are crucial to implement drop-out control per-se the TrueType spec.

-

-

input

-

- - - - -

y	- The pixel's y coordinate. -
x	- The pixel's x coordinate. -
user	- User-supplied data that is passed to the callback. -

-

-

return

-

1 if the pixel is ‘set’, 0 otherwise.

-

-

-

- - -

- -

-

FT_Raster_BitSet_Func

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

-
-  typedef void
-  (*FT_Raster_BitSet_Func)( int    y,
-                            int    x,
-                            void*  user );
-
-

-

-

THIS TYPE IS DEPRECATED. DO NOT USE IT.

-

A function used as a call-back by the monochrome scan-converter to set an individual target pixel. This is crucial to implement drop-out control according to the TrueType specification.

-

-

input

-

- - - - -

y	- The pixel's y coordinate. -
x	- The pixel's x coordinate. -
user	- User-supplied data that is passed to the callback. -

-

-

return

-

1 if the pixel is ‘set’, 0 otherwise.

-

-

-

- - -

- -

-

FT_RASTER_FLAG_XXX

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

-
-#define FT_RASTER_FLAG_DEFAULT  0x0
-#define FT_RASTER_FLAG_AA       0x1
-#define FT_RASTER_FLAG_DIRECT   0x2
-#define FT_RASTER_FLAG_CLIP     0x4
-
-  /* deprecated */
-#define ft_raster_flag_default  FT_RASTER_FLAG_DEFAULT
-#define ft_raster_flag_aa       FT_RASTER_FLAG_AA
-#define ft_raster_flag_direct   FT_RASTER_FLAG_DIRECT
-#define ft_raster_flag_clip     FT_RASTER_FLAG_CLIP
-
-

-

-

A list of bit flag constants as used in the ‘flags’ field of a FT_Raster_Params structure.

-

-

values

-

- - - - - -

FT_RASTER_FLAG_DEFAULT	- This value is 0. -
FT_RASTER_FLAG_AA	- This flag is set to indicate that an anti-aliased glyph image should be generated. Otherwise, it will be monochrome (1-bit). -
FT_RASTER_FLAG_DIRECT	- This flag is set to indicate direct rendering. In this mode, client applications must provide their own span callback. This lets them directly draw or compose over an existing bitmap. If this bit is not set, the target pixmap's buffer must be zeroed before rendering. - Note that for now, direct rendering is only possible with anti-aliased glyphs. -
FT_RASTER_FLAG_CLIP	- This flag is only used in direct rendering mode. If set, the output will be clipped to a box specified in the ‘clip_box’ field of the FT_Raster_Params structure. - Note that by default, the glyph bitmap is clipped to the target pixmap, except in direct rendering mode where all spans are generated if no clipping box is set. -

-

-

-

- - -

- -

-

FT_Raster_Params

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

+
+[Index] [Top] [TOC]
 
+
+FT_Raster_Params
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef struct  FT_Raster_Params_
   {
     const FT_Bitmap*        target;
     const void*             source;
     int                     flags;
     FT_SpanFunc             gray_spans;
-    FT_SpanFunc             black_spans;  /* doesn't work! */
-    FT_Raster_BitTest_Func  bit_test;     /* doesn't work! */
-    FT_Raster_BitSet_Func   bit_set;      /* doesn't work! */
+    FT_SpanFunc             black_spans;  /* unused */
+    FT_Raster_BitTest_Func  bit_test;     /* unused */
+    FT_Raster_BitSet_Func   bit_set;      /* unused */
     void*                   user;
     FT_BBox                 clip_box;
 
   } FT_Raster_Params;
+
 
-

-

A structure to hold the arguments used by a raster's render function.

-

-

fields

-

- -

target

+ +

fields

+ + - - - - - - - -

target	The target bitmap.
source	+
source	A pointer to the source glyph image (e.g., an FT_Outline).
flags	+
flags	The rendering flags.
gray_spans	+
gray_spans	The gray span drawing callback.
black_spans	- The black span drawing callback. UNIMPLEMENTED! +
black_spans	+ Unused.
bit_test	- The bit test callback. UNIMPLEMENTED! +
bit_test	+ Unused.
bit_set	- The bit set callback. UNIMPLEMENTED! +
bit_set	+ Unused.
user	+
user	User-supplied data that is passed to each drawing callback.
clip_box	+
clip_box	An optional clipping box. It is only used in direct rendering mode. Note that coordinates here should be expressed in integer pixels (and not in 26.6 fixed-point units).

-

-

note

+ +

note

An anti-aliased glyph bitmap is drawn if the FT_RASTER_FLAG_AA bit flag is set in the ‘flags’ field, otherwise a monochrome bitmap is generated.

-

If the FT_RASTER_FLAG_DIRECT bit flag is set in ‘flags’, the raster will call the ‘gray_spans’ callback to draw gray pixel spans, in the case of an aa glyph bitmap, it will call ‘black_spans’, and ‘bit_test’ and ‘bit_set’ in the case of a monochrome bitmap. This allows direct composition over a pre-existing bitmap through user-provided callbacks to perform the span drawing/composition.

-

Note that the ‘bit_test’ and ‘bit_set’ callbacks are required when rendering a monochrome bitmap, as they are crucial to implement correct drop-out control as defined in the TrueType specification.

-

-

-

- - -

- -

-

FT_Raster_NewFunc

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

+

If the FT_RASTER_FLAG_DIRECT bit flag is set in ‘flags’, the raster will call the ‘gray_spans’ callback to draw gray pixel spans. This allows direct composition over a pre-existing bitmap through user-provided callbacks to perform the span drawing and composition. Not supported by the monochrome rasterizer.

+ +

+

+ +

+

FT_RASTER_FLAG_XXX

+

Defined in FT_IMAGE_H (ftimage.h).

+

+#define FT_RASTER_FLAG_DEFAULT  0x0
+#define FT_RASTER_FLAG_AA       0x1
+#define FT_RASTER_FLAG_DIRECT   0x2
+#define FT_RASTER_FLAG_CLIP     0x4
+
+  /* these constants are deprecated; use the corresponding */
+  /* `FT_RASTER_FLAG_XXX' values instead                   */
+#define ft_raster_flag_default  FT_RASTER_FLAG_DEFAULT
+#define ft_raster_flag_aa       FT_RASTER_FLAG_AA
+#define ft_raster_flag_direct   FT_RASTER_FLAG_DIRECT
+#define ft_raster_flag_clip     FT_RASTER_FLAG_CLIP
+

+ +

A list of bit flag constants as used in the ‘flags’ field of a FT_Raster_Params structure.

+ +

values

+ + + + + +

FT_RASTER_FLAG_DEFAULT	+ This value is 0. +
FT_RASTER_FLAG_AA	+ This flag is set to indicate that an anti-aliased glyph image should be generated. Otherwise, it will be monochrome (1-bit). +
FT_RASTER_FLAG_DIRECT	+ This flag is set to indicate direct rendering. In this mode, client applications must provide their own span callback. This lets them directly draw or compose over an existing bitmap. If this bit is not set, the target pixmap's buffer must be zeroed before rendering. + Direct rendering is only possible with anti-aliased glyphs. +
FT_RASTER_FLAG_CLIP	+ This flag is only used in direct rendering mode. If set, the output will be clipped to a box specified in the ‘clip_box’ field of the FT_Raster_Params structure. + Note that by default, the glyph bitmap is clipped to the target pixmap, except in direct rendering mode where all spans are generated if no clipping box is set. +

+

+

+ +

+

FT_Raster_NewFunc

+

Defined in FT_IMAGE_H (ftimage.h).

+

   typedef int
   (*FT_Raster_NewFunc)( void*       memory,
                         FT_Raster*  raster );
 
 #define FT_Raster_New_Func  FT_Raster_NewFunc
+

-

-

A function used to create a new raster object.

-

-

input

-

- -

memory

+ +

input

+ +

memory

A handle to the memory allocator.

-

-

output

-

- -

raster

+ +

output

+ +

raster

A handle to the new raster object.

-

-

return

+ +

return

Error code. 0 means success.

-

-

note

+ +

note

The ‘memory’ parameter is a typeless pointer in order to avoid un-wanted dependencies on the rest of the FreeType code. In practice, it is an FT_Memory object, i.e., a handle to the standard FreeType memory allocator. However, this field can be completely ignored by a given raster implementation.

-

-

-

- - -

- -

-

FT_Raster_DoneFunc

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+[Index] [Top] [TOC]
+
+
+FT_Raster_DoneFunc
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef void
   (*FT_Raster_DoneFunc)( FT_Raster  raster );
 
 #define FT_Raster_Done_Func  FT_Raster_DoneFunc
+
 
-

-

A function used to destroy a given raster object.

-

-

input

-

- -

raster

+ +

input

+ +

raster

A handle to the raster object.

-

-

-

- - -

- -

-

FT_Raster_ResetFunc

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+[Index] [Top] [TOC]
+
+
+FT_Raster_ResetFunc
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef void
   (*FT_Raster_ResetFunc)( FT_Raster       raster,
                           unsigned char*  pool_base,
                           unsigned long   pool_size );
 
 #define FT_Raster_Reset_Func  FT_Raster_ResetFunc
+
 
-

-

FreeType provides an area of memory called the ‘render pool’, available to all registered rasters. This pool can be freely used during a given scan-conversion but is shared by all rasters. Its content is thus transient.

This function is called each time the render pool changes, or just after a new raster object is created.

-

-

input

-

- -

raster

+ +

input

+ + - -

raster	A handle to the new raster object.
pool_base	+
pool_base	The address in memory of the render pool.
pool_size	+
pool_size	The size in bytes of the render pool.

-

-

note

+ +

note

Rasters can ignore the render pool and rely on dynamic memory allocation if they want to (a handle to the memory allocator is passed to the raster constructor). However, this is not recommended for efficiency purposes.

-

-

-

- - -

- -

-

FT_Raster_SetModeFunc

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+[Index] [Top] [TOC]
+
+
+FT_Raster_SetModeFunc
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef int
   (*FT_Raster_SetModeFunc)( FT_Raster      raster,
                             unsigned long  mode,
                             void*          args );
 
 #define FT_Raster_Set_Mode_Func  FT_Raster_SetModeFunc
+
 
-

-

This function is a generic facility to change modes or attributes in a given raster. This can be used for debugging purposes, or simply to allow implementation-specific ‘features’ in a given raster module.

-

-

input

-

- -

raster

+ +

input

+ + - -

raster	A handle to the new raster object.
mode	+
mode	A 4-byte tag used to name the mode or property.
args	+
args	A pointer to the new mode/property to use.

-

-

-

- - -

- -

-

FT_Raster_RenderFunc

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+[Index] [Top] [TOC]
+
+
+FT_Raster_RenderFunc
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef int
   (*FT_Raster_RenderFunc)( FT_Raster                raster,
                            const FT_Raster_Params*  params );
 
 #define FT_Raster_Render_Func  FT_Raster_RenderFunc
+
 
-

-

Invoke a given raster to scan-convert a given glyph image into a target bitmap.

-

-

input

-

- -

raster

+ +

input

+ + -

raster	A handle to the raster object.
params	+
params	A pointer to an FT_Raster_Params structure used to store the rendering parameters.

-

-

return

+ +

return

Error code. 0 means success.

-

-

note

+ +

note

The exact format of the source image depends on the raster's glyph format defined in its FT_Raster_Funcs structure. It can be an FT_Outline or anything else in order to support a large array of glyph formats.

Note also that the render function can fail and return a ‘FT_Err_Unimplemented_Feature’ error code if the raster used does not support direct composition.

XXX: For now, the standard raster doesn't support direct composition but this should change for the final release (see the files ‘demos/src/ftgrays.c’ and ‘demos/src/ftgrays2.c’ for examples of distinct implementations that support direct composition).

-

-

-

- - -

- -

-

FT_Raster_Funcs

-

-Defined in FT_IMAGE_H (ftimage.h). -

-

 
+
+[Index] [Top] [TOC]
+
+
+FT_Raster_Funcs
+Defined in FT_IMAGE_H (ftimage.h).
+   typedef struct  FT_Raster_Funcs_
   {
     FT_Glyph_Format        glyph_format;
@@ -571,36 +472,61 @@ Defined in FT_IMAGE_H (ftimage.h).
     FT_Raster_DoneFunc     raster_done;
 
   } FT_Raster_Funcs;
+
 
-

-

A structure used to describe a given raster class to the library.

-

-

fields

-

- -

glyph_format

+ +

fields

+ + - - - -

glyph_format	The supported glyph format for this raster.
raster_new	+
raster_new	The raster constructor.
raster_reset	+
raster_reset	Used to reset the render pool within the raster.
raster_render	+
raster_render	A function to render a glyph into a given bitmap.
raster_done	+
raster_done	The raster destructor.

-

-

-

- - -

+ +

+

+ +

+

FT_Raster_BitTest_Func

+

Defined in FT_IMAGE_H (ftimage.h).

+

+  typedef int
+  (*FT_Raster_BitTest_Func)( int    y,
+                             int    x,
+                             void*  user );
+

+ +

Deprecated, unimplemented.

+ +

+

+ +

+

FT_Raster_BitSet_Func

+

Defined in FT_IMAGE_H (ftimage.h).

+

+  typedef void
+  (*FT_Raster_BitSet_Func)( int    y,
+                            int    x,
+                            void*  user );
+

+ +

Deprecated, unimplemented.

+ +

+

-- cgit v1.2.3