Move outline draw API behind HB_EXPERIMENTAL_API directive

.circleci/config.yml

@@ -121,6 +121,8 @@ jobs:
       - run: HB_TEST_SHAPE_FUZZER_TIMEOUT=3 HB_TEST_SUBSET_FUZZER_TIMEOUT=30 RUN_VALGRIND=1 make check && make -Ctest/api check-valgrind || .ci/fail.sh
       # informational for now
       - run: make -Ctest/api check-symbols || true
+      # enable and test experimental outline drawing APIs
+      - run: make clean && HB_EXPERIMENTAL_API=1 make -j9 CPPFLAGS="-DHB_EXPERIMENTAL_API" check
 
   clang-everything:
     docker:

docs/harfbuzz-sections.txt

@@ -221,26 +221,6 @@ hb_directwrite_face_get_font_face
 hb_directwrite_shape_experimental_width
 </SECTION>
 
-<SECTION>
-<FILE>hb-draw</FILE>
-hb_draw_funcs_t
-hb_draw_close_path_func_t
-hb_draw_cubic_to_func_t
-hb_draw_line_to_func_t
-hb_draw_move_to_func_t
-hb_draw_quadratic_to_func_t
-hb_draw_funcs_create
-hb_draw_funcs_destroy
-hb_draw_funcs_is_immutable
-hb_draw_funcs_make_immutable
-hb_draw_funcs_reference
-hb_draw_funcs_set_close_path_func
-hb_draw_funcs_set_cubic_to_func
-hb_draw_funcs_set_line_to_func
-hb_draw_funcs_set_move_to_func
-hb_draw_funcs_set_quadratic_to_func
-</SECTION>
-
 <SECTION>
 <FILE>hb-face</FILE>
 hb_face_count
@@ -276,7 +256,6 @@ hb_font_add_glyph_origin_for_direction
 hb_font_create
 hb_font_create_sub_font
 hb_font_destroy
-hb_font_draw_glyph
 hb_font_funcs_create
 hb_font_funcs_destroy
 hb_font_funcs_get_empty

src/gen-def.py

@@ -13,7 +13,29 @@ for h in header_paths:
 	if h.endswith (".h"):
 		with io.open (h, encoding='utf-8') as f: headers_content.append (f.read ())
 
