Skip to content

FreeType » Docs » Support API » Scanline Converter

# Scanline Converter

## Synopsis

A raster or a rasterizer is a scan converter in charge of producing a pixel coverage bitmap that can be used as an alpha channel when compositing a glyph with a background. FreeType comes with two rasterizers: bilevel `raster1` and anti-aliased `smooth` are two separate modules. They are usually called from the high-level `FT_Load_Glyph` or `FT_Render_Glyph` functions and produce the entire coverage bitmap at once, while staying largely invisible to users.

Instead of working with complete coverage bitmaps, it is also possible to intercept consecutive pixel runs on the same scanline with the same coverage, called spans, and process them individually. Only the `smooth` rasterizer permits this when calling `FT_Outline_Render` with `FT_Raster_Params` as described below.

Working with either complete bitmaps or spans it is important to think of them as colorless coverage objects suitable as alpha channels to blend arbitrary colors with a background. For best results, it is recommended to use gamma correction, too.

This section also describes the public API needed to set up alternative `FT_Renderer` modules.

## FT_Span

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef struct  FT_Span_
      {
        unsigned short  x;
        unsigned short  len;
        unsigned char   coverage;

      } FT_Span;

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

#### fields

x | The span's horizontal start position.
len | The span's length in pixels.
coverage | The span color/coverage, ranging from 0 (background) to 255 (foreground).

#### 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 anti-aliased rasterizer produces coverage values from 0 to 255, that is, from completely transparent to completely opaque.

## FT_SpanFunc

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef void
      (*FT_SpanFunc)( int             y,
                      int             count,
                      const FT_Span*  spans,
                      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 pixel spans on each scan line.

#### input

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

#### note

This callback allows client applications to directly render the 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 using alpha compositing. It can also be used for oversampling and averaging.

## FT_Raster_Params

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef struct  FT_Raster_Params_
      {
        const FT_Bitmap*        target;
        const void*             source;
        int                     flags;
        FT_SpanFunc             gray_spans;
        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 parameters used by a raster's render function, passed as an argument to `FT_Outline_Render`.

#### fields

target | The target bitmap.
source | A pointer to the source glyph image (e.g., an `FT_Outline`).
flags | The rendering flags.
gray_spans | The gray span drawing callback.
black_spans | Unused.
bit_test | Unused.
bit_set | Unused.
user | User-supplied data that is passed to each drawing callback.
clip_box | An optional span clipping box expressed in integer pixels (not in 26.6 fixed-point units).

#### note

The `FT_RASTER_FLAG_AA` bit flag must be set in the `flags` to generate an anti-aliased glyph bitmap, otherwise a monochrome bitmap is generated. The `target` should have appropriate pixel mode and its dimensions define the clipping region.

If both `FT_RASTER_FLAG_AA` and `FT_RASTER_FLAG_DIRECT` bit flags are set in `flags`, the raster calls an `FT_SpanFunc` callback `gray_spans` with `user` data as an argument ignoring `target`. This allows direct composition over a pre-existing user surface to perform the span drawing and composition. To optionally clip the spans, set the `FT_RASTER_FLAG_CLIP` flag and `clip_box`. The monochrome raster does not support the direct mode.

The gray-level rasterizer always uses 256 gray levels. If you want fewer gray levels, you have to use `FT_RASTER_FLAG_DIRECT` and reduce the levels in the callback function.

## FT_RASTER_FLAG_XXX

Defined in FT_IMAGE_H (freetype/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
    #define FT_RASTER_FLAG_SDF      0x8

      /* 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 and the output will be clipped to its size. 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. Otherwise, the `clip_box` is effectively set to the bounding box and all spans are generated.
FT_RASTER_FLAG_SDF | This flag is set to indicate that a signed distance field glyph image should be generated. This is only used while rendering with the `FT_RENDER_MODE_SDF` render mode.

## FT_Raster

Defined in FT_IMAGE_H (freetype/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.

#### note

In FreeType 2, all rasters are now encapsulated within specific `FT_Renderer` modules and only used in their context.

## FT_Raster_NewFunc

Defined in FT_IMAGE_H (freetype/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 | A handle to the memory allocator.

#### output

raster | A handle to the new raster object.

#### return

Error code. 0 means success.

#### 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 (freetype/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 | A handle to the raster object.

## FT_Raster_ResetFunc

Defined in FT_IMAGE_H (freetype/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 used to provide an area of memory called the ‘render pool’ available to all registered rasterizers. This was not thread safe, however, and now FreeType never allocates this pool.

This function is called after a new raster object is created.

#### input

raster | A handle to the new raster object.
pool_base | Previously, the address in memory of the render pool. Set this to `NULL`.
pool_size | Previously, the size in bytes of the render pool. Set this to 0.

#### note

Rasterizers should rely on dynamic or stack allocation if they want to (a handle to the memory allocator is passed to the rasterizer constructor).

## FT_Raster_SetModeFunc

Defined in FT_IMAGE_H (freetype/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 | A handle to the new raster object.
mode | A 4-byte tag used to name the mode or property.
args | A pointer to the new mode/property to use.

## FT_Raster_RenderFunc

Defined in FT_IMAGE_H (freetype/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 | A handle to the raster object.
params | A pointer to an `FT_Raster_Params` structure used to store the rendering parameters.

#### return

Error code. 0 means success.

#### 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.

## FT_Raster_Funcs

Defined in FT_IMAGE_H (freetype/ftimage.h).

      typedef struct  FT_Raster_Funcs_
      {
        FT_Glyph_Format        glyph_format;

        FT_Raster_NewFunc      raster_new;
        FT_Raster_ResetFunc    raster_reset;
        FT_Raster_SetModeFunc  raster_set_mode;
        FT_Raster_RenderFunc   raster_render;
        FT_Raster_DoneFunc     raster_done;

      } FT_Raster_Funcs;

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

#### fields

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

## FT_Raster_BitTest_Func

Defined in FT_IMAGE_H (freetype/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 (freetype/ftimage.h).

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

Deprecated, unimplemented.