* @short_description: Object representing a shaping plan
* @include: hb.h
*
- * Shape plans are not used for shaping directly, but can be access to query
- * certain information about how shaping will perform given a set of input
- * parameters (script, language, direction, features, etc.)
- * Most client would not need to deal with shape plans directly.
+ * Shape plans are an internal mechanism. Each plan contains state
+ * describing how HarfBuzz will shape a particular text segment, based on
+ * the combination of segment properties and the capabilities in the
+ * font face in use.
+ *
+ * Shape plans are not used for shaping directly, but can be queried to
+ * access certain information about how shaping will perform, given a set
+ * of specific input parameters (script, language, direction, features,
+ * etc.).
+ *
+ * Most client programs will not need to deal with shape plans directly.
**/
const char * const *shaper_list)
{
hb_feature_t *features = nullptr;
- if (copy && num_user_features && !(features = (hb_feature_t *) calloc (num_user_features, sizeof (hb_feature_t))))
+ if (copy && num_user_features && !(features = (hb_feature_t *) hb_calloc (num_user_features, sizeof (hb_feature_t))))
goto bail;
this->props = *props;
#undef HB_SHAPER_PLAN
bail:
- ::free (features);
+ ::hb_free (features);
return false;
}
/**
* hb_shape_plan_create: (Xconstructor)
- * @face:
- * @props:
- * @user_features: (array length=num_user_features):
- * @num_user_features:
- * @shaper_list: (array zero-terminated=1):
- *
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
*
+ * Constructs a shaping plan for a combination of @face, @user_features, @props,
+ * and @shaper_list.
*
- * Return value: (transfer full):
+ * Return value: (transfer full): The shaping plan
*
* Since: 0.9.7
**/
shaper_list);
}
+/**
+ * hb_shape_plan_create2: (Xconstructor)
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @coords: (array length=num_coords): The list of variation-space coordinates
+ * @num_coords: The number of variation-space coordinates
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
+ *
+ * The variable-font version of #hb_shape_plan_create.
+ * Constructs a shaping plan for a combination of @face, @user_features, @props,
+ * and @shaper_list, plus the variation-space coordinates @coords.
+ *
+ * Return value: (transfer full): The shaping plan
+ *
+ * Since: 1.4.0
+ **/
hb_shape_plan_t *
hb_shape_plan_create2 (hb_face_t *face,
const hb_segment_properties_t *props,
#ifndef HB_NO_OT_SHAPE
bail3:
#endif
- shape_plan->key.free ();
+ shape_plan->key.fini ();
bail2:
- free (shape_plan);
+ hb_free (shape_plan);
bail:
return hb_shape_plan_get_empty ();
}
/**
* hb_shape_plan_get_empty:
*
+ * Fetches the singleton empty shaping plan.
*
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The empty shaping plan
*
* Since: 0.9.7
**/
/**
* hb_shape_plan_reference: (skip)
- * @shape_plan: a shape plan.
+ * @shape_plan: A shaping plan
*
+ * Increases the reference count on the given shaping plan.
*
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): @shape_plan
*
* Since: 0.9.7
**/
/**
* hb_shape_plan_destroy: (skip)
- * @shape_plan: a shape plan.
- *
+ * @shape_plan: A shaping plan
*
+ * Decreases the reference count on the given shaping plan. When the
+ * reference count reaches zero, the shaping plan is destroyed,
+ * freeing all memory.
*
* Since: 0.9.7
**/
#ifndef HB_NO_OT_SHAPE
shape_plan->ot.fini ();
#endif
- shape_plan->key.free ();
- free (shape_plan);
+ shape_plan->key.fini ();
+ hb_free (shape_plan);
}
/**
* hb_shape_plan_set_user_data: (skip)
- * @shape_plan: a shape plan.
- * @key:
- * @data:
- * @destroy:
- * @replace:
- *
+ * @shape_plan: A shaping plan
+ * @key: The user-data key to set
+ * @data: A pointer to the user data
+ * @destroy: (nullable): A callback to call when @data is not needed anymore
+ * @replace: Whether to replace an existing data with the same key
*
+ * Attaches a user-data key/data pair to the given shaping plan.
*
- * Return value:
+ * Return value: %true if success, %false otherwise.
*
* Since: 0.9.7
**/
/**
* hb_shape_plan_get_user_data: (skip)
- * @shape_plan: a shape plan.
- * @key:
+ * @shape_plan: A shaping plan
+ * @key: The user-data key to query
*
+ * Fetches the user data associated with the specified key,
+ * attached to the specified shaping plan.
*
- *
- * Return value: (transfer none):
+ * Return value: (transfer none): A pointer to the user data
*
* Since: 0.9.7
**/
/**
* hb_shape_plan_get_shaper:
- * @shape_plan: a shape plan.
- *
+ * @shape_plan: A shaping plan
*
+ * Fetches the shaper from a given shaping plan.
*
- * Return value: (transfer none):
+ * Return value: (transfer none): The shaper
*
* Since: 0.9.7
**/
}
-/**
- * hb_shape_plan_execute:
- * @shape_plan: a shape plan.
- * @font: a font.
- * @buffer: a buffer.
- * @features: (array length=num_features):
- * @num_features:
- *
- *
- *
- * Return value:
- *
- * Since: 0.9.7
- **/
-hb_bool_t
-hb_shape_plan_execute (hb_shape_plan_t *shape_plan,
- hb_font_t *font,
- hb_buffer_t *buffer,
- const hb_feature_t *features,
- unsigned int num_features)
+static bool
+_hb_shape_plan_execute_internal (hb_shape_plan_t *shape_plan,
+ hb_font_t *font,
+ hb_buffer_t *buffer,
+ const hb_feature_t *features,
+ unsigned int num_features)
{
DEBUG_MSG_FUNC (SHAPE_PLAN, shape_plan,
"num_features=%d shaper_func=%p, shaper_name=%s",
return true;
assert (!hb_object_is_immutable (buffer));
- assert (buffer->content_type == HB_BUFFER_CONTENT_TYPE_UNICODE);
- if (unlikely (hb_object_is_inert (shape_plan)))
+ buffer->assert_unicode ();
+
+ if (unlikely (!hb_object_is_valid (shape_plan)))
return false;
assert (shape_plan->face_unsafe == font->face);
return false;
}
+/**
+ * hb_shape_plan_execute:
+ * @shape_plan: A shaping plan
+ * @font: The #hb_font_t to use
+ * @buffer: The #hb_buffer_t to work upon
+ * @features: (array length=num_features): Features to enable
+ * @num_features: The number of features to enable
+ *
+ * Executes the given shaping plan on the specified buffer, using
+ * the given @font and @features.
+ *
+ * Return value: %true if success, %false otherwise.
+ *
+ * Since: 0.9.7
+ **/
+hb_bool_t
+hb_shape_plan_execute (hb_shape_plan_t *shape_plan,
+ hb_font_t *font,
+ hb_buffer_t *buffer,
+ const hb_feature_t *features,
+ unsigned int num_features)
+{
+ bool ret = _hb_shape_plan_execute_internal (shape_plan, font, buffer,
+ features, num_features);
+
+ if (ret && buffer->content_type == HB_BUFFER_CONTENT_TYPE_UNICODE)
+ buffer->content_type = HB_BUFFER_CONTENT_TYPE_GLYPHS;
+
+ return ret;
+}
/*
/**
* hb_shape_plan_create_cached:
- * @face:
- * @props:
- * @user_features: (array length=num_user_features):
- * @num_user_features:
- * @shaper_list: (array zero-terminated=1):
- *
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
*
+ * Creates a cached shaping plan suitable for reuse, for a combination
+ * of @face, @user_features, @props, and @shaper_list.
*
- * Return value: (transfer full):
+ * Return value: (transfer full): The shaping plan
*
* Since: 0.9.7
**/
shaper_list);
}
+/**
+ * hb_shape_plan_create_cached2:
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @coords: (array length=num_coords): The list of variation-space coordinates
+ * @num_coords: The number of variation-space coordinates
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
+ *
+ * The variable-font version of #hb_shape_plan_create_cached.
+ * Creates a cached shaping plan suitable for reuse, for a combination
+ * of @face, @user_features, @props, and @shaper_list, plus the
+ * variation-space coordinates @coords.
+ *
+ * Return value: (transfer full): The shaping plan
+ *
+ * Since: 1.4.0
+ **/
hb_shape_plan_t *
hb_shape_plan_create_cached2 (hb_face_t *face,
const hb_segment_properties_t *props,
retry:
hb_face_t::plan_node_t *cached_plan_nodes = face->shape_plans;
- bool dont_cache = hb_object_is_inert (face);
+ bool dont_cache = !hb_object_is_valid (face);
if (likely (!dont_cache))
{
if (unlikely (dont_cache))
return shape_plan;
- hb_face_t::plan_node_t *node = (hb_face_t::plan_node_t *) calloc (1, sizeof (hb_face_t::plan_node_t));
+ hb_face_t::plan_node_t *node = (hb_face_t::plan_node_t *) hb_calloc (1, sizeof (hb_face_t::plan_node_t));
if (unlikely (!node))
return shape_plan;
if (unlikely (!face->shape_plans.cmpexch (cached_plan_nodes, node)))
{
hb_shape_plan_destroy (shape_plan);
- free (node);
+ hb_free (node);
goto retry;
}
DEBUG_MSG_FUNC (SHAPE_PLAN, shape_plan, "inserted into cache");
projects / platform / upstream / harfbuzz.git / blobdiff