diff --git a/[GSoC]ChangeLog b/[GSoC]ChangeLog index 41eb62b98..135f12fa7 100644 --- a/[GSoC]ChangeLog +++ b/[GSoC]ChangeLog @@ -1,3 +1,10 @@ +2020-08-7 Anuj Verma + + [sdf, bsdf] Added better documentation. + + * src/sdf/ftsdf.c, src/sdf/ftbsdf.c (*): Added documentation + of the structs and enums for both the renderers. + 2020-08-6 Anuj Verma [sdf] Added function to get contour orientation. diff --git a/src/sdf/ftbsdf.c b/src/sdf/ftbsdf.c index 805feea3d..48d1f3d3c 100644 --- a/src/sdf/ftbsdf.c +++ b/src/sdf/ftbsdf.c @@ -22,22 +22,87 @@ * */ + /************************************************************************** + * + * @Struct: + * BSDF_TRaster + * + * @Description: + * This struct is used in place of `FT_Raster' and is stored within + * the internal freetype renderer struct. While rasterizing this is + * passed to the `FT_Raster_Render_Func' function, which then can be + * used however we want. + * + * @Fields: + * memory :: + * Used internally to allocate intermediate memory while raterizing. + * + */ typedef struct BSDF_TRaster_ { - FT_Memory memory; /* used internally to allocate memory */ + FT_Memory memory; } BSDF_TRaster; - /* Euclidean distance used for euclidean distance transform */ - /* can also be interpreted as edge distance. */ + /************************************************************************** + * + * @Struct: + * ED + * + * @Description: + * Euclidean distance used for euclidean distance transform can also be + * interpreted as edge distance. + * + * @Fields: + * dist :: + * Vector length of the `near' parameter. Can be squared or absolute + * depending on the `USE_SQUARED_DISTANCES' parameter defined in + * `ftsdfcommon.h'. + * + * near :: + * Vector to the nearest edge. Can also be interpreted as shortest + * distance of a point. + * + * alpha :: + * Alpha value of the original bitmap from which we generate SDF. + * While computing the gradient and determining the proper sign + * of a pixel this field is used. + * + */ typedef struct ED_ { - FT_16D16 dist; /* distance at `near' */ - FT_16D16_Vec near; /* nearest point */ - FT_Byte alpha; /* alpha of the source */ + FT_16D16 dist; + FT_16D16_Vec near; + FT_Byte alpha; } ED; + /************************************************************************** + * + * @Struct: + * BSDF_Worker + * + * @Description: + * Just a convenient struct which is passed to most of the functions + * while generating SDF. This makes it easier to pass parameters because + * most functions require the same parameters. + * + * @Fields: + * distance_map :: + * A 1D array which is interpreted as 2D array. This array contains + * the Euclidean distance of all the points of the bitmap. + * + * width :: + * Width of the above `distance_map'. + * + * rows :: + * Number of rows in the above `distance_map'. + * + * params :: + * Internal params and properties required by the rasterizer. See + * `ftsdf.h' for the fields of this struct. + * + */ typedef struct BSDF_Worker_ { ED* distance_map; @@ -977,6 +1042,7 @@ * */ + /* called when adding a new module through `FT_Add_Module' */ static FT_Error bsdf_raster_new( FT_Memory memory, FT_Raster* araster) @@ -995,6 +1061,7 @@ return error; } + /* unused */ static void bsdf_raster_reset( FT_Raster raster, unsigned char* pool_base, @@ -1006,6 +1073,7 @@ FT_UNUSED( pool_size ); } + /* unused */ static FT_Error bsdf_raster_set_mode( FT_Raster raster, unsigned long mode, @@ -1019,6 +1087,7 @@ return FT_Err_Ok; } + /* called while rendering through `FT_Render_Glyph' */ static FT_Error bsdf_raster_render( FT_Raster raster, const FT_Raster_Params* params ) @@ -1112,6 +1181,7 @@ return error; } + /* called while deleting a `FT_Library' only if the module is added */ static void bsdf_raster_done( FT_Raster raster ) { diff --git a/src/sdf/ftsdf.c b/src/sdf/ftsdf.c index 605c4465f..83323a7df 100644 --- a/src/sdf/ftsdf.c +++ b/src/sdf/ftsdf.c @@ -143,6 +143,8 @@ /* then they will be checked for corner if they have ambiguity. */ #define CORNER_CHECK_EPSILON 32 + /* Coarse grid dimension. Probably will be removed in the future cause */ + /* coarse grid optimization is the slowest. */ #define CG_DIMEN 8 /************************************************************************** @@ -161,101 +163,258 @@ * */ + /************************************************************************** + * + * @Struct: + * SDF_TRaster + * + * @Description: + * This struct is used in place of `FT_Raster' and is stored within + * the internal freetype renderer struct. While rasterizing this is + * passed to the `FT_Raster_Render_Func' function, which then can be + * used however we want. + * + * @Fields: + * memory :: + * Used internally to allocate intermediate memory while raterizing. + * + */ typedef struct SDF_TRaster_ { - FT_Memory memory; /* used internally to allocate memory */ + FT_Memory memory; } SDF_TRaster; - /* enumeration of all the types of curve present in vector fonts */ + /************************************************************************** + * + * @Enum: + * SDF_Edge_Type + * + * @Description: + * Enumeration of all the types of curve present in fonts. + * + * @Fields: + * SDF_EDGE_UNDEFINED :: + * Undefined edge, simply used to initialize and detect errors. + * + * SDF_EDGE_LINE :: + * Line segment with start and end point. + * + * SDF_EDGE_CONIC :: + * A conic/quadratic bezier curve with start, end and on control + * point. + * + * SDF_EDGE_CUBIC :: + * A cubic bezier curve with start, end and two control points. + * + */ typedef enum SDF_Edge_Type_ { - SDF_EDGE_UNDEFINED = 0, /* undefined, used to initialize */ - SDF_EDGE_LINE = 1, /* straight line segment */ - SDF_EDGE_CONIC = 2, /* second order bezier curve */ - SDF_EDGE_CUBIC = 3 /* third order bezier curve */ + SDF_EDGE_UNDEFINED = 0, + SDF_EDGE_LINE = 1, + SDF_EDGE_CONIC = 2, + SDF_EDGE_CUBIC = 3 } SDF_Edge_Type; - /* Enumeration for the orientation of a contour, remember */ - /* the orientation is independent of the fill rule. */ + /************************************************************************** + * + * @Enum: + * SDF_Contour_Orientation + * + * @Description: + * Enumeration of all the orientation of a contour. We determine the + * orientation by calculating the area covered by a contour. + * + * @Fields: + * SDF_ORIENTATION_NONE :: + * Undefined orientation, simply used to initialize and detect errors. + * + * SDF_ORIENTATION_CW :: + * Clockwise orientation. (positive area covered) + * + * SDF_ORIENTATION_ACW :: + * Anti-clockwise orientation. (negative area covered) + * + * @Note: + * The orientation is independent of the fill rule of a `FT_Outline', + * that means the fill will be different for different font formats. + * For example, for TrueType fonts clockwise contours are filled, while + * for OpenType fonts anti-clockwise contours are filled. To determine + * the propert fill rule use `FT_Outline_Get_Orientation'. + * + */ typedef enum SDF_Contour_Orientation_ { - SDF_ORIENTATION_NONE = 0, /* undefined, used to initialize */ - SDF_ORIENTATION_CW = 0, /* clockwise orientation */ - SDF_ORIENTATION_ACW = 0, /* anti-clockwise orientation */ + SDF_ORIENTATION_NONE = 0, + SDF_ORIENTATION_CW = 0, + SDF_ORIENTATION_ACW = 0 } SDF_Contour_Orientation; - /* represent a single edge in a contour */ + /************************************************************************** + * + * @Enum: + * SDF_Edge + * + * @Description: + * Represent an edge of a contour. + * + * @Fields: + * start_pos :: + * Start position of an edge. Valid for all types of edges. + * + * end_pos :: + * Etart position of an edge. Valid for all types of edges. + * + * control_a :: + * A control point of the edge. Valid only for `SDF_EDGE_CONIC' + * and `SDF_EDGE_CUBIC'. + * + * control_b :: + * Another control point of the edge. Valid only for `SDF_EDGE_CONIC'. + * + * edge_type :: + * Type of the edge, see `SDF_Edge_Type' for all possible edge types. + * + * next :: + * Used to create a singly linked list, which can be interpreted + * as a contour. + * + */ typedef struct SDF_Edge_ { - FT_26D6_Vec start_pos; /* start position of the edge */ - FT_26D6_Vec end_pos; /* end position of the edge */ - FT_26D6_Vec control_a; /* first control point of a bezier curve */ - FT_26D6_Vec control_b; /* second control point of a bezier curve */ + FT_26D6_Vec start_pos; + FT_26D6_Vec end_pos; + FT_26D6_Vec control_a; + FT_26D6_Vec control_b; - SDF_Edge_Type edge_type; /* edge identifier */ + SDF_Edge_Type edge_type; - struct SDF_Edge_* next; /* to create linked list */ + struct SDF_Edge_* next; } SDF_Edge; - /* A contour represent a set of edges which make a closed */ - /* loop. */ + /************************************************************************** + * + * @Enum: + * SDF_Contour + * + * @Description: + * Represent a complete contour, which contains a list of edges. + * + * @Fields: + * last_pos :: + * Contains the position of the `end_pos' of the last edge + * in the list of edges. Useful while decomposing the outline + * using `FT_Outline_Decompose'. + * + * edges :: + * Linked list of all the edges that make the contour. + * + * next :: + * Used to create a singly linked list, which can be interpreted + * as a complete shape or `FT_Outline'. + * + */ typedef struct SDF_Contour_ { - FT_26D6_Vec last_pos; /* end position of the last edge */ - SDF_Edge* edges; /* list of all edges in the contour */ + FT_26D6_Vec last_pos; + SDF_Edge* edges; - struct SDF_Contour_* next; /* to create linked list */ + struct SDF_Contour_* next; } SDF_Contour; - /* Represent a set a contours which makes up a complete */ - /* glyph outline. */ + /************************************************************************** + * + * @Enum: + * SDF_Shape + * + * @Description: + * Represent a complete shape which is the decomposition of `FT_Outline'. + * + * @Fields: + * memory :: + * Used internally to allocate memory. + * + * contours :: + * Linked list of all the contours that make the shape. + * + */ typedef struct SDF_Shape_ { - FT_Memory memory; /* used internally to allocate memory */ - SDF_Contour* contours; /* list of all contours in the outline */ + FT_Memory memory; + SDF_Contour* contours; } SDF_Shape; + /************************************************************************** + * + * @Enum: + * SDF_Signed_Distance + * + * @Description: + * Represent signed distance of a point, i.e. the distance of the + * edge nearest to the point. + * + * @Fields: + * distance :: + * Distance of the point from the nearest edge. Can be squared or + * absolute depending on the `USE_SQUARED_DISTANCES' parameter + * defined in `ftsdfcommon.h'. + * + * cross :: + * Cross product of the shortest distance vector (i.e. the vector + * the point to the nearest edge) and the direction of the edge + * at the nearest point. This is used to resolve any ambiguity + * in the sign. + * + * sign :: + * Represent weather the distance vector is outside or inside the + * contour corresponding to the edge. + * + * @Note: + * The `sign' may or may not be correct, therefore it must be checked + * properly in case there is an ambiguity. + * + */ typedef struct SDF_Signed_Distance_ { - /* Unsigned shortest distance from the point to */ - /* the above `nearest_point'. */ - /* [NOTE]: This can represent both squared as or */ - /* actual distance. This is controlled by the */ - /* `USE_SQUARED_DISTANCES' macro. */ FT_16D16 distance; - - /* The cross product of distance vector and the */ - /* direction. ( aka orthogonality ) */ FT_16D16 cross; - - /* Represent weather the distance vector is outside */ - /* or inside the contour corresponding to the edge. */ - /* [note]: This sign may or may not be correct, */ - /* therefore it must be checked properly in */ - /* case there is an ambiguity. */ FT_Char sign; } SDF_Signed_Distance; + /************************************************************************** + * + * @Enum: + * SDF_Params + * + * @Description: + * Yet another internal parameters required by the rasterizer. + * + * @Fields: + * orientation :: + * This is not the `SDF_Contour_Orientation', this is the + * `FT_Orientation', which determine weather clockwise is to + * be filled or anti-clockwise. + * + * flip_sign :: + * Simply flip the sign if this is true. By default the points + * filled by the outline are positive. + * + * flip_y :: + * If set to true the output bitmap will be upside down. Can be + * useful because OpenGL and DirectX have different coordinate + * system for textures. + * + */ typedef struct SDF_Params_ { - /* Used to properly assign sign to the pixels. In */ - /* truetype the right should be inside but in post */ - /* script left should be inside. */ FT_Orientation orientation; - - /* Simply flip the sign if this is true. */ FT_Bool flip_sign; - - /* If set to true the output will be upside down. */ - /* Can be useful because OpenGL and DirectX have */ - /* different coordinate system for textures. */ FT_Bool flip_y; } SDF_Params;