hb-blob: HarfBuzz Manual

hb-blob

hb-blob — Binary data containers

Functions

hb_blob_t *	hb_blob_create ()
hb_blob_t *	hb_blob_create_or_fail ()
hb_blob_t *	hb_blob_create_from_file ()
hb_blob_t *	hb_blob_create_from_file_or_fail ()
hb_blob_t *	hb_blob_create_sub_blob ()
hb_blob_t *	hb_blob_copy_writable_or_fail ()
hb_blob_t *	hb_blob_get_empty ()
hb_blob_t *	hb_blob_reference ()
void	hb_blob_destroy ()
hb_bool_t	hb_blob_set_user_data ()
void *	hb_blob_get_user_data ()
void	hb_blob_make_immutable ()
hb_bool_t	hb_blob_is_immutable ()
const char *	hb_blob_get_data ()
char *	hb_blob_get_data_writable ()
unsigned int	hb_blob_get_length ()

Types and Values

typedef	hb_blob_t
enum	hb_memory_mode_t

Includes

#include <hb.h>

Description

Blobs wrap a chunk of binary data to handle lifecycle management of data while it is passed between client and HarfBuzz. Blobs are primarily used to create font faces, but also to access font face tables, as well as pass around other binary data.

Functions

hb_blob_create ()

hb_blob_t *
hb_blob_create (const char *data,
                unsigned int length,
                hb_memory_mode_t mode,
                void *user_data,
                hb_destroy_func_t destroy);

Creates a new "blob" object wrapping data . The mode parameter is used to negotiate ownership and lifecycle of data .

[skip]

Parameters

data	Pointer to blob data.
length	Length of `data` in bytes.
mode	Memory mode for `data` .
user_data	Data parameter to pass to `destroy` .
destroy	Callback to call when `data` is not needed anymore.	[nullable]

Returns

New blob, or the empty blob if something failed or if length is zero. Destroy with hb_blob_destroy().

Since: 0.9.2

hb_blob_create_or_fail ()

hb_blob_t *
hb_blob_create_or_fail (const char *data,
                        unsigned int length,
                        hb_memory_mode_t mode,
                        void *user_data,
                        hb_destroy_func_t destroy);

Creates a new "blob" object wrapping data . The mode parameter is used to negotiate ownership and lifecycle of data .

Note that this function returns a freshly-allocated empty blob even if length is zero. This is in contrast to hb_blob_create(), which returns the singleton empty blob (as returned by hb_blob_get_empty()) if length is zero.

[skip]

Parameters

data	Pointer to blob data.
length	Length of `data` in bytes.
mode	Memory mode for `data` .
user_data	Data parameter to pass to `destroy` .
destroy	Callback to call when `data` is not needed anymore.	[nullable]

Returns

New blob, or NULL if failed. Destroy with hb_blob_destroy().

Since: 2.8.2

hb_blob_create_from_file ()

hb_blob_t *
hb_blob_create_from_file (const char *file_name);

Creates a new blob containing the data from the specified binary font file.

The filename is passed directly to the system on all platforms, except on Windows, where the filename is interpreted as UTF-8. Only if the filename is not valid UTF-8, it will be interpreted according to the system codepage.

Parameters

file_name

A font filename

Returns

An hb_blob_t pointer with the content of the file, or hb_blob_get_empty() if failed.

Since: 1.7.7

hb_blob_create_from_file_or_fail ()

hb_blob_t *
hb_blob_create_from_file_or_fail (const char *file_name);

Creates a new blob containing the data from the specified file.

Parameters

file_name

A filename

Returns

An hb_blob_t pointer with the content of the file, or NULL if failed.

Since: 2.8.2

hb_blob_create_sub_blob ()

hb_blob_t *
hb_blob_create_sub_blob (hb_blob_t *parent,
                         unsigned int offset,
                         unsigned int length);

Returns a blob that represents a range of bytes in parent . The new blob is always created with HB_MEMORY_MODE_READONLY, meaning that it will never modify data in the parent blob. The parent data is not expected to be modified, and will result in undefined behavior if it is.

Makes parent immutable.

Parameters

parent	Parent blob.
offset	Start offset of sub-blob within `parent` , in bytes.
length	Length of sub-blob.

Returns

New blob, or the empty blob if something failed or if length is zero or offset is beyond the end of parent 's data. Destroy with hb_blob_destroy().

Since: 0.9.2

hb_blob_copy_writable_or_fail ()