-symbols = "\n".join (sorted (re.findall (r"^hb_\w+(?= \()", "\n".join (headers_content), re.M)))
+symbols = sorted (re.findall (r"^hb_\w+(?= \()", "\n".join (headers_content), re.M))
+if not os.environ.get('HB_EXPERIMENTAL_API', ''):
+	# Move these to harfbuzz-sections.txt when got stable
+	experimental_symbols = \
+"""hb_font_draw_glyph
+hb_draw_funcs_t
+hb_draw_close_path_func_t
+hb_draw_cubic_to_func_t
+hb_draw_line_to_func_t
+hb_draw_move_to_func_t
+hb_draw_quadratic_to_func_t
+hb_draw_funcs_create
+hb_draw_funcs_destroy
+hb_draw_funcs_is_immutable
+hb_draw_funcs_make_immutable
+hb_draw_funcs_reference
+hb_draw_funcs_set_close_path_func
+hb_draw_funcs_set_cubic_to_func
+hb_draw_funcs_set_line_to_func
+hb_draw_funcs_set_move_to_func
+hb_draw_funcs_set_quadratic_to_func""".splitlines ()
+	symbols = [x for x in symbols if x not in experimental_symbols]
+symbols = "\n".join (symbols)
 
 result = symbols if os.environ.get('PLAIN_LIST', '') else """EXPORTS
 %s

src/hb-draw.cc

@@ -25,6 +25,7 @@
 #include "hb.hh"
 
 #ifndef HB_NO_DRAW
+#ifdef HB_EXPERIMENTAL_API
 
 #include "hb-draw.hh"
 #include "hb-ot.h"
@@ -39,7 +40,7 @@
  *
  * Sets move-to callback to the draw functions object.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_set_move_to_func (hb_draw_funcs_t        *funcs,
@@ -56,7 +57,7 @@ hb_draw_funcs_set_move_to_func (hb_draw_funcs_t        *funcs,
  *
  * Sets line-to callback to the draw functions object.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_set_line_to_func (hb_draw_funcs_t        *funcs,
@@ -73,7 +74,7 @@ hb_draw_funcs_set_line_to_func (hb_draw_funcs_t        *funcs,
  *
  * Sets quadratic-to callback to the draw functions object.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_set_quadratic_to_func (hb_draw_funcs_t             *funcs,
@@ -91,7 +92,7 @@ hb_draw_funcs_set_quadratic_to_func (hb_draw_funcs_t             *funcs,
  *
  * Sets cubic-to callback to the draw functions object.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_set_cubic_to_func (hb_draw_funcs_t         *funcs,
@@ -108,7 +109,7 @@ hb_draw_funcs_set_cubic_to_func (hb_draw_funcs_t         *funcs,
  *
  * Sets close-path callback to the draw functions object.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_set_close_path_func (hb_draw_funcs_t           *funcs,
@@ -143,7 +144,7 @@ _close_path_nil (void *user_data HB_UNUSED) {}
  *
  * Creates a new draw callbacks object.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 hb_draw_funcs_t *
 hb_draw_funcs_create ()
@@ -168,7 +169,7 @@ hb_draw_funcs_create ()
  * Add to callbacks object refcount.
  *
  * Returns: The same object.
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 hb_draw_funcs_t *
 hb_draw_funcs_reference (hb_draw_funcs_t *funcs)
@@ -183,7 +184,7 @@ hb_draw_funcs_reference (hb_draw_funcs_t *funcs)
  * Decreases refcount of callbacks object and deletes the object if it reaches
  * to zero.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_destroy (hb_draw_funcs_t *funcs)
@@ -199,7 +200,7 @@ hb_draw_funcs_destroy (hb_draw_funcs_t *funcs)
  *
  * Makes funcs object immutable.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 void
 hb_draw_funcs_make_immutable (hb_draw_funcs_t *funcs)
@@ -217,7 +218,7 @@ hb_draw_funcs_make_immutable (hb_draw_funcs_t *funcs)
  * Checks whether funcs is immutable.
  *
  * Returns: If is immutable.
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 hb_bool_t
 hb_draw_funcs_is_immutable (hb_draw_funcs_t *funcs)
@@ -235,7 +236,7 @@ hb_draw_funcs_is_immutable (hb_draw_funcs_t *funcs)
  * Draw a glyph.
  *
  * Returns: Whether the font had the glyph and the operation completed successfully.
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 hb_bool_t
 hb_font_draw_glyph (hb_font_t *font, hb_codepoint_t glyph,
@@ -257,3 +258,4 @@ hb_font_draw_glyph (hb_font_t *font, hb_codepoint_t glyph,
 }
 
 #endif
+#endif

src/hb-draw.h

@@ -33,6 +33,7 @@
 
 HB_BEGIN_DECLS
 
+#ifdef HB_EXPERIMENTAL_API
 typedef void (*hb_draw_move_to_func_t) (hb_position_t to_x, hb_position_t to_y, void *user_data);
 typedef void (*hb_draw_line_to_func_t) (hb_position_t to_x, hb_position_t to_y, void *user_data);
 typedef void (*hb_draw_quadratic_to_func_t) (hb_position_t control_x, hb_position_t control_y,
@@ -52,7 +53,7 @@ typedef void (*hb_draw_close_path_func_t) (void *user_data);
  * _move_to, _line_to and _cubic_to calls are nessecary to be defined but we
  * translate _quadratic_to calls to _cubic_to if the callback isn't defined.
  *
- * Since: REPLACEME
+ * Since: EXPERIMENTAL
  **/
 typedef struct hb_draw_funcs_t hb_draw_funcs_t;
 
@@ -90,6 +91,7 @@ hb_draw_funcs_make_immutable (hb_draw_funcs_t *funcs);
 
 HB_EXTERN hb_bool_t
 hb_draw_funcs_is_immutable (hb_draw_funcs_t *funcs);
+#endif
 
 HB_END_DECLS
 

src/hb-draw.hh

@@ -27,6 +27,7 @@
 
 #include "hb.hh"
 
+#ifdef HB_EXPERIMENTAL_API
 struct hb_draw_funcs_t
 {
   hb_object_header_t header;
@@ -133,5 +134,6 @@ struct draw_helper_t
   const hb_draw_funcs_t *funcs;
   void *user_data;
 };
+#endif
 
 #endif /* HB_DRAW_HH */

src/hb-font.h

@@ -722,9 +722,11 @@ HB_EXTERN void
 hb_font_set_var_named_instance (hb_font_t *font,
 				unsigned instance_index);
 
+#ifdef HB_EXPERIMENTAL_API
 HB_EXTERN hb_bool_t
 hb_font_draw_glyph (hb_font_t *font, hb_codepoint_t glyph,
 		    const hb_draw_funcs_t *funcs, void *user_data);
+#endif
 
 HB_END_DECLS
 

src/hb-ot-cff1-table.cc

@@ -343,6 +343,7 @@ bool OT::cff1::accelerator_t::get_extents (hb_font_t *font, hb_codepoint_t glyph
   return true;
 }
 
+#ifdef HB_EXPERIMENTAL_API
 struct cff1_path_param_t
 {
   cff1_path_param_t (const OT::cff1::accelerator_t *cff_, hb_font_t *font_,
@@ -464,6 +465,7 @@ bool OT::cff1::accelerator_t::get_path (hb_font_t *font, hb_codepoint_t glyph, d
 
   return _get_path (this, font, glyph, draw_helper);
 }
+#endif
 
 struct get_seac_param_t
 {

src/hb-ot-cff1-table.hh

@@ -1320,7 +1320,9 @@ struct cff1
 
     HB_INTERNAL bool get_extents (hb_font_t *font, hb_codepoint_t glyph, hb_glyph_extents_t *extents) const;
     HB_INTERNAL bool get_seac_components (hb_codepoint_t glyph, hb_codepoint_t *base, hb_codepoint_t *accent) const;
+#ifdef HB_EXPERIMENTAL_API
     HB_INTERNAL bool get_path (hb_font_t *font, hb_codepoint_t glyph, draw_helper_t &draw_helper) const;
+#endif
 
     private:
     struct gname_t

src/hb-ot-cff2-table.cc

@@ -143,6 +143,7 @@ bool OT::cff2::accelerator_t::get_extents (hb_font_t *font,
   return true;
 }
 
+#ifdef HB_EXPERIMENTAL_API
 struct cff2_path_param_t
 {
   cff2_path_param_t (hb_font_t *font_, draw_helper_t &draw_helper_)
@@ -209,5 +210,6 @@ bool OT::cff2::accelerator_t::get_path (hb_font_t *font, hb_codepoint_t glyph, d
   if (unlikely (!interp.interpret (param))) return false;
   return true;
 }
+#endif
 
 #endif

src/hb-ot-cff2-table.hh

@@ -506,7 +506,9 @@ struct cff2
     HB_INTERNAL bool get_extents (hb_font_t *font,
 				  hb_codepoint_t glyph,
 				  hb_glyph_extents_t *extents) const;
+#ifdef HB_EXPERIMENTAL_API
     HB_INTERNAL bool get_path (hb_font_t *font, hb_codepoint_t glyph, draw_helper_t &draw_helper) const;
+#endif
   };
 
   typedef accelerator_templ_t<cff2_private_dict_opset_subset_t, cff2_private_dict_values_subset_t> accelerator_subset_t;

src/hb-ot-glyf-table.hh

@@ -1032,6 +1032,7 @@ struct glyf
 	add_gid_and_children (item.glyphIndex, gids_to_retain, depth);
     }
 
+#ifdef HB_EXPERIMENTAL_API
     struct path_builder_t
     {
       hb_font_t *font;
@@ -1150,6 +1151,7 @@ struct glyf
     bool
     get_path (hb_font_t *font, hb_codepoint_t gid, draw_helper_t &draw_helper) const
     { return get_points (font, gid, path_builder_t (font, draw_helper)); }
+#endif
 
     private:
     bool short_offset;

src/main.cc

@@ -38,6 +38,7 @@
 #endif
 
 #if !defined(HB_NO_COLOR) && !defined(HB_NO_DRAW)
+#ifdef HB_EXPERIMENTAL_API
 static void
 svg_dump (hb_face_t *face, unsigned face_index)
 {
@@ -328,6 +329,7 @@ dump_glyphs (hb_blob_t *blob, const char *font_name)
   hb_draw_funcs_destroy (funcs);
 }
 #endif
+#endif
 
 /* Only this part of this mini app uses private API */
 #include "hb-static.cc"
@@ -503,7 +505,9 @@ main (int argc, char **argv)
   printf ("Opened font file %s: %d bytes long\n", argv[1], hb_blob_get_length (blob));
   print_layout_info_using_private_api (blob);
 #if !defined(HB_NO_COLOR) && !defined(HB_NO_DRAW)
+#ifdef HB_EXPERIMENTAL_API
   dump_glyphs (blob, argv[1]);
+#endif
 #endif
   hb_blob_destroy (blob);
 

test/api/test-draw.c

@@ -26,6 +26,7 @@
 
 #include <hb.h>
 
+#ifdef HB_EXPERIMENTAL_API
 typedef struct user_data_t
 {
   char *str;
@@ -935,3 +936,9 @@ main (int argc, char **argv)
   hb_draw_funcs_destroy (funcs2);
   return result;
 }
+#else
+int main (int argc HB_UNUSED, char **argv HB_UNUSED)
+{
+  return 0;
+}
+#endif

test/api/test-ot-face.c

@@ -120,9 +120,11 @@ test_font (hb_font_t *font, hb_codepoint_t cp)
   hb_ot_var_normalize_variations (face, NULL, 0, NULL, 0);
   hb_ot_var_normalize_coords (face, 0, NULL, NULL);
 
+#ifdef HB_EXPERIMENTAL_API
   hb_draw_funcs_t *funcs = hb_draw_funcs_create ();
   hb_font_draw_glyph (font, cp, funcs, NULL);
   hb_draw_funcs_destroy (funcs);
+#endif
 
   hb_set_destroy (set);
 }

test/fuzzing/hb-draw-fuzzer.cc

@@ -5,6 +5,7 @@
 
 #include "hb-fuzzer.hh"
 
+#ifdef HB_EXPERIMENTAL_API
 struct _user_data_t
 {
   bool is_open;
@@ -74,6 +75,7 @@ _close_path (void *user_data_)
   assert (user_data->path_start_x == user_data->path_last_x &&
 	  user_data->path_start_y == user_data->path_last_y);
 }
+#endif
 
 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
 {
@@ -95,6 +97,7 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
   unsigned glyph_count = hb_face_get_glyph_count (face);
   glyph_count = glyph_count > 16 ? 16 : glyph_count;
 
+#ifdef HB_EXPERIMENTAL_API
   _user_data_t user_data = {false, 0, 0, 0, 0, 0};
 
   hb_draw_funcs_t *funcs = hb_draw_funcs_create ();
@@ -103,11 +106,14 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
   hb_draw_funcs_set_quadratic_to_func (funcs, (hb_draw_quadratic_to_func_t) _quadratic_to);
   hb_draw_funcs_set_cubic_to_func (funcs, (hb_draw_cubic_to_func_t) _cubic_to);
   hb_draw_funcs_set_close_path_func (funcs, (hb_draw_close_path_func_t) _close_path);
+#endif
   volatile unsigned counter = !glyph_count;
   for (unsigned gid = 0; gid < glyph_count; ++gid)
   {
+#ifdef HB_EXPERIMENTAL_API
     hb_font_draw_glyph (font, gid, funcs, &user_data);
     assert (!user_data.is_open);
+#endif
 
     /* Glyph extents also may practices the similar path, call it now that is related */
     hb_glyph_extents_t extents;
@@ -117,7 +123,9 @@ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
     if (!counter) counter += 1;
   }
   assert (counter);
+#ifdef HB_EXPERIMENTAL_API
   hb_draw_funcs_destroy (funcs);
+#endif
 
   hb_font_destroy (font);
   hb_face_destroy (face);