OpenWFD

This topic describes the Khronos ™ Open Windowing Foundation - Display ™ (OpenWFD) API that can be used to interact with the display hardware. OpenWFD does not require the presence of a native windowing system.

OpenWFD is a Khronos API that provides a low-level hardware abstraction interface for windowing systems, and applications can interact directly with the display by using the OpenWFD API. The specification of the OpenWFD API is available at Khronos’ registry at OpenWF Display 1.0 Specification (also referred to as the spec).

The display architecture on Jetson includes an OpenWFD driver (also referred to as the WFD driver) that supports a subset of the core OpenWFD APIs in the spec and additional NVIDIA specific extensions. Usage guidelines for the core OpenWFD APIs can be obtained from the spec, and deviations from the spec or additional details will be described in this section.

Supported OpenWFD APIs

The following table provides a list of the supported core OpenWFD APIs on the WFD driver:

Supported OpenWFD APIs

API	Support in the OpenWFD driver
wfdGetStrings	Supported
wfdIsExtensionSupported	Supported
wfdGetError	Supported
wfdEnumerateDevices	Supported
wfdCreateDevice	Supported
wfdDestroyDevice	Supported
wfdDeviceCommit	Supported
wfdGetDeviceAttribi	Supported
wfdSetDeviceAttribi	Supported
wfdCreateEvent	Not supported
wfdDestroyEvent	Not supported
wfdGetEventAttribi	Not supported
wfdDeviceEventAsync	Not supported
wfdDeviceEventWait	Not supported
wfdDeviceEventFilter	Not supported
wfdEnumeratePorts	Supported
wfdCreatePort	Supported
wfdDestroyPort	Supported
wfdGetPortModes	Supported
wfdGetPortModeAttrib{i/f}	Supported
wfdSetPortMode	Supported
wfdGetCurrentPortMode	Supported
wfdGetPortAttribi	Supported
wfdGetPortAttribf	Supported
wfdGetPortAttribiv	Supported
wfdGetPortAttribfv	Supported
wfdSetPortAttribi	Supported
wfdSetPortAttribf	Supported
wfdSetPortAttribiv	Supported
wfdSetPortAttribfv	Supported
wfdBindPipelineToPort	Supported
wfdGetDisplayDataFormats	Not supported
wfdGetDisplayData	Not supported
wfdEnumeratePipelines	Not supported
wfdCreatePipeline	Supported
wfdDestroyPipeline	Supported
wfdCreateSourceFromImage	Not supported
wfdCreateSourceFromStream	Not supported
wfdDestroySource	Supported
wfdCreateMaskFromImage	Not supported
wfdCreateMaskFromStream	Not supported
wfdDestroyMask	Not supported
wfdBindSourceToPipeline	Supported
wfdBindMaskToPipeline	Not supported
wfdGetPipelineAttribi	Supported
wfdGetPipelineAttribf	Supported
wfdGetPipelineAttribiv	Supported
wfdGetPipelineAttribfv	Supported
wfdSetPipelineAttribi	Supported
wfdSetPipelineAttribf	Supported
wfdSetPipelineAttribiv	Supported
wfdSetPipelineAttribfv	Supported
wfdGetPipelineTransparency	Supported
wfdSetPipelineTSColor	Not supported
wfdGetPipelineLayerOrder	Supported

The following OpenWFD attributes are not implemented:

• WFD_PORT_POWER_MODE

• WFD_PORT_PROTECTION_ENABLE

• WFD_PORT_PARTIAL_REFRESH_ENABLE

• WFD_PORT_GAMMA

• WFD_PIPELINE_SHAREABLE

• WFD_PIPELINE_SCALE_FILTER

The following OpenWFD attributes have limited support for querying:

WFD_PORT_BACKGROUND_COLOR - Cannot be queried via the wfdGetPortAttribi API. The wfdGetPortAttribiv and wfdGetPortAttribfv APIs can still be used for querying WFD_PORT_BACKGROUND_COLOR.

Supported OpenWFD Extensions

The following OpenWFD extensions are supported by the OpenWFD Driver:

WFD_NVX_create_source_from_nvscibuf

This extension allows the creation of WFDSource handles from NvSciBufObj buffer objects.

The following APIs are introduced as part of this extension:

