Commit e34a860a07ce60ae23ee4c01cb3c8076dc24c2b7
2022-01-27T11:50:12
Document `FT_Outline_Decompose` degenerate segments. `FT_Outline_Decompose` does not filter out and can return degenerate segments in an outline. This can be surprising when attemping to stroke such an outline. Clarify the existing documentation on this matter to cover all forms of degeneracy (without specifying exactly how they will be reported), why they might arise, and better explain in what cases they may be an issue. * include/freetype/ftoutlin.h (FT_Outline_Decompose): update documentation. Fixes #952.
diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h
index 32ca841..46ebf93 100644
--- a/include/freetype/ftoutln.h
+++ b/include/freetype/ftoutln.h
@@ -109,11 +109,13 @@ FT_BEGIN_HEADER
* FreeType error code. 0~means success.
*
* @note:
- * A contour that contains a single point only is represented by a 'move
- * to' operation followed by 'line to' to the same point. In most cases,
- * it is best to filter this out before using the outline for stroking
- * purposes (otherwise it would result in a visible dot when round caps
- * are used).
+ * Degenerate contours, segments, and Bezier arcs may be reported. In
+ * most cases, it is best to filter these out before using the outline
+ * for stroking or other path modification purposes (which may cause
+ * degenerate segments to become non-degenrate and visible, like when
+ * stroke caps are used or the path is otherwise outset). Some glyph
+ * outlines may contain deliberate degenerate single points for mark
+ * attachement.
*
* Similarly, the function returns success for an empty outline also
* (doing nothing, this is, not calling any emitter); if necessary, you