VDPAU: VdpPresentationQueue; Video presentation (display) object

VDPAU

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

## Typedefs
typedef uint64_t | VdpTime
| The representation of a point in time.
typedef uint32_t | VdpPresentationQueueTarget
| An opaque handle representing the location where video will be presented.
typedef VdpStatus | VdpPresentationQueueTargetDestroy(VdpPresentationQueueTarget presentation_queue_target)
| Destroy a VdpPresentationQueueTarget.
typedef uint32_t | VdpPresentationQueue
| An opaque handle representing a presentation queue object.
typedef VdpStatus | VdpPresentationQueueCreate(VdpDevice device, VdpPresentationQueueTarget presentation_queue_target, VdpPresentationQueue *presentation_queue)
| Create a VdpPresentationQueue.
typedef VdpStatus | VdpPresentationQueueDestroy(VdpPresentationQueue presentation_queue)
| Destroy a VdpPresentationQueue.
typedef VdpStatus | VdpPresentationQueueSetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *const background_color)
| Configure the background color setting.
typedef VdpStatus | VdpPresentationQueueGetBackgroundColor(VdpPresentationQueue presentation_queue, VdpColor *background_color)
| Retrieve the current background color setting.
typedef VdpStatus | VdpPresentationQueueGetTime(VdpPresentationQueue presentation_queue, VdpTime *current_time)
| Retrieve the presentation queue's "current" time.
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.
typedef VdpStatus | VdpPresentationQueueBlockUntilSurfaceIdle(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, VdpTime *first_presentation_time)
| Wait for a surface to finish being displayed.
typedef VdpStatus | VdpPresentationQueueQuerySurfaceStatus(VdpPresentationQueue presentation_queue, VdpOutputSurface surface, VdpPresentationQueueStatus *status, VdpTime *first_presentation_time)
| Poll the current queue status of a surface.

## 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

enum VdpPresentationQueueStatus

The status of a surface within a presentation queue.

Enumerator
VDP_PRESENTATION_QUEUE_STATUS_IDLE | The surface is not 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.