# viewer.h ## Index
`tm_viewer_render_callback_f`
`tm_viewer_gather_shader_data_callback_f`
`tm_viewer_gather_render_callback_f`
`struct tm_viewer_camera_t`
`tm_viewer_gather_camera_settings_callback_f`
`enum tm_viewer_camera_settings`
`struct tm_viewer_render_args_t`

`struct tm_viewer_render_args_provider_i`
`entity_ctx`
`user_data`
`render_args()`

`tm_viewer_render_args_provider_i_version`
`struct tm_viewer_render_info_t`
`tm_viewer_o`

`struct tm_viewer_api`
`request_render()`
`get_color_space()`
`pipeline()`
`reset_render_pipeline()`
`set_render_pipeline_api()`
`screenshot()`
`init_vr()`
`id()`

`tm_viewer_api_version`
`tm_viewer_manager_o`

`struct tm_viewer_manager_api`
`create_manager()`
`destroy_manager()`
`create()`
`destroy()`
`viewers()`
`render()`

`tm_viewer_manager_api_version`
## API
### `tm_viewer_render_callback_f`
~~~c typedef void tm_viewer_render_callback_f(void *inst, const struct tm_render_args_t *args); ~~~
### `tm_viewer_gather_shader_data_callback_f`
~~~c typedef void tm_viewer_gather_shader_data_callback_f(void *inst, struct tm_ci_shader_data_gather_callback_args_t *args); ~~~
### `tm_viewer_gather_render_callback_f`
~~~c typedef void tm_viewer_gather_render_callback_f(void *inst, struct tm_ci_render_gather_callback_args_t *args); ~~~
### `struct tm_viewer_camera_t`
~~~c typedef struct tm_viewer_camera_t { tm_transform_t tm; const struct tm_camera_settings_t *camera; } tm_viewer_camera_t; ~~~
### `tm_viewer_gather_camera_settings_callback_f`
~~~c typedef void tm_viewer_gather_camera_settings_callback_f(void *inst, struct tm_viewer_camera_t *camera); ~~~
### `enum tm_viewer_camera_settings`
~~~c typedef enum tm_viewer_camera_settings { // Use camera parameters passed in `camera` struct. TM_VIEWER_CAMERA_SETTINGS_IMMEDIATE = 0, // Gather camera settings by calling the callback tm_viewer_gather_camera_settings_callback_f TM_VIEWER_CAMERA_SETTINGS_CALLBACK, } tm_viewer_camera_settings; ~~~
### `struct tm_viewer_render_args_t`
~~~c typedef struct tm_viewer_render_args_t { // ** Required ** tm_viewer_camera_settings camera_settings; TM_PAD(4); union { struct { // Callback function to camera settings tm_viewer_gather_camera_settings_callback_f *gather_camera_settings_callback; void *gather_camera_settings_callback_inst; }; tm_viewer_camera_t camera; }; // Specifies which render pipeline API to use for rendering the viewer. struct tm_render_pipeline_vt *render_pipeline_api; // Defines the color space of the output target. // Linear sRGB is assumed if NULL. struct tm_color_space_desc_t *target_color_space; // Defines the format to use for the output target. // R8G8B8A8_UNORM is assumed if zero. uint32_t target_color_space_format; // Simulation speed multiplier. float simulation_speed; // The state into which the render target should be transitioned into after being rendered into. uint16_t final_target_resource_state; TM_PAD(2); // Wanted render viewer resolution. uint32_t target_width; uint32_t target_height; TM_PAD(4); // *** API REVIEW *** // Should be called visibility mask, not flags // ** Optional ** // Requested editor visibility uint64_t editor_visibility_flags; // True if we should render with native resolution. bool native_resolution; TM_PAD(7); // Optional, set if RenderDoc capture is supported. struct tm_renderdoc_toolbar_args_t *renderdoc_args; // Wanted GPU to use for rendering. uint32_t wanted_gpu; // The resource to capture into, i.e. we want to capture into something else that the // render target that is created by default. tm_renderer_handle_t capture_target_resource; // If `capture_target_resource` is a multi-surface resource, then this specifies which surface // to capture into. uint32_t capture_target_resource_surface; // The state `capture_target_resource` is in. uint16_t capture_target_resource_state; TM_PAD(2); // Callback function to render actual objects. tm_viewer_render_callback_f *render_callback; void *render_callback_inst; // Callback function to gather shader data tm_viewer_gather_shader_data_callback_f *gather_shader_data_callback; void *gather_shader_data_callback_inst; // Callback function to gather render component interfaces tm_viewer_gather_render_callback_f *gather_render_callback; void *gather_render_callback_inst; // Should be specified if the viewer wants to use GPU picking. struct tm_gpu_picking_o *gpu_picking; } tm_viewer_render_args_t ~~~
### `struct tm_viewer_render_args_provider_i`
This interface can be implemented when you have an entity ctx that can provide viewer render args. This is often used to capture cubemaps etc but you don't know what render args are. #### `entity_ctx` ~~~c struct tm_entity_context_o *entity_ctx; ~~~ #### `user_data` ~~~c void *user_data; ~~~ #### `render_args()` ~~~c void (*render_args)(void *user_data, struct tm_viewer_render_args_t *args); ~~~
### `tm_viewer_render_args_provider_i_version`
~~~c #define tm_viewer_render_args_provider_i_version TM_VERSION(1, 0, 0) ~~~
### `struct tm_viewer_render_info_t`
~~~c typedef struct tm_viewer_render_info_t { // The width of the primary color target. uint32_t target_width; // The height of the primary color target. uint32_t target_height; uint32_t vr_context; // The state color_targets[0] was in. uint16_t color_target_state; TM_PAD(2); // colors_targets[0] is the main target of the viewer rendering. In case `vr_context` is // non-zero, then then two targets are the left and right eye. tm_renderer_handle_t color_targets[2]; // The image description of the target const struct tm_renderer_image_desc_t *color_target_desc; const struct tm_camera_t *camera; struct tm_render_pipeline_i *render_pipeline; } tm_viewer_render_info_t; ~~~
### `tm_viewer_o`
~~~c typedef struct tm_viewer_o tm_viewer_o; ~~~
### `struct tm_viewer_api`
A Viewer is something that can gather rendering data, render it into a render target and then transition the render target into a state that can be drawn into the UI. It is used to create viewports within The Machinery. Usually, the tab that wants a viewer will create it (`tm_viewer_manager_api`:`create`) and then once per frame the tab will call `request_render` along with callbacks that specify what to actually render. The return value of `request_render` will be the render resource into which the viewer will render. The tab can then assign this render resource to a GUI texture (see the `tm_ui_renderer_api`:`set_image`). In the main loop of the application, `tm_viewer_manager_api`:`render` should be called, it will loop over all viewers that have requested to be rendered and asynchronously render them. `tick` will also transition the resources into the whatever resource state the user specified when calling `request_render` (using the parameter `final_target_resource_state`), making it ready for the next operation, such as being read when drawn into the UI. #### `request_render()` ~~~c tm_renderer_handle_t (*request_render)(tm_viewer_o *viewer, const tm_viewer_render_args_t *args, tm_viewer_render_info_t *info, struct tm_renderer_resource_command_buffer_o *res_buf, struct tm_renderer_command_buffer_o *cmd_buf); ~~~ Should be called once per frame by the code that wishes to render into the viewer. Fill out `args` with arguments such as camera transform, render pipeline API, callbacks for gathering render data etc. It is specified in the comments within `tm_viewer_render_args_t` which fields that are required. `info` will be filled out by the function. Return value is the render resource into which the viewer will render. Note that no actual rendering happens until `tm_viewer_manager_api`:`render` is called. Threading: Internally synchronized. #### `get_color_space()` ~~~c const struct tm_color_space_desc_t *(*get_color_space)(const tm_viewer_o *viewer); ~~~ Gets the color space last used by the viewer. By default this is sRGB. #### `pipeline()` ~~~c struct tm_render_pipeline_i *(*pipeline)(tm_viewer_o *viewer); ~~~ Returns the pipeline which the viewer uses for rendering. Threading: Thread-safe. #### `reset_render_pipeline()` ~~~c void (*reset_render_pipeline)(tm_viewer_o *viewer); ~~~ Destroys the render pipeline, ensuring that it is recreated next time it is needed. Threading: Thread-safe. #### `set_render_pipeline_api()` ~~~c void (*set_render_pipeline_api)(tm_viewer_o *viewer, struct tm_render_pipeline_vt *pipeline_api); ~~~ Destroys and previous render pipeline and sets `pipeline_api` as the new pipeline API to use. Threading: Thread-safe. #### `screenshot()` ~~~c void (*screenshot)(tm_viewer_o *viewer); ~~~ Saves a screenshot of viewer contents. Will pop up a modal dialog asking the user where to save it. TODO: Make this less hard coded? Threading: Thread-safe. #### `init_vr()` ~~~c void (*init_vr)(tm_viewer_o *viewer, bool activate); ~~~ Sets this viewer up for VR usage, uses the OpenVR library internally. Set `activate` to `true` in order to initialize the VR mode, and `false` to shut it down. Threading: Internally synchronized. #### `id()` ~~~c uint64_t (*id)(const tm_viewer_o *viewer); ~~~ Gets the unique indentifier for the viewer.
### `tm_viewer_api_version`
~~~c #define tm_viewer_api_version TM_VERSION(1, 0, 0) ~~~
### `tm_viewer_manager_o`
~~~c typedef struct tm_viewer_manager_o tm_viewer_manager_o; ~~~
### `struct tm_viewer_manager_api`
The Viewer Manager stores a list of all viewers. Normally you'd have one viewer manager per application. It comes with functions to create new viewers and also efficiently render all viewers that have requested to be rendered. #### `create_manager()` ~~~c tm_viewer_manager_o *(*create_manager)(struct tm_allocator_i *allocator, struct tm_renderer_backend_i *render_backend, struct tm_shader_repository_o *shader_repository, uint32_t main_device_affinity, struct tm_visibility_context_o *default_visibility_context, uint64_t viewport_visibility_flag); ~~~ Creates a new Viewer Manager. Normally you'd do this once at application start-up. #### `destroy_manager()` ~~~c void (*destroy_manager)(tm_viewer_manager_o *manager, struct tm_renderer_resource_command_buffer_o *res_buf); ~~~ Destroys a Viewer Manager, and all viewers created using it (i.e. you don't need to call destroy on each viewer at application shutdown). #### `create()` ~~~c tm_viewer_o *(*create)(tm_viewer_manager_o *manager, const char *main_module_name); ~~~ Creates a new Viewer. The viewer will use the rendering pipeline specified by `render_pipeline_api`. Threading: Internally synchronized. #### `destroy()` ~~~c void (*destroy)(tm_viewer_manager_o *manager, tm_viewer_o *viewer, struct tm_renderer_resource_command_buffer_o *res_buf); ~~~ Destoys a Viewer. Call this when you close a tab that contains a Viewer. You don't need to call this on application shutdown, `destroy_manager` will destroy all existing viewers. Threading: Internally synchronized. #### `viewers()` ~~~c tm_viewer_o **(*viewers)(tm_viewer_manager_o *manager, bool **active); ~~~ Returns a `carray` of all existing viewers within the manager. Optionally returns whether each viewer was `active` during the last `tm_viewer_manager_api->render()` call. Threading: Externally synchronized. #### `render()` ~~~c void (*render)(tm_viewer_manager_o *manager, const struct tm_shader_system_context_o *shader_context, const struct tm_the_truth_o *tt, const struct tm_render_pipeline_update_frame_parameters_t *frame_params); ~~~ Renders all viewers that have requested to be rendered into their render targets and transitions their resources to their final state (specified by parameter final_target_resource_state passed to `request_render`). Threading: Externally synchronized.
### `tm_viewer_manager_api_version`
~~~c #define tm_viewer_manager_api_version TM_VERSION(2, 0, 0) ~~~