• wfdNvSciBufSetDisplayAttributesNVX

  Before allocating NvSciBufObj, the list of engines that require access to NvSciBufObj need to be specified by the clients of NvSciBuf. For NvSciBufObj that will be accessed by the display hardware, before reconciling the attribute lists, the relevant display engine flags need to be added in NvSciBufAttrList with the other engine’s flags.

  wfdNvSciBufSetDisplayAttributesNVX fills attrList with the required display engine attributes and OpenWFD clients that require NvSciBufObj buffers to be consumed by the display and, before allocating the NvSciBufObj, should call wfdNvSciBufSetDisplayAttributesNVX.

  • API Prototype:

    • WFDErrorCode wfdNvSciBufSetDisplayAttributesNVX(NvSciBufAttrList *attrList)

  • Parameters:

    • NvSciBufAttrList *attrList: A valid pointer to a NvSciBufAttrList object.

  • Return Values:

    • WFD_ERROR_NOT_SUPPORTED: The engine ID created for the display engine is not supported.

    • WFD_ERROR_OUT_OF_MEMORY: Insufficient memory is available to the OpenWFD driver for filling attrList.

    • WFD_ERROR_ILLEGAL_ARGUMENT: attrList is not a valid NvSciBufAttrList.

• wfdCreateSourceFromNvSciBufNVX

  wfdCreateSourceFromNvSciBufNVX creates WFDSource handles from NvSciBufObj objects. bufferObject should be allocated with reconciliation and include a NvSciBufAttrList that is filled using wfdNvSciBufSetDisplayAttributesNV.

  • API Prototype:

    • WFDSource wfdCreateSourceFromNvSciBufNVX(WFDDevice device, WFDPipeline pipeline, NvSciBufObj &bufferObject)

  • Parameters:

    • WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice.

    • WFDPipeline pipeline: A valid WFDPipeline handle created using wfdCreatePipeline.

    • NvSciBufObj &bufferObject: A valid reference to a NvSciBufObj.

  • Return Values:

    • A valid WFDSource handle: On success.

    • WFD_INVALID_HANDLE: On failure (Use wfdGetError to query the error code).

  • Error Codes Set:

    • WFD_ERROR_ILLEGAL_ARGUMENT: bufferObject is not a valid NvSciBuf object, and bufferObject does not contain display flags as part of its engine array list.

    • WFD_ERROR_NOT_SUPPORTED: The attributes of bufferObject are not supported by the extension.

    • WFD_ERROR_BAD_HANDLE: pipeline is not a valid WFDPipeline.

A limited set of values are supported by this extension for only the following NvSciBuf attribute keys:

Supported values for NvSciBuf attribute keys

NvSciBuf Attribute Key	Value
NvSciBufGeneralAttrKey_Types	NvSciBufType_Image
NvSciBufImageAttrKey_PlaneCount	1 or 2
NvSciBufImageAttrKey_PlaneColorFormat	NvSciColor_A8R8G8B8, NvSciColor_A8B8G8R8, NvSciColor_Y8, NvSciColor_U8_V8, NvSciColor_U8Y8V8Y8, NvSciColor_Y8U8Y8V8, NvSciColor_V8U8

WFD_NVX_commit_non_blocking

This extension allows users to schedule flips to the display that do not block until the display has completed its work. The default behavior of the core OpenWFD API wfdDeviceCommit is to block until the display is done with the flip. This extensions adds WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX, a new WFDPipeline attribute, which can be used to alter the default behavior of wfdDeviceCommit.

By default, WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX is set to WFD_FALSE, which makes calls to wfdDeviceCommit on the WFDPipeline blocking. The wfdSetPipelineAttribi function can be used to set the value of a WFDPipeline object’s WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX attribute to WFD_TRUE, which makes calls to wfdDeviceCommit on the WFDPipeline non blocking.

When calling wfdDeviceCommit with WFDCommitType that is set to WFD_COMMIT_ENTIRE_PORT or WFD_COMMIT_ENTIRE_DEVICE, the WFDPipeline objects that are attached to the WFDPort and WFDDevice handles need to have their WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX attribute set to WFD_TRUE to allow non-blocking commits. In this scenario, synchronizing calls to wfdDeviceCommit must be explicitly handled by the user with the help of the WFD_NVX_nvscisync extension.

Here are the additions to the list of WFDPortModeAttrib enums:

• WFD_PIPELINE_COMMIT_NON_BLOCKING_NVX

WFD_NVX_nvscisync

This extension allows users to explicitly handle the synchronization of work submissions to the display by using NvSciSyncFence.

The WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX WFDPipeline attribute can be used to alter the default behavior of the post-flip fence that is returned by wfdDeviceCommitWithNvSciSyncFenceNVX. By default, WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX is set to WFD_TRUE, so when the display hardware starts scanning the current buffer, the post-flip fence that was returned from wfdDeviceCommitWithNvSciSyncFenceNVX is signaled.

The wfdSetPipelineAttribi function can be used to modify the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX. When this attribute is set to WFD_FALSE, the post-flip fence returned by wfdDeviceCommitWithNvSciSyncFenceNVX will be signaled at the end of scan-out of the buffer. This can happen only when a wfdDeviceCommit on a new WFDSource handle is scheduled so that the display hardware can stop scanning the WFDSource used for the previous wfdDeviceCommit.

