Skip to content

Latest commit

 

History

History
396 lines (311 loc) · 17.5 KB

api-tiler.md

File metadata and controls

396 lines (311 loc) · 17.5 KB
Raw

Multi-Stream Tiler API

Tiler components perform frame-rendering from multiple-sources into a 2D grid array with one tile per source. As with all components, Tilers must be uniquely named from all other components created. Tiler components have dimensions, width and height, and a number-of-tiles expressed in rows and cols. A Tiler's dimension must be set on creation, whereas rows and cols default to 0 indicating best-fit based on the number of sources. Both dimensions and tiles can be updated after Tiler creation, even when the Tiler is currently in-use by a Pipeline. A Tiler can be called on to show a single source for an extendable time and return to show all sources on timeout.

Tiler Construction and Destruction

Tilers are constructed by calling the constructor dsl_tiler_new. As with all Pipeline Components, Tilers are deleted by calling dsl_component_delete, dsl_component_delete_many, or dsl_component_delete_all

Adding and Removing

The relationship between Pipelines/Branches and Tilers is one-to-one. Once added to a Pipeline or Branch, a Tiler must be removed before it can used with another.

Multi-Stream Tilers are added to a Pipeline by calling dsl_pipeline_component_add or dsl_pipeline_component_add_many and removed with dsl_pipeline_component_remove, dsl_pipeline_component_remove_many, or dsl_pipeline_component_remove_all.

A similar set of Services are used when adding/removing a to/from a branch: dsl_branch_component_add, dsl_branch_component_add_many, dsl_branch_component_remove, dsl_branch_component_remove_many, and dsl_branch_component_remove_all.

Adding/Removing Pad-Probe-handlers

Multiple sink and/or source Pad-Probe Handlers can be added to a Tiler by calling dsl_tiler_pph_add and removed with dsl_tiler_pph_remove.

Relevant Examples

Tiler API

Constructors

Methods

Return Values

The following return codes are used by the Tiler API

#define DSL_RESULT_TILER_RESULT                                     0x00070000
#define DSL_RESULT_TILER_NAME_NOT_UNIQUE                            0x00070001
#define DSL_RESULT_TILER_NAME_NOT_FOUND                             0x00070002
#define DSL_RESULT_TILER_NAME_BAD_FORMAT                            0x00070003
#define DSL_RESULT_TILER_THREW_EXCEPTION                            0x00070004
#define DSL_RESULT_TILER_IS_IN_USE                                  0x00070005
#define DSL_RESULT_TILER_SET_FAILED                                 0x00070006
#define DSL_RESULT_TILER_HANDLER_ADD_FAILED                         0x00070007
#define DSL_RESULT_TILER_HANDLER_REMOVE_FAILED                      0x00070008
#define DSL_RESULT_TILER_PAD_TYPE_INVALID                           0x00070009
#define DSL_RESULT_TILER_COMPONENT_IS_NOT_TILER                     0x0007000A

Constructors

dsl_tiler_new

DslReturnType dsl_tiler_new(const wchar_t* name, uint width, uint height);

The constructor creates a uniquely named Tiler with given dimensions. Construction will fail if the name is currently in use. The Tiler is created using the default rows and cols settings of 0 allowing the Tiler to select a best-fit for the number of [Sources] upstream in the Pipeline. The default values can be updated be calling dsl_tiler_tiles_set.

Parameters

  • name - [in] unique name for the Tiler to create.
  • width - [in] width of the Tiler in pixels
  • height - [in] height of the Tiler in pixels

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure

Python Example

retval = dsl_tiler_new('my-tiler', 1280, 720)

Methods

dsl_tiler_dimensions_get

DslReturnType dsl_tiler_dimensions_get(const wchar_t* name, uint* width, uint* height);

This service returns the current width and height of the named Tiler.

Parameters

  • name - [in] unique name for the Tiler to query.
  • width - [out] width of the Tiler in pixels.
  • height - [out] height of the Tiler in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure

Python Example

retval, width, height = dsl_tiler_dimensions_get('my-tiler')

dsl_tiler_dimensions_set

