hb-shape-plan: HarfBuzz Manual

hb-shape-plan

hb-shape-plan — Object representing a shaping plan

Functions

hb_shape_plan_t *	hb_shape_plan_create ()
hb_shape_plan_t *	hb_shape_plan_create_cached ()
hb_shape_plan_t *	hb_shape_plan_create2 ()
hb_shape_plan_t *	hb_shape_plan_create_cached2 ()
hb_shape_plan_t *	hb_shape_plan_get_empty ()
hb_shape_plan_t *	hb_shape_plan_reference ()
void	hb_shape_plan_destroy ()
hb_bool_t	hb_shape_plan_set_user_data ()
void *	hb_shape_plan_get_user_data ()
hb_bool_t	hb_shape_plan_execute ()
const char *	hb_shape_plan_get_shaper ()

Types and Values

typedef

hb_shape_plan_t

Includes

#include <hb.h>

Description

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.

Functions

hb_shape_plan_create ()

hb_shape_plan_t *
hb_shape_plan_create (hb_face_t *face,
                      const hb_segment_properties_t *props,
                      const hb_feature_t *user_features,
                      unsigned int num_user_features,
                      const char * const *shaper_list);

Constructs a shaping plan for a combination of face , user_features , props , and shaper_list .

Parameters

face	hb_face_t to use
props	The hb_segment_properties_t of the segment
user_features	The list of user-selected features.	[array length=num_user_features]
num_user_features	The number of user-selected features
shaper_list	List of shapers to try.	[array zero-terminated=1]

Returns

The shaping plan.

[transfer full]

Since: 0.9.7

hb_shape_plan_create_cached ()

hb_shape_plan_t *
hb_shape_plan_create_cached (hb_face_t *face,
                             const hb_segment_properties_t *props,
                             const hb_feature_t *user_features,
                             unsigned int num_user_features,
                             const char * const *shaper_list);

Creates a cached shaping plan suitable for reuse, for a combination of face , user_features , props , and shaper_list .

Parameters

face	hb_face_t to use
props	The hb_segment_properties_t of the segment
user_features	The list of user-selected features.	[array length=num_user_features]
num_user_features	The number of user-selected features
shaper_list	List of shapers to try.	[array zero-terminated=1]

Returns

The shaping plan.

[transfer full]

Since: 0.9.7

hb_shape_plan_create2 ()

hb_shape_plan_t *
hb_shape_plan_create2 (hb_face_t *face,
                       const hb_segment_properties_t *props,
                       const hb_feature_t *user_features,
                       unsigned int num_user_features,
                       const int *coords,
                       unsigned int num_coords,
                       const char * const *shaper_list);

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 .

Parameters

face	hb_face_t to use
props	The hb_segment_properties_t of the segment
user_features	The list of user-selected features.	[array length=num_user_features]
num_user_features	The number of user-selected features
coords	The list of variation-space coordinates.	[array length=num_coords]
num_coords	The number of variation-space coordinates
shaper_list	List of shapers to try.	[array zero-terminated=1]

Returns

The shaping plan.

[transfer full]

Since: 1.4.0

hb_shape_plan_create_cached2 ()

hb_shape_plan_t *
hb_shape_plan_create_cached2 (hb_face_t *face,
                              const hb_segment_properties_t *props,
                              const hb_feature_t *user_features,
                              unsigned int num_user_features,
                              const int *coords,
                              unsigned int num_coords,
                              const char * const *shaper_list);

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 .

Parameters

face	hb_face_t to use
props	The hb_segment_properties_t of the segment
user_features	The list of user-selected features.	[array length=num_user_features]
num_user_features	The number of user-selected features
coords	The list of variation-space coordinates.	[array length=num_coords]
num_coords	The number of variation-space coordinates
shaper_list	List of shapers to try.	[array zero-terminated=1]

Returns

The shaping plan.

[transfer full]

Since: 1.4.0

hb_shape_plan_get_empty ()

hb_shape_plan_t *
hb_shape_plan_get_empty (void);

Fetches the singleton empty shaping plan.

Returns

The empty shaping plan.

[transfer full]

Since: 0.9.7

hb_shape_plan_reference ()

hb_shape_plan_t *
hb_shape_plan_reference (hb_shape_plan_t *shape_plan);

Increases the reference count on the given shaping plan.

[skip]

Parameters

shape_plan

A shaping plan

Returns

shape_plan .

[transfer full]

Since: 0.9.7

hb_shape_plan_destroy ()

void
hb_shape_plan_destroy (hb_shape_plan_t *shape_plan);

Decreases the reference count on the given shaping plan. When the reference count reaches zero, the shaping plan is destroyed, freeing all memory.

[skip]

Parameters

shape_plan

A shaping plan

Since: 0.9.7

hb_shape_plan_set_user_data ()

hb_bool_t
hb_shape_plan_set_user_data (hb_shape_plan_t *shape_plan,
                             hb_user_data_key_t *key,
                             void *data,
                             hb_destroy_func_t destroy,
                             hb_bool_t replace);

Attaches a user-data key/data pair to the given shaping plan.

[skip]

Parameters

shape_plan	A shaping plan
key	The user-data key to set
data	A pointer to the user data
destroy	A callback to call when `data` is not needed anymore.	[nullable]
replace	Whether to replace an existing data with the same key

Returns

true if success, false otherwise.

Since: 0.9.7

hb_shape_plan_get_user_data ()

void *
hb_shape_plan_get_user_data (const hb_shape_plan_t *shape_plan,
                             hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified shaping plan.

[skip]

Parameters

shape_plan	A shaping plan
key	The user-data key to query

Returns

A pointer to the user data.

[transfer none]

Since: 0.9.7

hb_shape_plan_execute ()

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);

Executes the given shaping plan on the specified buffer, using the given font and features .

Parameters

shape_plan	A shaping plan
font	The hb_font_t to use
buffer	The hb_buffer_t to work upon
features	Features to enable.	[array length=num_features]
num_features	The number of features to enable

Returns

true if success, false otherwise.

Since: 0.9.7

hb_shape_plan_get_shaper ()

const char *
hb_shape_plan_get_shaper (hb_shape_plan_t *shape_plan);

Fetches the shaper from a given shaping plan.

Parameters

shape_plan

A shaping plan

Returns

The shaper.

[transfer none]

Since: 0.9.7

Types and Values

hb_shape_plan_t

typedef struct hb_shape_plan_t hb_shape_plan_t;

Data type for holding a shaping plan.

Shape plans contain information about how HarfBuzz will shape a particular text segment, based on the segment's properties and the capabilities in the font face in use.

Shape plans can be queried about how shaping will perform, given a set of specific input parameters (script, language, direction, features, etc.).