freetype2/freetype/ftrender.h

0001 /****************************************************************************
0002  *
0003  * ftrender.h
0004  *
0005  *   FreeType renderer modules public interface (specification).
0006  *
0007  * Copyright (C) 1996-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTRENDER_H_
0020 #define FTRENDER_H_
0021
0022
0023 #include <freetype/ftmodapi.h>
0024 #include <freetype/ftglyph.h>
0025
0026
0027 FT_BEGIN_HEADER
0028
0029
0030   /**************************************************************************
0031    *
0032    * @section:
0033    *   module_management
0034    *
0035    */
0036
0037
0038   /* create a new glyph object */
0039   typedef FT_Error
0040   (*FT_Glyph_InitFunc)( FT_Glyph      glyph,
0041                         FT_GlyphSlot  slot );
0042
0043   /* destroys a given glyph object */
0044   typedef void
0045   (*FT_Glyph_DoneFunc)( FT_Glyph  glyph );
0046
0047   typedef void
0048   (*FT_Glyph_TransformFunc)( FT_Glyph          glyph,
0049                              const FT_Matrix*  matrix,
0050                              const FT_Vector*  delta );
0051
0052   typedef void
0053   (*FT_Glyph_GetBBoxFunc)( FT_Glyph  glyph,
0054                            FT_BBox*  abbox );
0055
0056   typedef FT_Error
0057   (*FT_Glyph_CopyFunc)( FT_Glyph   source,
0058                         FT_Glyph   target );
0059
0060   typedef FT_Error
0061   (*FT_Glyph_PrepareFunc)( FT_Glyph      glyph,
0062                            FT_GlyphSlot  slot );
0063
0064 /* deprecated */
0065 #define FT_Glyph_Init_Func       FT_Glyph_InitFunc
0066 #define FT_Glyph_Done_Func       FT_Glyph_DoneFunc
0067 #define FT_Glyph_Transform_Func  FT_Glyph_TransformFunc
0068 #define FT_Glyph_BBox_Func       FT_Glyph_GetBBoxFunc
0069 #define FT_Glyph_Copy_Func       FT_Glyph_CopyFunc
0070 #define FT_Glyph_Prepare_Func    FT_Glyph_PrepareFunc
0071
0072
0073   struct  FT_Glyph_Class_
0074   {
0075     FT_Long                 glyph_size;
0076     FT_Glyph_Format         glyph_format;
0077
0078     FT_Glyph_InitFunc       glyph_init;
0079     FT_Glyph_DoneFunc       glyph_done;
0080     FT_Glyph_CopyFunc       glyph_copy;
0081     FT_Glyph_TransformFunc  glyph_transform;
0082     FT_Glyph_GetBBoxFunc    glyph_bbox;
0083     FT_Glyph_PrepareFunc    glyph_prepare;
0084   };
0085
0086
0087   typedef FT_Error
0088   (*FT_Renderer_RenderFunc)( FT_Renderer       renderer,
0089                              FT_GlyphSlot      slot,
0090                              FT_Render_Mode    mode,
0091                              const FT_Vector*  origin );
0092
0093   typedef FT_Error
0094   (*FT_Renderer_TransformFunc)( FT_Renderer       renderer,
0095                                 FT_GlyphSlot      slot,
0096                                 const FT_Matrix*  matrix,
0097                                 const FT_Vector*  delta );
0098
0099
0100   typedef void
0101   (*FT_Renderer_GetCBoxFunc)( FT_Renderer   renderer,
0102                               FT_GlyphSlot  slot,
0103                               FT_BBox*      cbox );
0104
0105
0106   typedef FT_Error
0107   (*FT_Renderer_SetModeFunc)( FT_Renderer  renderer,
0108                               FT_ULong     mode_tag,
0109                               FT_Pointer   mode_ptr );
0110
0111 /* deprecated identifiers */
0112 #define FTRenderer_render  FT_Renderer_RenderFunc
0113 #define FTRenderer_transform  FT_Renderer_TransformFunc
0114 #define FTRenderer_getCBox  FT_Renderer_GetCBoxFunc
0115 #define FTRenderer_setMode  FT_Renderer_SetModeFunc
0116
0117
0118   /**************************************************************************
0119    *
0120    * @struct:
0121    *   FT_Renderer_Class
0122    *
0123    * @description:
0124    *   The renderer module class descriptor.
0125    *
0126    * @fields:
0127    *   root ::
0128    *     The root @FT_Module_Class fields.
0129    *
0130    *   glyph_format ::
0131    *     The glyph image format this renderer handles.
0132    *
0133    *   render_glyph ::
0134    *     A method used to render the image that is in a given glyph slot into
0135    *     a bitmap.
0136    *
0137    *   transform_glyph ::
0138    *     A method used to transform the image that is in a given glyph slot.
0139    *
0140    *   get_glyph_cbox ::
0141    *     A method used to access the glyph's cbox.
0142    *
0143    *   set_mode ::
0144    *     A method used to pass additional parameters.
0145    *
0146    *   raster_class ::
0147    *     For @FT_GLYPH_FORMAT_OUTLINE renderers only.  This is a pointer to
0148    *     its raster's class.
0149    */
0150   typedef struct  FT_Renderer_Class_
0151   {
0152     FT_Module_Class            root;
0153
0154     FT_Glyph_Format            glyph_format;
0155
0156     FT_Renderer_RenderFunc     render_glyph;
0157     FT_Renderer_TransformFunc  transform_glyph;
0158     FT_Renderer_GetCBoxFunc    get_glyph_cbox;
0159     FT_Renderer_SetModeFunc    set_mode;
0160
0161     const FT_Raster_Funcs*     raster_class;
0162
0163   } FT_Renderer_Class;
0164
0165
0166   /**************************************************************************
0167    *
0168    * @function:
0169    *   FT_Get_Renderer
0170    *
0171    * @description:
0172    *   Retrieve the current renderer for a given glyph format.
0173    *
0174    * @input:
0175    *   library ::
0176    *     A handle to the library object.
0177    *
0178    *   format ::
0179    *     The glyph format.
0180    *
0181    * @return:
0182    *   A renderer handle.  0~if none found.
0183    *
0184    * @note:
0185    *   An error will be returned if a module already exists by that name, or
0186    *   if the module requires a version of FreeType that is too great.
0187    *
0188    *   To add a new renderer, simply use @FT_Add_Module.  To retrieve a
0189    *   renderer by its name, use @FT_Get_Module.
0190    */
0191   FT_EXPORT( FT_Renderer )
0192   FT_Get_Renderer( FT_Library       library,
0193                    FT_Glyph_Format  format );
0194
0195
0196   /**************************************************************************
0197    *
0198    * @function:
0199    *   FT_Set_Renderer
0200    *
0201    * @description:
0202    *   Set the current renderer to use, and set additional mode.
0203    *
0204    * @inout:
0205    *   library ::
0206    *     A handle to the library object.
0207    *
0208    * @input:
0209    *   renderer ::
0210    *     A handle to the renderer object.
0211    *
0212    *   num_params ::
0213    *     The number of additional parameters.
0214    *
0215    *   parameters ::
0216    *     Additional parameters.
0217    *
0218    * @return:
0219    *   FreeType error code.  0~means success.
0220    *
0221    * @note:
0222    *   In case of success, the renderer will be used to convert glyph images
0223    *   in the renderer's known format into bitmaps.
0224    *
0225    *   This doesn't change the current renderer for other formats.
0226    *
0227    *   Currently, no FreeType renderer module uses `parameters`; you should
0228    *   thus always pass `NULL` as the value.
0229    */
0230   FT_EXPORT( FT_Error )
0231   FT_Set_Renderer( FT_Library     library,
0232                    FT_Renderer    renderer,
0233                    FT_UInt        num_params,
0234                    FT_Parameter*  parameters );
0235
0236   /* */
0237
0238
0239 FT_END_HEADER
0240
0241 #endif /* FTRENDER_H_ */
0242
0243
0244 /* END */