DslReturnType dsl_tiler_dimensions_set(const wchar_t* name, uint width, uint height);

This service sets the width and height of the named Tiler. The call will also fail if the Tiler is currently linked.

Parameters

  • name - [in] unique name for the Tiler to update.
  • width - [in] new width for the Tiler in pixels.
  • height - [in] new height for the Tiler in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure

Python Example

retval = dsl_tiler_dimensions_set('my-tiler', 1280, 720)

dsl_tiler_tiles_get

DslReturnType dsl_tiler_tiles_get(const wchar_t* name, uint* cols, uint* rows);

This service returns the current columns and rows in use by the named Tiler. Values of 0 - the default – indicate that the Tiler is using a best-fit based on the number of Sources upstream in the Pipeline.

Parameters

  • name - [in] unique name for the Tiler to query.
  • cols - [out] current columns setting for the Tiler.
  • rows - [out] current rows setting for the Tiler.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, cols, rows = dsl_tiler_tiles_get('my-tiler')

dsl_tiler_tiles_set

DslReturnType dsl_tiler_tiles_set(const wchar_t* name, uint cols, uint rows);

This service sets the number of columns and rows for the named Tiler. Once set, the values cannot be reset back to the default 0. The call will also fail if the Tiler is currently linked.

Parameters

  • name - [in] unique name for the Tiler to update.
  • cols - [in] new columns setting for the Tiler.
  • rows - [in] new rows setting for the Tiler.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_tiles_set('my-tiler', 3, 2)

dsl_tiler_frame_numbering_enabled_get

DslReturnType dsl_tiler_frame_numbering_enabled_get(const wchar_t* name,
    boolean* enabled);

This service gets the current frame-numbering enabled setting for the named Tiler. When enabled, the Tiler will add a unique frame number to each frame metatdata structure flowing over its source pad. This is to override the NVIDIA plugin's default behavior of setting the frame number to 0.

Parameters

  • name - [in] unique name for the Tiler to query.
  • enabled - [out] if true, the Tiler will add an incrementing frame number to each frame metadata structure -- for each buffer flowing over the Tiler's source pad -- overwriting the 0 value set by the NVIDIA Tiler plugin.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, enabled = dsl_tiler_frame_numbering_enabled_get('my-tiler')

dsl_tiler_frame_numbering_enabled_set

DslReturnType dsl_tiler_frame_numbering_enabled_set(const wchar_t* name,
    boolean enabled);

This service sets the frame-numbering enabled setting for the named Tiler. When enabled, the Tiler will add a unique frame number to each frame metatdata structure flowing over its source pad. This is to override the NVIDIA plugin's default behavior of setting the frame number to 0.

Parameters

  • name - [in] unique name for the Tiler to update.
  • enabled - [in] set to true to have the Tiler add an incrementing frame number to each frame metadata structure -- for each buffer flowing over the Tiler's source pad -- overwriting the 0 value set by the NVIDIA Tiler plugin.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_frame_numbering_enabled_set('my-tiler', True)

dsl_tiler_source_show_get

DslReturnType dsl_tiler_source_show_get(const wchar_t* name, 
    const wchar_t** source, uint* timeout);

This service get the current show-source parameters for the named Tiler. The service returns DSL_TILER_ALL_SOURCES (equal to NULL) to indicate that all sources are shown

Parameters

  • name - [in] unique name for the Tiler to update.
  • source - [out] unique name of the current source show. DSL_TILER_ALL_SOURCES (equal to NULL) indicates that all sources are shown (default).
  • timeout - [out] the remaining number of seconds that the current source will be shown for. A value of 0 indicates show indefinitely (default).

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval, current_source, timeout = dsl_tiler_source_show_get('my-tiler')

dsl_tiler_source_show_set

DslReturnType dsl_tiler_source_show_set(const wchar_t* name, 
    const wchar_t* source, uint timeout, boolean has_presedence);

This service sets the current show-source parameter for the named Tiler to show a single Source. The service will fail if the Source name is not found. The timeout parameter controls how long the single Source will be show.

Calling dsl_tiler_source_show_set with the same source name as currently show will adjust the remaining time to the newly provided timeout value.

