## hb-shape

hb-shape — Conversion of text strings into positioned glyphs

## Functions

void | hb_shape ()
hb_bool_t | hb_shape_full ()
hb_bool_t | hb_shape_justify ()
const char ** | hb_shape_list_shapers ()

## Includes

    #include <hb.h>

## Description

Shaping is the central operation of HarfBuzz. Shaping operates on buffers, which are sequences of Unicode characters that use the same font and have the same text direction, script, and language. After shaping the buffer contains the output glyphs and their positions.

## Functions

### hb_shape ()

    void
    hb_shape (hb_font_t *font,
              hb_buffer_t *buffer,
              const hb_feature_t *features,
              unsigned int num_features);

Shapes `buffer` using `font` turning its Unicode characters content to positioned glyphs. If `features` is not `NULL`, it will be used to control the features applied during shaping. If two `features` have the same tag but overlapping ranges the value of the feature with the higher index takes precedence.

#### Parameters

font | an hb_font_t to use for shaping |
buffer | an hb_buffer_t to shape |
features | an array of user specified hb_feature_t or `NULL`. | [array length=num_features][nullable]
num_features | the length of `features` array |

Since: 0.9.2

### hb_shape_full ()

    hb_bool_t
    hb_shape_full (hb_font_t *font,
                   hb_buffer_t *buffer,
                   const hb_feature_t *features,
                   unsigned int num_features,
                   const char * const *shaper_list);

See `hb_shape()` for details. If `shaper_list` is not `NULL`, the specified shapers will be used in the given order, otherwise the default shapers list will be used.

#### Parameters

font | an hb_font_t to use for shaping |
buffer | an hb_buffer_t to shape |
features | an array of user specified hb_feature_t or `NULL`. | [array length=num_features][nullable]
num_features | the length of `features` array |
shaper_list | a `NULL`-terminated array of shapers to use or `NULL`. | [array zero-terminated=1][nullable]

#### Returns

false if all shapers failed, true otherwise

Since: 0.9.2

### hb_shape_justify ()

    hb_bool_t
    hb_shape_justify (hb_font_t *font,
                      hb_buffer_t *buffer,
                      const hb_feature_t *features,
                      unsigned int num_features,
                      const char * const *shaper_list,
                      float min_target_advance,
                      float max_target_advance,
                      float *advance,
                      hb_tag_t *var_tag,
                      float *var_value);

See `hb_shape_full()` for basic details. If `shaper_list` is not `NULL`, the specified shapers will be used in the given order, otherwise the default shapers list will be used.

In addition, justify the shaping results such that the shaping results reach the target advance width/height, depending on the buffer direction.

If the advance of the buffer shaped with `hb_shape_full()` is already known, put that in *advance. Otherwise set *advance to zero.

This API is currently experimental and will probably change in the future.

#### Parameters

font | a mutable hb_font_t to use for shaping |
buffer | an hb_buffer_t to shape |
features | an array of user specified hb_feature_t or `NULL`. | [array length=num_features][nullable]
num_features | the length of `features` array |
shaper_list | a `NULL`-terminated array of shapers to use or `NULL`. | [array zero-terminated=1][nullable]
min_target_advance | Minimum advance width/height to aim for. |
max_target_advance | Maximum advance width/height to aim for. |
advance | Input/output advance width/height of the buffer. | [inout]
var_tag | Variation-axis tag used for justification. | [out]
var_value | Variation-axis value used to reach target justification. | [out]

#### Returns

false if all shapers failed, true otherwise

XSince: EXPERIMENTAL

### hb_shape_list_shapers ()

    const char **
    hb_shape_list_shapers (void);

Retrieves the list of shapers supported by HarfBuzz.

#### Returns

an array of constant strings.

[transfer none][array zero-terminated=1]

Since: 0.9.2