The wfdSetPipelineAttribi function can be called to modify the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX only once per WFDPipeline for the duration of the application life-cycle. The wfdGetPipelineAttribi function can be used to query the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX.

Note

When scheduling commits of the WFD_COMMIT_ENTIRE_PORT type or the WFD_COMMIT_ENTIRE_DEVICE type, the values of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX should be the same for all WFDPipeline handles in the commit. When there are discrepancies in the values of the WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX values, the value of the highest Z-ordered WFDPipeline for the WFDPort is considered. Applications should not rely on this behavior and instead explicitly set the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX for all WFDPipeline handles in the commit.

The following APIs are exposed to users as part of this extension and are described below:

• wfdNvSciSyncSetWaiterAttributesNVX

  The OpenWFD driver only supports sync-point synchronization primitives and NvSciSyncFences that are passed to OpenWFD must be generated from NvSciSyncObj objects that have been created with the reconciliation of attribute lists that specify the sync-point type supported by the OpenWFD driver. wfdNvSciSyncSetWaiterAttributesNVX allows OpenWFD clients that intended to pass waiter NvSciSyncFence objects to fill NvSciSyncAttrLists with the supported sync-point primitive type for reconciliation.

  • API Prototype:

    • WFDErrorCode wfdNvSciSyncSetWaiterAttributesNVX(NvSciSyncAttrList *attrList)

  • Parameters:

    • *attrList: A valid pointer to a NvSciSyncAttrList object.

  • Return values:

    • WFD_ERROR_ILLEGAL_ARGUMENT: attrList is not a valid NvSciSyncAttrList.

    • WFD_ERROR_NONE: On success.

• wfdNvSciSyncSetSignalerAttributesNVX

  Similar to wfdNvSciSyncSetWaiterAttributesNVX, wfdNvSciSyncSetSignalerAttributesNVX allows OpenWFD clients that intended to pass NvSciSyncFence objects that are signaled by the display hardware to fill NvSciSyncAttrLists with the supported sync-point primitive type for reconciliation.

  • API Prototype:

    • WFDErrorCode wfdNvSciSyncSetSignalerAttributesNVX(NvSciSyncAttrList *attrList)

  • Parameters:

    • NvSciSyncAttrList *attrList: A valid pointer to a NvSciSyncAttrList object.

  • Return Values:

    • WFD_ERROR_ILLEGAL_ARGUMENT: attrList is not a valid NvSciSyncAttrList.

    • WFD_ERROR_NONE: On success.

• wfdBindNvSciSyncFenceToSourceNVX

  wfdBindNvSciSyncFenceToSourceNVX allows users to associate an NvSciSyncFence object with a WFDSource handle.

  Work submissions that are done to the display with the WFDSource handle will be blocked on the NvSciSyncFence that is bound to the WFDSource. The user is responsible to signal the NvSciSyncFence and allow the display to consume the buffer.

  • API Prototype:

    • WFDErrorCode wfdBindNvSciSyncFenceToSourceNVX(WFDDevice device, WFDSource source, void* fence)

  • Parameters:

    • WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice.

    • WFDSource source: A valid WFDSource handle created using wfdCreateSourceFromNvSciBufNVX.

    • void *fence: A valid pointer to a NvSciSyncFence object.

  • Return Values:

    • WFD_ERROR_ILLEGAL_ARGUMENT: fence is nullptr or an invalid NvSciSyncFence object, or the source is not a valid WFDSource handle.

    • WFD_ERROR_BAD_DEVICE: device is an invalid WFDDevice handle.

    • WFD_ERROR_BAD_HANDLE: source is not bound to a valid WFDPipeline.

    • WFD_ERROR_NONE: Success.

• wfdRegisterPostFlipNvSciSyncObjNVX

  wfdRegisterPostFlipNvSciSyncObjNVX allows WFD clients to register a NvSciSyncObj with the OpenWFD driver, and the driver uses NvSciSyncObj to generate NvSciSyncFence objects that are passed to the WFD client and are signaled when the display hardware has completed consuming the buffer.

  The OpenWFD driver allows only one NvSciSyncObj to be registered at a time. nullptr can be passed for obj to unregister existing NvSciSyncObj objects. This allows the WFD client to register a different NvSciSyncObj handle with the OpenWFD driver. The NvSciSyncFence that is generated by using the registered NvSciSyncObj handle is returned to the client through wfdDeviceCommitWithNvSciSyncFeenceNVX. obj should be created with a NvSciSyncAttrList filled by wfdNvSciSyncSetSignalerAttributesNVX.

  • API Prototype:

    • WFDErrorCode wfdRegisterPostFlipNvSciSyncObjNVX(WFDDevice device, NvSciSyncObj* obj)

  • Parameters:

    • WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice.

    • NvSciSyncObj *obj: A valid pointer to a NvSciSyncObj object or nullptr (see above).

  • Return Values:

    • WFD_ERROR_ILLEGAL_ARGUMENT: A NvSciSyncObj is already registered with device.

    • WFD_ERROR_BAD_ATTRIBUTE: obj is not a valid NvSciSyncObj.

    • WFD_ERROR_BAD_DEVICE: device is not a valid WFDDevice handle.

    • WFD_ERROR_NOT_SUPPORTED: obj encapsulates a primitive type not supported by the OpenWFD driver.

    • WFD_ERROR_NONE: Success.

