The VdpPresentationQueue manages a queue of surfaces and associated timestamps. For each surface in the queue, once the associated timestamp is reached, the surface is displayed to the user. This timestamp-based approach yields high quality video delivery. More...
Typedefs | |
| typedef uint64_t | VdpTime |
| The representation of a point in time. More... | |
| typedef uint32_t | VdpPresentationQueueTarget |
| An opaque handle representing the location where video will be presented. More... | |
| typedef VdpStatus | VdpPresentationQueueTargetDestroy(VdpPresentationQueueTarget presentation_queue_target) |
| Destroy a VdpPresentationQueueTarget. More... | |
| typedef uint32_t | VdpPresentationQueue |
| An opaque handle representing a presentation queue object. More... | |
| typedef VdpStatus | VdpPresentationQueueCreate(VdpDevice device, VdpPresentationQueueTarget presentation_queue_target, VdpPresentationQueue *presentation_queue) |
| Create a VdpPresentationQueue. More... | |
| typedef VdpStatus | VdpPresentationQueueDestroy(VdpPresentationQueue presentation_queue) |
| Destroy a VdpPresentationQueue. More... | |
| typedef VdpStatus | VdpPresentationQueueSetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *const background_color) |
| Configure the background color setting. More... | |
| typedef VdpStatus | VdpPresentationQueueGetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *background_color) |
| Retrieve the current background color setting. More... | |
| typedef VdpStatus | VdpPresentationQueueGetTime(VdpPresentationQueue presentation_queue, VdpTime *current_time) |
| Retrieve the presentation queue's "current" time. More... | |
| typedef VdpStatus | VdpPresentationQueueDisplay(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, uint32_t clip_width, uint32_t clip_height, VdpTime earliest_presentation_time) |
| Enter a surface into the presentation queue. More... | |
| typedef VdpStatus | VdpPresentationQueueBlockUntilSurfaceIdle(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, VdpTime *first_presentation_time) |
| Wait for a surface to finish being displayed. More... | |
| typedef VdpStatus | VdpPresentationQueueQuerySurfaceStatus(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, VdpPresentationQueueStatus *status, VdpTime *first_presentation_time) |
| Poll the current queue status of a surface. More... | |
Enumerations | |
| enum | VdpPresentationQueueStatus { VDP_PRESENTATION_QUEUE_STATUS_IDLE, VDP_PRESENTATION_QUEUE_STATUS_QUEUED, VDP_PRESENTATION_QUEUE_STATUS_VISIBLE } |
| The status of a surface within a presentation queue. More... | |
Detailed Description
The VdpPresentationQueue manages a queue of surfaces and associated timestamps. For each surface in the queue, once the associated timestamp is reached, the surface is displayed to the user. This timestamp-based approach yields high quality video delivery.
The exact location of the displayed content is Window System specific. For this reason, the Window System Integration Layer provides an API to create a VdpPresentationQueueTarget object (e.g. via VdpPresentationQueueTargetCreateX11) which encapsulates this information.
Note that the presentation queue performs no scaling of surfaces to match the display target's size, aspect ratio, etc.
Surfaces that are too large to fit into the display target will be clipped. Surfaces that are too small to fill the display target will be aligned to the top-left corner of the display target, with the balance of the display target being filled with a constant configurable "background" color.
Note that the presentation queue operates in a manner that is semantically equivalent to an overlay surface, with any required color key painting hidden internally. However, implementations are free to use whatever semantically equivalent technique they wish. Note that implementations that actually use color-keyed overlays will typically use the "background" color as the overlay color key value, so this color should be chosen with care.
Typedef Documentation
◆ VdpPresentationQueue
| typedef uint32_t VdpPresentationQueue |
An opaque handle representing a presentation queue object.
◆ VdpPresentationQueueBlockUntilSurfaceIdle
| typedef VdpStatus VdpPresentationQueueBlockUntilSurfaceIdle(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, VdpTime *first_presentation_time) |
Wait for a surface to finish being displayed.
- Parameters
-
[in] presentation_queue The queue to query. [in] surface The surface to wait for. [out] first_presentation_time The timestamp of the VSYNC at which this surface was first displayed. Note that 0 means the surface was never displayed.
- Returns
- VdpStatus The completion status of the operation.
Note that this API would block forever if queried about the surface most recently added to a presentation queue. That is because there would be no other surface that could possibly replace that surface as the currently displayed surface, and hence that surface would never become idle. For that reason, this function will return an error in that case.
◆ VdpPresentationQueueCreate
| typedef VdpStatus VdpPresentationQueueCreate(VdpDevice device, VdpPresentationQueueTarget presentation_queue_target, VdpPresentationQueue *presentation_queue) |
Create a VdpPresentationQueue.
- Parameters
-
[in] device The device that will contain the queue. [in] presentation_queue_target The location to display the content. [out] presentation_queue The new queue's handle.
- Returns
- VdpStatus The completion status of the operation.
Note: The initial value for the background color will be set to an implementation-defined value.
◆ VdpPresentationQueueDestroy
| typedef VdpStatus VdpPresentationQueueDestroy(VdpPresentationQueue presentation_queue) |
Destroy a VdpPresentationQueue.
- Parameters
-
[in] presentation_queue The queue to destroy.
- Returns
- VdpStatus The completion status of the operation.
◆ VdpPresentationQueueDisplay
| typedef VdpStatus VdpPresentationQueueDisplay(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, uint32_t clip_width, uint32_t clip_height, VdpTime earliest_presentation_time) |
Enter a surface into the presentation queue.
- Parameters
-
[in] presentation_queue The queue to query. [in] surface The surface to enter into the queue. [in] clip_width If set to a non-zero value, the presentation queue will display only clip_width pixels of the surface (anchored to the top-left corner of the surface. [in] clip_height If set to a non-zero value, the presentation queue will display only clip_height lines of the surface (anchored to the top-left corner of the surface. [in] earliest_presentation_time The timestamp associated with the surface. The presentation queue will not display the surface until the presentation queue's current time is at least this value.
- Returns
- VdpStatus The completion status of the operation.
Applications may choose to allow resizing of the presentation queue target (which may be e.g. a regular Window when using an X11-based implementation).
clip_width and clip_height may be used to limit the size of the displayed region of a surface, in order to match the specific region that was rendered to.
In turn, this allows the application to allocate over-sized (e.g. screen-sized) surfaces, but render to a region that matches the current size of the video window.
Using this technique, an application's response to window resizing may simply be to render to, and display, a different region of the surface, rather than de-/re-allocation of surfaces to match the updated window size.
Implementations may impose an upper bound on the number of entries contained by the presentation queue at a given time. This limit is likely different to the number of VdpOutputSurfaces that may be allocated at a given time. This limit applies to entries in the QUEUED or VISIBLE state only. In other words, entries that have transitioned from a QUEUED or VISIBLE state to an IDLE state do not count toward this limit.
◆ VdpPresentationQueueGetBackgroundColor
| typedef VdpStatus VdpPresentationQueueGetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *background_color) |
Retrieve the current background color setting.
- Parameters
-
[in] presentation_queue The queue to query. [out] background_color The current background color.
◆ VdpPresentationQueueGetTime
| typedef VdpStatus VdpPresentationQueueGetTime(VdpPresentationQueue presentation_queue, VdpTime *current_time) |
Retrieve the presentation queue's "current" time.
- Parameters
-
[in] presentation_queue The queue to query. [out] current_time The current time, which may represent a point between display VSYNC events.
- Returns
- VdpStatus The completion status of the operation.
◆ VdpPresentationQueueQuerySurfaceStatus
| typedef VdpStatus VdpPresentationQueueQuerySurfaceStatus(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, VdpPresentationQueueStatus *status, VdpTime *first_presentation_time) |
Poll the current queue status of a surface.
- Parameters
-
[in] presentation_queue The queue to query. [in] surface The surface to query. [out] status The current status of the surface within the queue. [out] first_presentation_time The timestamp of the VSYNC at which this surface was first displayed. Note that 0 means the surface was never displayed.
- Returns
- VdpStatus The completion status of the operation.
◆ VdpPresentationQueueSetBackgroundColor
| typedef VdpStatus VdpPresentationQueueSetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *const background_color) |
Configure the background color setting.
- Parameters
-
[in] presentation_queue The queue to manipulate. [in] background_color The new background color.
Note: Implementations may choose whether to apply the new background color value immediately, or defer it until the next surface is presented.
◆ VdpPresentationQueueTarget
| typedef uint32_t VdpPresentationQueueTarget |
An opaque handle representing the location where video will be presented.
VdpPresentationQueueTarget are created using a Window System Integration Layer specific API, such as VdpPresentationQueueTargetCreateX11.
◆ VdpPresentationQueueTargetDestroy
| typedef VdpStatus VdpPresentationQueueTargetDestroy(VdpPresentationQueueTarget presentation_queue_target) |
Destroy a VdpPresentationQueueTarget.
- Parameters
-
[in] presentation_queue_target The target to destroy.
- Returns
- VdpStatus The completion status of the operation.
◆ VdpTime
| typedef uint64_t VdpTime |
The representation of a point in time.
VdpTime timestamps are intended to be a high-precision timing system, potentially independent from any other time domain in the system.
Time is represented in units of nanoseconds. The origin (i.e. the time represented by a value of 0) is implementation dependent.
Enumeration Type Documentation
◆ VdpPresentationQueueStatus
The status of a surface within a presentation queue.
