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 ()
void | hb_shape_plan_destroy ()
hb_bool_t | hb_shape_plan_execute ()
hb_shape_plan_t * | hb_shape_plan_get_empty ()
const char * | hb_shape_plan_get_shaper ()
void * | hb_shape_plan_get_user_data ()
hb_shape_plan_t * | hb_shape_plan_reference ()
hb_bool_t | hb_shape_plan_set_user_data ()

## 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` .

[Xconstructor]

#### 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` .

[Xconstructor]

#### 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_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_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_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_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

### hb_shape_plan_get_user_data ()

    void *
    hb_shape_plan_get_user_data (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_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_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

## 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.).