OpenWFD Usage Guidelines

  • The macro WFD_WFDEXT_PROTOTYPES must be defined before including the wfd.h and wfdext.h headers.
  • To clear the contents on a WFDPipeline (performing a null flip), wfdBindSourceToPipeline must be called with 0 as the argument for WFDSource before calling wfdDeviceCommit on the WFDPipeline. This is demonstrated in the openwfd_nvsci_sample application present in the SDK.
  • During the deinitialization of OpenWFD applications, you must follow these steps:
    1. Perform a null flip on all WFDPorts and WFDPipelines that were previously bound to a WFDSource.
      • If nonblocking commits are being used and WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX is set to WFD_TRUE, the post-flip fence of the null flip commit should be waited on.
      • If nonblocking commits are being used and WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX is set to WFD_FALSE, the post-flip fence of the wfdDeviceCommit call before the null flip commit should be waited on.
    2. Destroy all WFDSource objects by invoking wfdDestroySource on them only after all null flip commits are complete. Blocking wfdDeviceCommit calls ensures that the null flip is complete when the wfdDeviceCommit call returns. For nonblocking wfdDeviceCommit calls, synchronization must be handled by the OpenWFD client as described previously.
    3. Destroy all WFDPipeline and WFDPort objects by using wfdDestroyPipeline and wfdDestroyPort, respectively, before finally destroying the WFDDevice object using wfdDestroyDevice.
  • For committing to multiple WFDPipeline handles bound to the same WFDPort, it is recommended to call wfdDeviceCommit* with WFDCommitType set to WFD_COMMIT_ENTIRE_PORT.
  • When you use WFD_COMMIT_ENTIRE_PORT in a wfdDeviceCommit call, all the WFDPipeline objects part of the commit must either 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 NvDisplay resource manager. To ensure that any errors are caught, the OpenWFD API wfdGetError must be invoked after calls to the following OpenWFD APIs that take in 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}

  • When flipping to display, you should use a minimum of two WFDSource handles (double buffering) to prevent tearing or corruption.

    For more details, see section 8.1 in the OpenWF Display Specification.

  • The following prerequisites must be fulfilled for use cases to suspend to RAM (SC7 mode):

    • Before entering suspend-to-RAM (SC7) mode, it is recommended to perform a null flip to display.
    • To exit SC7 mode, a modeset must be performed before flipping to display.
  • On Linux platforms, the following restriction applies when you invoke wfdDeviceCommit or wfdDeviceCommitWithNvSciSyncFenceNVX:
    • A main WFDPipeline of a WFDPort refers to the WFD pipeline that is represented by the first WFD pipeline ID returned by wfdEnumeratePipelines. An overlay WFDPipeline refers to the WFD pipelines represented by the remaining WFD pipeline IDs enumerated by wfdEnumeratePipelines. On Linux, calling the wfdDeviceCommit or wfdDeviceCommitWithNvSciSyncFenceNVX API involving the overlay WFD pipelines is supported only if the main WFDPipeline already has a WFDSource bound. Similarly, null flip commit on main WFD pipelines is only supported when all overlay WFD pipelines are also bound to null surfaces.
  • To minimize flip latency, you should set WFD_PIPELINE_POSTFENCE_SCANOUT_BEGIN_NVX to WFD_FALSE.