VDPAU
Typedefs | Enumerations
VdpPresentationQueue; Video presentation (display) object
Collaboration diagram for VdpPresentationQueue; Video presentation (display) object:

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

typedef uint32_t VdpPresentationQueue

An opaque handle representing a presentation queue object.

typedef VdpStatus VdpPresentationQueueBlockUntilSurfaceIdle(VdpPresentationQueue presentation_queue, VdpOutputSurface surface,VdpTime *first_presentation_time)

Wait for a surface to finish being displayed.

Parameters
[in]presentation_queueThe queue to query.
[in]surfaceThe surface to wait for.
[out]first_presentation_timeThe 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.

typedef VdpStatus VdpPresentationQueueCreate(VdpDevice device, VdpPresentationQueueTarget presentation_queue_target,VdpPresentationQueue *presentation_queue)

Create a VdpPresentationQueue.

Parameters
[in]deviceThe device that will contain the queue.
[in]presentation_queue_targetThe location to display the content.
[out]presentation_queueThe 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.

typedef VdpStatus VdpPresentationQueueDestroy(VdpPresentationQueue presentation_queue)

Destroy a VdpPresentationQueue.

Parameters
[in]presentation_queueThe queue to destroy.
Returns
VdpStatus The completion status of the operation.
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_queueThe queue to query.
[in]surfaceThe surface to enter into the queue.
[in]clip_widthIf 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_heightIf 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_timeThe 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.

typedef VdpStatus VdpPresentationQueueGetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *background_color)

Retrieve the current background color setting.

Parameters
[in]presentation_queueThe queue to query.
[out]background_colorThe current background color.
typedef VdpStatus VdpPresentationQueueGetTime(VdpPresentationQueue presentation_queue,VdpTime *current_time)

Retrieve the presentation queue's "current" time.

Parameters
[in]presentation_queueThe queue to query.
[out]current_timeThe current time, which may represent a point between display VSYNC events.
Returns
VdpStatus The completion status of the operation.
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_queueThe queue to query.
[in]surfaceThe surface to query.
[out]statusThe current status of the surface within the queue.
[out]first_presentation_timeThe 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.
typedef VdpStatus VdpPresentationQueueSetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *const background_color)

Configure the background color setting.

Parameters
[in]presentation_queueThe queue to manipulate.
[in]background_colorThe 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.

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.

typedef VdpStatus VdpPresentationQueueTargetDestroy(VdpPresentationQueueTarget presentation_queue_target)

Destroy a VdpPresentationQueueTarget.

Parameters
[in]presentation_queue_targetThe target to destroy.
Returns
VdpStatus The completion status of the operation.
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

The status of a surface within a presentation queue.

Enumerator
VDP_PRESENTATION_QUEUE_STATUS_IDLE 

The surface is no queued or currently visible.

VDP_PRESENTATION_QUEUE_STATUS_QUEUED 

The surface is in the queue, and not currently visible.

VDP_PRESENTATION_QUEUE_STATUS_VISIBLE 

The surface is the currently visible surface.