# ui_renderer.h ## Overview
Small helper API for rendering user interfaces (`tm_ui_o`) using The Machinery's renderer. Also responsible for generating and managing `tm_font_t`, used to draw fonts in the UI. Threading: Calls to the API when operating on the same `tm_ui_renderer_o` must be externally synchronized.
## Index
`struct tm_font_provider_t`
`TM_FONT_PROVIDER_INTERFACE_NAME`
`tm_font_provider_f`
`TM_FONT_PROVIDER_FUNCTION_INTERFACE_NAME`
`struct tm_font_request_glyphs_t`
`TM_FONT_REQUEST_GLYPH_INTERFACE_NAME`
`struct tm_added_font_t`
`enum tm_ui_canvas_type`
`struct tm_ui_canvas_t`
`tm_ui_renderer_o`

`struct tm_ui_renderer_api`
`create()`
`destroy()`
`render()`
`default_font()`
`custom_font()`
`add_all_font_providers()`
`allocate_image_slot()`
`set_image()`

`TM_UI_RENDERER_API_NAME`
## API
### `struct tm_font_provider_t`
Interface that can be used to provide additional fonts to The Machinery (usually The Machinery is only set up with the default font). The code that sets up the `tm_ui_renderer_api` will typically call `add_all_font_providers()` to set up all the `tm_font_provider_t` interfaces in the UI. The fonts can then be used with `tm_ui_api->font()`. If you want multiple sizes of the same font, you should implement a `tm_font_provider_t` for each size. ~~~c typedef struct tm_font_provider_t { // ID uniquely identifying this font, typically a hash of the font name. tm_strhash_t font_id; // Font size that should be rendered out. Default font size for The Machinery Editor is 9 // points. You should use this unless you use the font specifically to render out large icons. uint32_t font_size; TM_PAD(4); // Descriptor that describes the font. const struct tm_font_descriptor_t *descriptor; } tm_font_provider_t; ~~~
### `TM_FONT_PROVIDER_INTERFACE_NAME`
~~~c #define TM_FONT_PROVIDER_INTERFACE_NAME "tm_font_provider_t" ~~~ Interface name used to register and query the `tm_api_registry_api` for `tm_font_provider_t` interfaces.
### `tm_font_provider_f`
~~~c typedef const tm_font_provider_t *tm_font_provider_f(struct tm_temp_allocator_i *ta); ~~~ Interface similar to `tm_font_provider_t`, excepts the fonts are provided by a callback function that returns a number of `tm_font_provider_t` as a `carray.inl`. Just as with `tm_font_provider_t`, these fonts will be added by `add_all_font_providers()`.
### `TM_FONT_PROVIDER_FUNCTION_INTERFACE_NAME`
~~~c #define TM_FONT_PROVIDER_FUNCTION_INTERFACE_NAME "tm_font_provider_f" ~~~ Interface name used to register and query the `tm_api_registry_api` for `tm_font_provider_f` interfaces.
### `struct tm_font_request_glyphs_t`
Interface that can be used to request certain glyphs from a font. When we generate the textures for a font, we will enumerate all matching `tm_font_request_glyphs_t` interfaces and add the glyphs requested by them to the font's glyph list. This can be used by a plugin to request certain glyphs. For example, a localization plugins may request glyphs for characters needed by the target language. Note that if a font is rendered out in multiple sizes, the glyphs added using `tm_font_request_glyphs_t` will be added to all font sizes. !!! TODO: API-REVIEW Should there be a mechanism for requesting specific glyphs in specific font sizes of an existing font? I.e., should someone be able to be request: I want just the copyright symbol, rendered out in 32px, from the Arial font (which is defined elsewhere). ~~~c typedef struct tm_font_request_glyphs_t { // ID of the font that glyphs are requested from. The ID is typically the hash of the font name. // A value of 0 means the default font. tm_strhash_t font_id; // Number of glyph ranges requested. uint32_t num_ranges; TM_PAD(4); // Glyph ranges. Each range item consist of a starting glyph and a count. const struct tm_ttf_range_t *ranges; } tm_font_request_glyphs_t; ~~~
### `TM_FONT_REQUEST_GLYPH_INTERFACE_NAME`
~~~c #define TM_FONT_REQUEST_GLYPH_INTERFACE_NAME "tm_font_request_glyphs_t" ~~~ Interface name used to register and query the `tm_api_registry_api` for `tm_font_request_glyphs_t` interfaces.
### `struct tm_added_font_t`
Represents a font added to the `tm_ui_renderer_api` using `add_all_font_providers()`. ~~~c typedef struct tm_added_font_t { // ID identifying this font. tm_strhash_t font_identifier; // Size of the font. uint32_t font_size; TM_PAD(4); // Font representation. const struct tm_font_t *font; } tm_added_font_t; ~~~
### `enum tm_ui_canvas_type`
~~~c enum tm_ui_canvas_type { TM_UI_CANVAS_SCREEN_SPACE, TM_UI_CANVAS_WORLD_SPACE }; ~~~
### `struct tm_ui_canvas_t`
~~~c typedef struct tm_ui_canvas_t { enum tm_ui_canvas_type type; float dpi_scale_factor; tm_rect_t rect; tm_transform_t transform; tm_mat44_t cam_view; tm_mat44_t cam_projection; } tm_ui_canvas_t; ~~~
### `tm_ui_renderer_o`
~~~c typedef struct tm_ui_renderer_o tm_ui_renderer_o; ~~~ Object that represents a UI renderer.
### `struct tm_ui_renderer_api`
API for the UI rendrerer. #### `create()` ~~~c struct tm_ui_renderer_o *(*create)(struct tm_renderer_resource_command_buffer_o *res_buf, struct tm_shader_repository_o *shader_repository, struct tm_allocator_i *allocator, uint32_t device_affinity); ~~~ Creates a new `tm_ui_renderer_o`. #### `destroy()` ~~~c void (*destroy)(tm_ui_renderer_o *ui_renderer, struct tm_renderer_resource_command_buffer_o *res_buf); ~~~ Destroys a previously created `tm_ui_renderer_o`. #### `render()` ~~~c void (*render)(tm_ui_renderer_o *ui_renderer, struct tm_ui_o *ui, const tm_ui_canvas_t *canvas, uint64_t sort_key, struct tm_renderer_resource_command_buffer_o *res_buf, struct tm_renderer_command_buffer_o *cmd_buf); ~~~ Renders the specified `tm_ui_o` and writes any necessary commands to `res_buf` and `cmd_buf`. `render_target_resolution` should specify the width and height of the render target that the ui targetting. `dpi_scale_factor` should specify the scale factor for the display that will show the render target. Threading: Externally synchronized. #### `default_font()` ~~~c const struct tm_font_t *(*default_font)(tm_ui_renderer_o *ui_renderer, uint32_t font_size, float window_dpi, struct tm_renderer_resource_command_buffer_o *res_buf); ~~~ Returns a `tm_font_t` for the default platform font with font `size` and `window_dpi`. If the `(size, window_dpi)` combination doesn't exist, it will be generated. This could be an expensive operation, so you might want to perform it on a background thread. Threading: Externally synchronized. #### `custom_font()` ~~~c const struct tm_font_t *(*custom_font)(tm_ui_renderer_o *ui_renderer, tm_strhash_t font_id, const struct tm_font_descriptor_t *desc, uint32_t font_size, float window_dpi, struct tm_renderer_resource_command_buffer_o *res_buf); ~~~ Returns a `tm_font_t` for the font identified by the unique identifier `font_id` (typically a hash of the font name) and the descriptor `desc` with font `size` and `window_dpi`. If the `(font_id, size, window_dpi)` combination doesn't exist, it will be generated. This could be an expensive operation, so you might want to perform it on a background thread. Threading: Externally synchronized. #### `add_all_font_providers()` ~~~c tm_added_font_t *(*add_all_font_providers)(tm_ui_renderer_o *ui_renderer, float window_dpi, struct tm_renderer_resource_command_buffer_o *res_buf, struct tm_temp_allocator_i *ta); ~~~ Adds all `TM_FONT_PROVIDER_INTERFACE_NAME` implementations to the UI renderer and returns a `carray.inl` of the added fonts. The caller should call `tm_ui_api->add_font()` on the returned values to add them to the UI. #### `allocate_image_slot()` ~~~c uint32_t (*allocate_image_slot)(tm_ui_renderer_o *ui_renderer); ~~~ Allocates an image slot and returns its index. Use `set_image()` to bind an image handle to the returned slot. Threading: Internally synchronized. #### `set_image()` ~~~c void (*set_image)(tm_ui_renderer_o *ui_renderer, uint32_t slot, tm_renderer_handle_t image_handle); ~~~ Binds an image handle to the specified slot. Threading: Thread-safe.
### `TM_UI_RENDERER_API_NAME`
~~~c #define TM_UI_RENDERER_API_NAME "tm_ui_renderer" ~~~