Vulkan-Docs/appendices/VK_EXT_transform_feedback.txt

include::meta/VK_EXT_transform_feedback.txt[]

*Last Modified Data*::
    2018-10-09
*Contributors*::
  - Baldur Karlsson, Valve
  - Boris Zanin, Mobica
  - Daniel Rakos, AMD
  - Donald Scorgie, Imagination
  - Henri Verbeet, CodeWeavers
  - Jan-Harald Fredriksen, Arm
  - Jason Ekstrand, Intel
  - Jeff Bolz, NVIDIA
  - Jesse Barker, Unity
  - Jesse Hall, Google
  - Pierre-Loup Griffais, Valve
  - Philip Rebohle, DXVK
  - Ruihao Zhang, Qualcomm
  - Samuel Pitoiset, Valve
  - Slawomir Grajewski, Intel
  - Stu Smith, Imagination Technologies


This extension adds transform feedback to the Vulkan API by exposing the
SPIR-V code:TransformFeedback and code:GeometryStreams capabilities to
capture vertex, tessellation or geometry shader outputs to one or more
buffers.
It adds API functionality to bind transform feedback buffers to capture the
primitives emitted by the graphics pipeline from SPIR-V outputs decorated
for transform feedback.
The transform feedback capture can be paused and resumed by way of storing
and retrieving a byte counter.
The captured data can be drawn again where the vertex count is derived from
the byte counter without CPU intervention.
If the implementation is capable, a vertex stream other than zero can be
rasterized.

All these features are designed to match the full capabilities of OpenGL
core transform feedback functionality and beyond.
Many of the features are optional to allow base OpenGL ES GPUs to also
implement this extension.

The primary purpose of the functionality exposed by this extension is to
support translation layers from other 3D APIs.
This functionality is not considered forward looking, and is not expected to
be promoted to a KHR extension or to core Vulkan.
Unless this is needed for translation, it is recommended that developers use
alternative techniques of using the GPU to process and capture vertex data.

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:

  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_FEATURES_EXT
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_TRANSFORM_FEEDBACK_PROPERTIES_EXT
  ** ename:VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_STREAM_CREATE_INFO_EXT

  * Extending elink:VkQueryType:

  ** ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT

  * Extending elink:VkBufferUsageFlagBits:

  ** ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT
  ** ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT

  * Extending elink:VkAccessFlagBits:

  ** ename:VK_ACCESS_TRANSFORM_FEEDBACK_WRITE_BIT_EXT
  ** ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT
  ** ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT

  * Extending elink:VkPipelineStageFlagBits:

  ** ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

=== New Enums

  * tlink:VkPipelineRasterizationStateStreamCreateFlagsEXT

=== New Structures

  * Extending slink:VkPhysicalDeviceFeatures2:
  ** slink:VkPhysicalDeviceTransformFeedbackFeaturesEXT
  * Extending slink:VkPhysicalDeviceProperties2:
  ** slink:VkPhysicalDeviceTransformFeedbackPropertiesEXT
  * Extending slink:VkPipelineRasterizationStateCreateInfo
  ** slink:VkPipelineRasterizationStateStreamCreateInfoEXT

=== New Functions

  * flink:vkCmdBindTransformFeedbackBuffersEXT
  * flink:vkCmdBeginTransformFeedbackEXT
  * flink:vkCmdEndTransformFeedbackEXT
  * flink:vkCmdBeginQueryIndexedEXT
  * flink:vkCmdEndQueryIndexedEXT
  * flink:vkCmdDrawIndirectByteCountEXT

=== Issues

1) Should we include pause/resume functionality?

*RESOLVED*: Yes, this is needed to ease layering other APIs which have this
functionality.
To pause use fname:vkCmdEndTransformFeedbackEXT and provide valid buffer
handles in the pname:pCounterBuffers array and offsets in the
pname:pCounterBufferOffsets array for the implementation to save the resume
points.
Then to resume use fname:vkCmdBeginTransformFeedbackEXT with the previous
pname:pCounterBuffers and pname:pCounterBufferOffsets values.
Between the pause and resume there needs to be a memory barrier for the
counter buffers with a source access of
ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_WRITE_BIT_EXT at pipeline stage
ename:VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT to a destination access
of ename:VK_ACCESS_TRANSFORM_FEEDBACK_COUNTER_READ_BIT_EXT at pipeline stage
ename:VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT.

2) How does this interact with multiview?

*RESOLVED*: Transform feedback cannot be made active in a render pass with
multiview enabled.

3) How should queries be done?

*RESOLVED*: There is a new query type
ename:VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT.
A query pool created with this type will capture 2 integers -
numPrimitivesWritten and numPrimitivesNeeded - for the specified vertex
stream output from the last vertex processing stage.
The vertex stream output queried is zero by default, but can be specified
with the new fname:vkCmdBeginQueryIndexedEXT and
fname:vkCmdEndQueryIndexedEXT commands.

=== Version History

  * Revision 1, 2018-10-09 (Piers Daniell)
    - Internal revisions