hb_blob_t *
hb_blob_copy_writable_or_fail (hb_blob_t *blob);

Makes a writable copy of blob .

Parameters

blob

A blob.

Returns

The new blob, or nullptr if allocation failed

Since: 1.8.0

hb_blob_get_empty ()

hb_blob_t *
hb_blob_get_empty (void);

Returns the singleton empty blob.

See TODO:link object types for more information.

Returns

The empty blob.

[transfer full]

Since: 0.9.2

hb_blob_reference ()

hb_blob_t *
hb_blob_reference (hb_blob_t *blob);

Increases the reference count on blob .

See TODO:link object types for more information.

[skip]

Parameters

blob

a blob.

Returns

blob .

Since: 0.9.2

hb_blob_destroy ()

void
hb_blob_destroy (hb_blob_t *blob);

Decreases the reference count on blob , and if it reaches zero, destroys blob , freeing all memory, possibly calling the destroy-callback the blob was created for if it has not been called already.

See TODO:link object types for more information.

[skip]

Parameters

blob

a blob.

Since: 0.9.2

hb_blob_set_user_data ()

hb_bool_t
hb_blob_set_user_data (hb_blob_t *blob,
                       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 specified blob.

[skip]

Parameters

blob	An hb_blob_t
key	The user-data key to set
data	A pointer to the user data to set
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.2

hb_blob_get_user_data ()

void *
hb_blob_get_user_data (const hb_blob_t *blob,
                       hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified font-functions structure.

[skip]

Parameters

blob	a blob
key	The user-data key to query

Returns

A pointer to the user data.

[transfer none]

Since: 0.9.2

hb_blob_make_immutable ()

void
hb_blob_make_immutable (hb_blob_t *blob);

Makes a blob immutable.

Parameters

blob

a blob

Since: 0.9.2

hb_blob_is_immutable ()

hb_bool_t
hb_blob_is_immutable (hb_blob_t *blob);

Tests whether a blob is immutable.

Parameters

blob

a blob.

Returns

true if blob is immutable, false otherwise

Since: 0.9.2

hb_blob_get_data ()

const char *
hb_blob_get_data (hb_blob_t *blob,
                  unsigned int *length);

Fetches the data from a blob.

Parameters

blob	a blob.
length	The length in bytes of the data retrieved.	[out]

Returns

the byte data of blob .

[nullable][transfer none][array length=length]

Since: 0.9.2

hb_blob_get_data_writable ()

char *
hb_blob_get_data_writable (hb_blob_t *blob,
                           unsigned int *length);

Tries to make blob data writable (possibly copying it) and return pointer to data.

Fails if blob has been made immutable, or if memory allocation fails.

Parameters

blob	a blob.
length	output length of the writable data.	[out]

Returns

Writable blob data, or NULL if failed.

[transfer none][array length=length]

Since: 0.9.2

hb_blob_get_length ()

unsigned int
hb_blob_get_length (hb_blob_t *blob);

Fetches the length of a blob's data.

Parameters

blob

a blob.

Returns

the length of blob data in bytes.

Since: 0.9.2

Types and Values

hb_blob_t

typedef struct hb_blob_t hb_blob_t;

Data type for blobs. A blob wraps a chunk of binary data and facilitates its lifecycle management between a client program and HarfBuzz.

enum hb_memory_mode_t

Data type holding the memory modes available to client programs.

Regarding these various memory-modes:

In no case shall the HarfBuzz client modify memory that is passed to HarfBuzz in a blob. If there is any such possibility, HB_MEMORY_MODE_DUPLICATE should be used such that HarfBuzz makes a copy immediately,
Use HB_MEMORY_MODE_READONLY otherwise, unless you really really really know what you are doing,
HB_MEMORY_MODE_WRITABLE is appropriate if you really made a copy of data solely for the purpose of passing to HarfBuzz and doing that just once (no reuse!),
If the font is mmap()ed, it's okay to use HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE , however, using that mode correctly is very tricky. Use HB_MEMORY_MODE_READONLY instead.

Members

HB_MEMORY_MODE_DUPLICATE	HarfBuzz immediately makes a copy of the data.
HB_MEMORY_MODE_READONLY	HarfBuzz client will never modify the data, and HarfBuzz will never modify the data.
HB_MEMORY_MODE_WRITABLE	HarfBuzz client made a copy of the data solely for HarfBuzz, so HarfBuzz may modify the data.
HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE	See above