• wfdDeviceCommitWithNvSciSyncFenceNVX

  This API is similar to the OpenWFD Core API wfdDeviceCommit with the addition of a NvSciSyncFence parameter.

  When a NvSciSyncObj is registered with the OpenWFD driver, wfdDeviceCommitWithNvSciSyncFenceNVX can be used by the client to acquire an NvSciSyncFence object passed via fence. This is the post-flip fence of display, and its signaling semantics depend on the value of WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX for the WFDPipeline in the commit call.

  After the fence has been signaled, the fence must be cleared by the client with a call to NvSciSyncFenceClear. When this API is called, with no registered NvSciSyncObj, fence returns a nullptr.

  • API Prototype:

    • void wfdDeviceCommitWithNvSciSyncFenceNVX(WFDDevice device, WFDCommitType type, WFDHandle handle, void *fence)

  • Parameters:

    • WFDDevice device: A valid WFDDevice handle created using wfdCreateDevice.

    • WFDHandle handle: A valid handle to a WFDPort or a WFDPipeline. Refer to the OpenWF Display 1.0 Specification for the list of accepted values.

    • void *fence: A pointer that can store a NvSciSyncFence object.

  • Return Values:

    • None

  • Error codes set:

    • WFD_ERROR_ILLEGAL_ARGUMENT: type is not a valid WFDCommitType.

    • WFD_ERROR_NOT_SUPPORTED: If any hardware resource limitations exist.

    • WFD_ERROR_BUSY: A call to wfdDeviceCommitWithNvSciSyncFenceNVX is currently executing.

    • WFD_ERROR_BAD_HANDLE: handle does not match the requirements of type as specified in the documentation of wfdDeviceCommit at OpenWF Display 1.0 Specification.

    • WFD_ERROR_INCONSISTENCY: If any configuration conflicts exist within the device or corresponding ports or corresponding pipelines.

    • WFD_ERROR_BAD_ATTRIBUTE: fence is not a valid NvSciSyncFence object.

WFD_NVX_port_mode_timings

This extension allows WFD clients to query the horizontal total and vertical total values of the display by using the following WFDPortMode attributes.

Additions to the list of WFDPortModeAttrib enums:

• WFD_PORT_MODE_H_TOTAL_NVX

• WFD_PORT_MODE_V_TOTAL_NVX

These attributes are read-only and can be queried only by using wfdGetPortModeAttribi.

OpenWFD Usage Guidelines

• To enable the WFD_NVX_create_source_from_nvscibuf extension, before you include the wfd.h and wfdext.h headers, define the WFD_NVX_create_source_from_nvscibuf macro.

• Define the WFD_WFDEXT_PROTOTYPES macro before you include the wfd.h and wfdext.h headers.

• To clear the contents on a WFDPipeline (performing a null flip), call wfdBindSourceToPipeline with 0 for the WFDSource argument before you call wfdDeviceCommit on the WFDPipeline.

• To commit to multiple WFDPipeline handles that are bound to the same WFDPort, we recommended that you call wfdDeviceCommit* with WFDCommitType set to WFD_COMMIT_ENTIRE_PORT.

• When you use WFD_COMMIT_ENTIRE_PORT in a wfdDeviceCommit call, the WFDPipeline objects that are part of the commit must have a surface bound(normal flip) or have no surfaces bound (null flip). A mix of normal and a null flip in one WFD_COMMIT_ENTIRE_PORT wfdDeviceCommit call is not allowed due to a limitation on the Display driver.

• To ensure that errors are caught, invoke the wfdGetError API after calls to the following OpenWFD APIs that take a WFDDevice handle as one of the inputs and return void:

  • wfdDeviceCommit

  • wfdDeviceCommitWithNvSciSyncFenceNVX

  • wfdDestroyPort

  • wfdSetPortMode

  • wfdGetPortAttrib{iv/fv}

  • wfdSetPortAttrib{i/v/iv/fv}

  • wfdBindPipelineToPort

  • wfdDestroyPipeline

  • wfdDestroySource

  • wfdBindSourceToPipeline

  • wfdGetPipelineAttrib{iv/fv}

  • wfdSetPipelineAttrib{i/v/iv/fv}