thorvg_python.engine¶

class thorvg_python.engine.Engine(thorvg_lib_path: str | None = None, engine_method: EngineBackend = EngineBackend.SW, threads: int = 0)¶

Bases: object

Engine API

A module enabling initialization and termination of the TVG engines.

accessor_generate_id(name: str) → int¶

Generate a unique ID (hash key) from a given name.

This function computes a unique identifier value based on the provided string. You can use this to assign a unique ID to the Paint object.

Parameters:¶

name : str¶

The input string to generate the unique identifier from.

Returns:¶

The generated unique identifier value.

Return type:¶

int

Note

Experimental API

font_load(path: str) → Result¶

Loads a scalable font data from a file.

ThorVG efficiently caches the loaded data using the specified path as a key. This means that loading the same file again will not result in duplicate operations; instead, ThorVG will reuse the previously loaded font data.

Parameters:¶

path : str¶

The path to the font file.

Returns:¶

• INVALID_ARGUMENT An invalid path passed as an argument.

• NOT_SUPPORTED When trying to load a file with an unknown extension.

Return type:¶

Result

See also

Engine.font_unload()

Added in version 0.15.

font_load_data(name: str, data: bytes, mimetype: str | None, copy: bool) → Result¶

Loads a scalable font data from a memory block of a given size.

ThorVG efficiently caches the loaded font data using the specified name as a key. This means that loading the same fonts again will not result in duplicate operations. Instead, ThorVG will reuse the previously loaded font data.

Parameters:¶

name : str¶

The name under which the font will be stored and accessible (e.x. in a tvg_text_set_font API).

data : bytes¶

A pointer to a memory location where the content of the font data is stored.

mimetype : str¶

Mimetype or extension of font data. In case a None or an empty “” value is provided the loader will be determined automatically.

copy : bool¶

If true the data are copied into the engine local buffer, otherwise they are not (default).

Returns:¶

• INVALID_ARGUMENT If no name is provided or if size is zero while data points to a valid memory location.

• NOT_SUPPORTED When trying to load a file with an unknown extension.

• INSUFFICIENT_CONDITION When trying to unload the font data that has not been previously loaded.

Return type:¶

Result

Warning

: It’s the user responsibility to release the data memory.

Note

To unload the font data loaded using this API, pass the proper name and nullptr as data.

Added in version 0.15.

font_unload(path: str) → Result¶

Unloads the specified scalable font data that was previously loaded.

This function is used to release resources associated with a font file that has been loaded into memory.

Parameters:¶

path : str¶

The path to the loaded font file.

Returns:¶

INSUFFICIENT_CONDITION The loader is not initialized.

Return type:¶

Result

Note

If the font data is currently in use, it will not be immediately unloaded.

See also

Engine.font_load()

Added in version 0.15.

init(engine_method: EngineBackend, threads: int) → Result¶

Initializes TVG engines.

TVG requires the running-engine environment. TVG runs its own task-scheduler for parallelizing rendering tasks efficiently. You can indicate the number of threads, the count of which is designated threads. In the initialization step, TVG will generate/spawn the threads as set by threads count.

from thorvg_python import Engine
engine = Engine.init(EngineBackend.SW, 0);  //Initialize software renderer and use the main thread only

Parameters:¶

engine_method : EngineBackend¶

The engine types to initialize. This is relative to the Canvas types, in which it will be used. For multiple backends bitwise operation is allowed. - SW: CPU rasterizer - GL: OpenGL rasterizer (not supported yet)

threads : int¶

The number of additional threads used to perform rendering. Zero indicates only the main thread is to be used.

Returns:¶

• INVALID_ARGUMENT Unknown engine type.

• NOT_SUPPORTED Unsupported engine type.

Return type:¶

Result

Note

The Initializer keeps track of the number of times it was called. Threads count is fixed at the first init() call.

See also

Engine.term()

See also

EngineBackend

term(engine_method: EngineBackend | None = None) → Result¶

Terminates TVG engines.

It should be called in case of termination of the TVG client with the same engine types as were passed when tvg_engine_init() was called.

from thorvg_python import Engine
engine = Engine()
//define canvas and shapes, update shapes, general rendering calls
engine.tvg_engine_term()

Parameters:¶

engine_method : Optional[EngineBackend]¶

The engine types to terminate. This is relative to the Canvas types, in which it will be used. For multiple backends bitwise operation is allowed. If None is passed, all engine types will be terminated - SW: CPU rasterizer - GL: OpenGL rasterizer (not supported yet)

Returns:¶

• INSUFFICIENT_CONDITION Nothing to be terminated.

• INVALID_ARGUMENT Unknown engine type.

• NOT_SUPPORTED Unsupported engine type.

Return type:¶

Result

See also

Engine.init()

See also

EngineBackend

version() → tuple[Result, int, int, int, str | None]¶

Retrieves the version of the TVG engine.

Returns:¶

SUCCESS

Return type:¶

Result

Returns:¶

A major version number.

Return type:¶

int

Returns:¶

A minor version number.

Return type:¶

int

Returns:¶

A micro version number.

Return type:¶

int

Returns:¶

The version of the engine in the format major.minor.micro, or a nullptr in case of an internal error.

Return type:¶

Optional[str]

Added in version 0.15.