include/freetype/ftrender.h

   1 /****************************************************************************
   2  *
   3  * ftrender.h
   4  *
   5  *   FreeType renderer modules public interface (specification).
   6  *
   7  * Copyright (C) 1996-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 FTRENDER_H_
  20 #define FTRENDER_H_
  21
  22
  23 #include <freetype/ftmodapi.h>
  24 #include <freetype/ftglyph.h>
  25
  26
  27 FT_BEGIN_HEADER
  28
  29
  30   /**************************************************************************
  31    *
  32    * @section:
  33    *   module_management
  34    *
  35    */
  36
  37
  38   /* create a new glyph object */
  39   typedef FT_Error
  40   (*FT_Glyph_InitFunc)( FT_Glyph      glyph,
  41                         FT_GlyphSlot  slot );
  42
  43   /* destroys a given glyph object */
  44   typedef void
  45   (*FT_Glyph_DoneFunc)( FT_Glyph  glyph );
  46
  47   typedef void
  48   (*FT_Glyph_TransformFunc)( FT_Glyph          glyph,
  49                              const FT_Matrix*  matrix,
  50                              const FT_Vector*  delta );
  51
  52   typedef void
  53   (*FT_Glyph_GetBBoxFunc)( FT_Glyph  glyph,
  54                            FT_BBox*  abbox );
  55
  56   typedef FT_Error
  57   (*FT_Glyph_CopyFunc)( FT_Glyph   source,
  58                         FT_Glyph   target );
  59
  60   typedef FT_Error
  61   (*FT_Glyph_PrepareFunc)( FT_Glyph      glyph,
  62                            FT_GlyphSlot  slot );
  63
  64 /* deprecated */
  65 #define FT_Glyph_Init_Func       FT_Glyph_InitFunc
  66 #define FT_Glyph_Done_Func       FT_Glyph_DoneFunc
  67 #define FT_Glyph_Transform_Func  FT_Glyph_TransformFunc
  68 #define FT_Glyph_BBox_Func       FT_Glyph_GetBBoxFunc
  69 #define FT_Glyph_Copy_Func       FT_Glyph_CopyFunc
  70 #define FT_Glyph_Prepare_Func    FT_Glyph_PrepareFunc
  71
  72
  73   struct  FT_Glyph_Class_
  74   {
  75     FT_Long                 glyph_size;
  76     FT_Glyph_Format         glyph_format;
  77
  78     FT_Glyph_InitFunc       glyph_init;
  79     FT_Glyph_DoneFunc       glyph_done;
  80     FT_Glyph_CopyFunc       glyph_copy;
  81     FT_Glyph_TransformFunc  glyph_transform;
  82     FT_Glyph_GetBBoxFunc    glyph_bbox;
  83     FT_Glyph_PrepareFunc    glyph_prepare;
  84   };
  85
  86
  87   typedef FT_Error
  88   (*FT_Renderer_RenderFunc)( FT_Renderer       renderer,
  89                              FT_GlyphSlot      slot,
  90                              FT_Render_Mode    mode,
  91                              const FT_Vector*  origin );
  92
  93   typedef FT_Error
  94   (*FT_Renderer_TransformFunc)( FT_Renderer       renderer,
  95                                 FT_GlyphSlot      slot,
  96                                 const FT_Matrix*  matrix,
  97                                 const FT_Vector*  delta );
  98
  99
 100   typedef void
 101   (*FT_Renderer_GetCBoxFunc)( FT_Renderer   renderer,
 102                               FT_GlyphSlot  slot,
 103                               FT_BBox*      cbox );
 104
 105
 106   typedef FT_Error
 107   (*FT_Renderer_SetModeFunc)( FT_Renderer  renderer,
 108                               FT_ULong     mode_tag,
 109                               FT_Pointer   mode_ptr );
 110
 111 /* deprecated identifiers */
 112 #define FTRenderer_render  FT_Renderer_RenderFunc
 113 #define FTRenderer_transform  FT_Renderer_TransformFunc
 114 #define FTRenderer_getCBox  FT_Renderer_GetCBoxFunc
 115 #define FTRenderer_setMode  FT_Renderer_SetModeFunc
 116
 117
 118   /**************************************************************************
 119    *
 120    * @struct:
 121    *   FT_Renderer_Class
 122    *
 123    * @description:
 124    *   The renderer module class descriptor.
 125    *
 126    * @fields:
 127    *   root ::
 128    *     The root @FT_Module_Class fields.
 129    *
 130    *   glyph_format ::
 131    *     The glyph image format this renderer handles.
 132    *
 133    *   render_glyph ::
 134    *     A method used to render the image that is in a given glyph slot into
 135    *     a bitmap.
 136    *
 137    *   transform_glyph ::
 138    *     A method used to transform the image that is in a given glyph slot.
 139    *
 140    *   get_glyph_cbox ::
 141    *     A method used to access the glyph's cbox.
 142    *
 143    *   set_mode ::
 144    *     A method used to pass additional parameters.
 145    *
 146    *   raster_class ::
 147    *     For @FT_GLYPH_FORMAT_OUTLINE renderers only.  This is a pointer to
 148    *     its raster's class.
 149    */
 150   typedef struct  FT_Renderer_Class_
 151   {
 152     FT_Module_Class            root;
 153
 154     FT_Glyph_Format            glyph_format;
 155
 156     FT_Renderer_RenderFunc     render_glyph;
 157     FT_Renderer_TransformFunc  transform_glyph;
 158     FT_Renderer_GetCBoxFunc    get_glyph_cbox;
 159     FT_Renderer_SetModeFunc    set_mode;
 160
 161     FT_Raster_Funcs*           raster_class;
 162
 163   } FT_Renderer_Class;
 164
 165
 166   /**************************************************************************
 167    *
 168    * @function:
 169    *   FT_Get_Renderer
 170    *
 171    * @description:
 172    *   Retrieve the current renderer for a given glyph format.
 173    *
 174    * @input:
 175    *   library ::
 176    *     A handle to the library object.
 177    *
 178    *   format ::
 179    *     The glyph format.
 180    *
 181    * @return:
 182    *   A renderer handle.  0~if none found.
 183    *
 184    * @note:
 185    *   An error will be returned if a module already exists by that name, or
 186    *   if the module requires a version of FreeType that is too great.
 187    *
 188    *   To add a new renderer, simply use @FT_Add_Module.  To retrieve a
 189    *   renderer by its name, use @FT_Get_Module.
 190    */
 191   FT_EXPORT( FT_Renderer )
 192   FT_Get_Renderer( FT_Library       library,
 193                    FT_Glyph_Format  format );
 194
 195
 196   /**************************************************************************
 197    *
 198    * @function:
 199    *   FT_Set_Renderer
 200    *
 201    * @description:
 202    *   Set the current renderer to use, and set additional mode.
 203    *
 204    * @inout:
 205    *   library ::
 206    *     A handle to the library object.
 207    *
 208    * @input:
 209    *   renderer ::
 210    *     A handle to the renderer object.
 211    *
 212    *   num_params ::
 213    *     The number of additional parameters.
 214    *
 215    *   parameters ::
 216    *     Additional parameters.
 217    *
 218    * @return:
 219    *   FreeType error code.  0~means success.
 220    *
 221    * @note:
 222    *   In case of success, the renderer will be used to convert glyph images
 223    *   in the renderer's known format into bitmaps.
 224    *
 225    *   This doesn't change the current renderer for other formats.
 226    *
 227    *   Currently, no FreeType renderer module uses `parameters`; you should
 228    *   thus always pass `NULL` as the value.
 229    */
 230   FT_EXPORT( FT_Error )
 231   FT_Set_Renderer( FT_Library     library,
 232                    FT_Renderer    renderer,
 233                    FT_UInt        num_params,
 234                    FT_Parameter*  parameters );
 235
 236   /* */
 237
 238
 239 FT_END_HEADER
 240
 241 #endif /* FTRENDER_H_ */
 242
 243
 244 /* END */