|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
Options for SwTimelineStartEx(). More...
#include "timelineapi.h"
Data Fields | |
| size_t | size |
| int32 | can_prolong |
| HqBool | progress_monotonic |
| HqBool | progress_clamped |
| uint32 | progress_throttle_uS |
| uint32 | progress_not_suppressed |
Options for SwTimelineStartEx().
Option values are arranged where possible so that the default behaviour happens with a zero value. It is still advisable to initialise auto/static options variables using the SW_TL_OPTIONS_INIT initialiser, and then override the fields of interest.
| int32 sw_tl_options::can_prolong |
Can this timeline be prolonged by event handler objections? Prolonging a timeline assumes that it can have dynamic scope. If the timeline is modelling a function or has context data associated with it that has static scope, prolonging a timeline could result in events being sent with context data that has been invalidated. This option determines whether a timeline can permit extension beyond the request to end or abort. The default value is inherited from the timeline's parent, if there is one, or is SW_TL_PROLONG_AUTO otherwise. It is an error to create a timeline which explicitly disallows prolonging if the parent timeline permits it, however only timelines created with SW_TL_PROLONG_TRUE can be objected to by event handlers.
| HqBool sw_tl_options::progress_clamped |
Is progress clamped to the extent? If this is TRUE, then updates to the progress that exceed the extent of the timeline are silently ignored. If FALSE, then progress updates that exceed the extent will automatically extend the extend. The default value is FALSE.
| HqBool sw_tl_options::progress_monotonic |
Is progress monotonic? If this is TRUE, then updates to the start or end of the extent or progress of the timeline that are retrograde are silently ignored. Normally, this means that values for the start and end extent and progress can only be increased. However, timelines can be created with the start value greater than the end value (for example, a countdown timer): in this case the values can only be decreased. The extents are permitted to go from indeterminate to a bounded value, but not to revert to indeterminate thereafter. The default value is FALSE.
| uint32 sw_tl_options::progress_not_suppressed |
Which progress messages are not suppressed? Normally, timeline progress events are suppressed if they do not change the progress counter value. Setting these option bits allows finer control over whether event messages are suppressed if the progress is updated to the start of the timeline extent, the end of the timeline extent, somewhere in between, as well as an option to allow the first progress update to be issued regardless whether it is at the start, end or in between. This can be useful for timeline protocols where the timeline is created in advance of work being done on it: an initial progress update to the start of the timeline can be used to indicate the start of work on the timeline's process.
| uint32 sw_tl_options::progress_throttle_uS |
Minimum time between event message updates for progress or extend, in microseconds. If this is non-zero, then the event messages for progress and extent updates occurring too soon after a previous update will be suppressed. The timeline progress and extent counters will be modified, but the event message will not be issued. Note that when throttling progress messages, the client should be prepared to handle both progress and extent changes in either message; an extent change may be suppressed that becomes visible in a subsequent progress message; or vice-versa. Suppressed messages will not be automatically issued when the interval expires; a timeline progress update is still required to trigger an event message after the suppression interval has expired. If a timeline is ended or aborted and the last progress update was suppressed, a progress or extent event message will be issued immediately before the timeline end or abort event message. In this case, handlers will receive an EVENT_TIMELINE_PROGRESS message if the progress changed (even if the extent also changed), or an EVENT_TIMELINE_EXTEND message if just the extent changed. Progress messages will not be suppressed if the progress is updated to the start or end of a timeline with a clamped extent (one that does not automatically extend the timeline). Extend messages will not be suppressed if the extent changes from indeterminate to determinate.
| size_t sw_tl_options::size |
Size of this structure. This must be set correctly so that parameters for new versions of the Timeline API will be set to sensible default values if linked with older clients.