## Shaping

Shaping — Conversion of text strings into positioned glyphs

## Functions

hb_bool_t | hb_feature_from_string ()
void | hb_feature_to_string ()
void | hb_shape ()
hb_bool_t | hb_shape_full ()
const char ** | hb_shape_list_shapers ()

## Types and Values

| hb_feature_t

## Object Hierarchy

        GBoxed
        ╰── hb_feature_t

## 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_feature_from_string ()

    hb_bool_t
    hb_feature_from_string (const char *str,
                            int len,
                            hb_feature_t *feature);

Parses a string into a hb_feature_t.

TODO: document the syntax here.

#### Parameters

str | a string to parse. | [array length=len][element-type uint8_t]
len | length of `str` , or -1 if string is `NULL` terminated |
feature | the hb_feature_t to initialize with the parsed values. | [out]

#### Returns

`true` if `str` is successfully parsed, `false` otherwise.

Since: 0.9.5

### hb_feature_to_string ()

    void
    hb_feature_to_string (hb_feature_t *feature,
                          char *buf,
                          unsigned int size);

Converts a hb_feature_t into a `NULL`-terminated string in the format understood by `hb_feature_from_string()`. The client in responsible for allocating big enough size for `buf` , 128 bytes is more than enough.

#### Parameters

feature | an hb_feature_t to convert |
buf | output string. | [array length=size][out]
size | the allocated size of `buf` |

Since: 0.9.5

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

#### 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][allow-none]
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][allow-none]
num_features | the length of `features` array |
shaper_list | a `NULL`-terminated array of shapers to use or `NULL`. | [array zero-terminated=1][allow-none]

#### Returns

false if all shapers failed, true otherwise

Since: 0.9.2

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

## Types and Values

### hb_feature_t

    typedef struct {
      hb_tag_t      tag;
      uint32_t      value;
      unsigned int  start;
      unsigned int  end;
    } hb_feature_t;