Calling dsl_tiler_source_show_set with a different source name than currently show will switch to the new source, while applying the new timeout, if:

  1. the current source setting is set to DSL_TILER_ALL_SOURCES
  2. the has_precedence parameter is set to True

Note: It's advised to set the has_precedence value to False when controlling the show-source setting with an ODE Action as excessive switching may occur. Set to True when calling from a client key or mouse-button callback for immediate control.

Parameters

  • name - [in] unique name for the Tiler to update.
  • source - [in] unique name of the source to show. The service will fail if the Source is not found
  • timeout - [in] the number of seconds that the current source will be shown for. A value of 0 indicates show indefinitely.
  • has_precedence - [in] set to true to give this call precedence over the current setting, false to switch only if another source is not currently shown.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_source_show_set('my-tiler', 'camera-2', 10, True)

dsl_tiler_source_show_select

DslReturnType dsl_tiler_source_show_select(const wchar_t* name, 
    int x_pos, int y_pos, uint window_width, uint window_height, uint timeout);

This service sets the current show-source parameter for the named Tiler to show a single Source based on positional selection. The timeout parameter controls how long the single Source will be show.

Calling dsl_tiler_source_show_select when a single source is currently shown sets the tiler to show all sources.

Parameters

  • name - [in] unique name for the Tiler to update.
  • timeout - [in] the remaining number of seconds that the current source will be shown for. A value of 0 indicates show indefinitely.
  • x_pos - [in] relative to the given window_width.
  • y_pos - [in] relative to the given window_height
  • window_width - [in] width of the window the x and y positional coordinates are relative to
  • window_height - [in] height of the window the x and y positional coordinates are relative to

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

dsl_tiler_source_show_select('tiler', x_pos, y_pos, WINDOW_WIDTH, WINDOW_HEIGHT, SHOW_SOURCE_TIMEOUT)

dsl_tiler_source_show_cycle

DslReturnType dsl_tiler_source_show_cycle(const wchar_t* name, uint timeout);

This service enables the named Tiler to cycle through all sources showing each one for a specified time before showing the next. This services will fail with DSL_RESULT_TILER_SET_FAILED if the provided timeout is 0.

Parameters

  • name - [in] unique name for the Tiler to update.
  • timeout - [in] time to display each source before moving to the next in units of seconds

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_source_show_cycle('my-tiler', 4)

dsl_tiler_source_show_all

DslReturnType dsl_tiler_source_show_all(const wchar_t* name);

This service sets the current show-source setting for the named Tiler to DSL_TILER_ALL_SOURCES. The service always has precedence over any single source show.

Parameters

  • name - [in] unique name for the Tiler to update.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_source_show_all('my-tiler')

dsl_tiler_pph_add

DslReturnType dsl_tiler_pph_add(const wchar_t* name, const wchar_t* handler, uint pad);

This service adds a Pad Probe Handler to either the Sink or Source pad of the named Tiler.

Parameters

  • name - [in] unique name of the Tiler to update.
  • handler - [in] unique name of Pad Probe Handler to add
  • pad - [in] to which of the two pads to add the handler: DSL_PAD_SIK or DSL_PAD SRC

Returns

  • DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_pph_add('my-tiler', 'my-pph-handler', `DSL_PAD_SINK`)

dsl_tiler_pph_remove

DslReturnType dsl_tiler_pph_remove(const wchar_t* name, const wchar_t* handler, uint pad);

This service removes a Pad Probe Handler from either the Sink or Source pad of the named Tiler. The service will fail if the named handler is not owned by the Tiler

Parameters

  • name - [in] unique name of the Tiler to update.
  • handler - [in] unique name of Pad Probe Handler to remove
  • pad - [in] to which of the two pads to remove the handler from: DSL_PAD_SIK or DSL_PAD SRC

Returns

  • DSL_RESULT_SUCCESS on successful remove. One of the Return Values defined above on failure.

Python Example

retval = dsl_tiler_pph_remove('my-tiler', 'my-pph-handler', `DSL_PAD_SINK`)

API Reference