.. _SD.Graphics.OpenWFD: .. include:: /content/swdocs.rsts .. spelling:: wfdNvSciBufSetDisplayAttributesNVX attrList wfdCreateSourceFromNvSciBufNVX bufferObject enums wfdNvSciSyncSetWaiterAttributesNVX wfdNvSciSyncSetSignalerAttributesNVX wfdBindNvSciSyncFenceToSourceNVX nullptr wfdRegisterPostFlipNvSciSyncObjNVX wfdDeviceCommitWithNvSciSyncFenceNVX OpenWFD !!!!!!! This topic describes the Khronos \ |tm| Open Windowing Foundation - Display \ |tm| (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: .. list-table:: Supported OpenWFD APIs :widths: 25 25 :header-rows: 1 * - 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: .. list-table:: Supported values for NvSciBuf attribute keys :widths: 25 25 :header-rows: 1 * - 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}`