protocols/vk-gen/chapters/VK_NVX_device_generated_commands/generation.txt - device/generic/vulkan-cereal - Git at Google

 == Indirect Commands Generation

 [open,refpage='vkCmdReserveSpaceForCommandsNVX',desc='Perform a reservation of command buffer space',type='protos']
 --

 Command space for generated commands recorded into a secondary command
 buffer must: be reserved by calling:

 include::../../api/protos/vkCmdReserveSpaceForCommandsNVX.txt[]

   * pname:commandBuffer is the secondary command buffer in which the space
     for device-generated commands is reserved.
   * pname:pProcessCommandsInfo is a pointer to an instance of the
     slink:vkCmdReserveSpaceForCommandsNVX structure containing parameters
     affecting the reservation of command buffer space.

 .Valid Usage
 ****
   * [[VUID-vkCmdReserveSpaceForCommandsNVX-commandBuffer-01329]]
     The provided pname:commandBuffer must: not have had a prior space
     reservation since its creation or the last reset.
   * [[VUID-vkCmdReserveSpaceForCommandsNVX-commandBuffer-01330]]
     The state of the pname:commandBuffer must: be legal to execute all
     commands within the sequence provided by the
     pname:indirectCommandsLayout member of pname:pProcessCommandsInfo.
 ****

 include::../../validity/protos/vkCmdReserveSpaceForCommandsNVX.txt[]
 --

 [open,refpage='VkCmdReserveSpaceForCommandsInfoNVX',desc='Structure specifying parameters for the reservation of command buffer space',type='structs']
 --

 include::../../api/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[]

   * pname:sType is the type of this structure.
   * pname:pNext is `NULL` or a pointer to an extension-specific structure.
   * pname:objectTable is the slink:VkObjectTableNVX to be used for the
     generation process.
     Only registered objects at the time
     flink:vkCmdReserveSpaceForCommandsNVX is called, will be taken into
     account for the reservation.
   * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNVX
     that must: also be used at generation time.
   * pname:maxSequencesCount is the maximum number of sequences for which
     command buffer space will be reserved.

 include::../../validity/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[]
 --

 The generated commands will behave as if they were recorded within the call
 to fname:vkCmdReserveSpaceForCommandsNVX, that means they can inherit state
 defined in the command buffer prior this call.
 However, given the stateless nature of the generated sequences, they will
 not affect commands after the reserved space.
 Treat the state that can: be affected by the provided
 sname:VkIndirectCommandsLayoutNVX as undefined.

 [open,refpage='vkCmdProcessCommandsNVX',desc='Performs the generation of commands on the device',type='protos']
 --

 The actual generation on the device is handled with:

 include::../../api/protos/vkCmdProcessCommandsNVX.txt[]

   * pname:commandBuffer is the primary command buffer in which the
     generation process takes space.
   * pname:pProcessCommandsInfo is a pointer to an instance of the
     slink:VkCmdProcessCommandsInfoNVX structure containing parameters
     affecting the processing of commands.

 include::../../validity/protos/vkCmdProcessCommandsNVX.txt[]
 --

 [open,refpage='VkCmdProcessCommandsInfoNVX',desc='Structure specifying parameters for the generation of commands',type='structs']
 --

 include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[]

   * pname:sType is the type of this structure.
   * pname:pNext is `NULL` or a pointer to an extension-specific structure.
   * pname:objectTable is the slink:VkObjectTableNVX to be used for the
     generation process.
     Only registered objects at the time
     flink:vkCmdReserveSpaceForCommandsNVX is called, will be taken into
     account for the reservation.
   * pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNVX
     that provides the command sequence to generate.
   * pname:indirectCommandsTokenCount defines the number of input tokens
     used.
   * pname:pIndirectCommandsTokens provides an array of
     slink:VkIndirectCommandsTokenNVX that reference the input data for each
     token command.
   * pname:maxSequencesCount is the maximum number of sequences for which
     command buffer space will be reserved.
     If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the
     actual number of sequences generated.
   * pname:targetCommandBuffer can: be the secondary slink:VkCommandBuffer in
     which the commands should be recorded.
     If pname:targetCommandBuffer is `NULL` an implicit reservation as well
     as execution takes place on the processing sname:VkCommandBuffer.
   * pname:sequencesCountBuffer can: be slink:VkBuffer from which the actual
     amount of sequences is sourced from as ftext:uint32_t value.
   * pname:sequencesCountOffset is the byte offset into
     pname:sequencesCountBuffer where the count value is stored.
   * pname:sequencesIndexBuffer must: be set if
     pname:indirectCommandsLayout's
     ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT is set and
     provides the used sequence indices as ftext:uint32_t array.
     Otherwise it must: be dlink:VK_NULL_HANDLE.
   * pname:sequencesIndexOffset is the byte offset into
     pname:sequencesIndexBuffer where the index values start.


 .Valid Usage
 ****
   * [[VUID-VkCmdProcessCommandsInfoNVX-objectTable-01331]]
     The provided pname:objectTable must: include all objects referenced by
     the generation process.
   * [[VUID-VkCmdProcessCommandsInfoNVX-indirectCommandsTokenCount-01332]]
     pname:indirectCommandsTokenCount must: match the
     pname:indirectCommandsLayout's pname:tokenCount.
   * [[VUID-VkCmdProcessCommandsInfoNVX-tokenType-01333]]
     The pname:tokenType member of each entry in the
     pname:pIndirectCommandsTokens array must: match the values used at
     creation time of pname:indirectCommandsLayout
   * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01334]]
     If pname:targetCommandBuffer is provided, it must: have reserved command
     space.
   * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01335]]
     If pname:targetCommandBuffer is provided, the pname:objectTable must:
     match the reservation's objectTable and must: have had all referenced
     objects registered at reservation time.
   * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01336]]
     If pname:targetCommandBuffer is provided, the
     pname:indirectCommandsLayout must: match the reservation's
     indirectCommandsLayout.
   * [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01337]]
     If pname:targetCommandBuffer is provided, the pname:maxSequencesCount
     must: not exceed the reservation's maxSequencesCount.
   * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesCountBuffer-01338]]
     If pname:sequencesCountBuffer is used, its usage flag must: have
     ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set.
   * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesCountBuffer-01339]]
     If pname:sequencesCountBuffer is used, pname:sequencesCountOffset must:
     be aligned to
     sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceCountBufferOffsetAlignment.
   * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesIndexBuffer-01340]]
     If pname:sequencesIndexBuffer is used, its usage flag must: have
     ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set.
   * [[VUID-VkCmdProcessCommandsInfoNVX-sequencesIndexBuffer-01341]]
     If pname:sequencesIndexBuffer is used, pname:sequencesIndexOffset must:
     be aligned to
     sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceIndexBufferOffsetAlignment.
 ****

 include::../../validity/structs/VkCmdProcessCommandsInfoNVX.txt[]
 --

 Referencing the functions defined in <<indirectmdslayout>>,
 fname:vkCmdProcessCommandsNVX behaves as:

 [source,c]
 ---------------------------------------------------
 // For targetCommandBuffers the existing reservedSpace is reset & overwritten.

 VkCommandBuffer cmd = targetCommandBuffer ?
       targetCommandBuffer.reservedSpace :
       commandBuffer;

 uint32_t sequencesCount = sequencesCountBuffer ?
       min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) :
       maxSequencesCount;


 cmdProcessAllSequences(cmd, objectTable,
                        indirectCommandsLayout, pIndirectCommandsTokens,
                        sequencesCount,
                        sequencesIndexBuffer, sequencesIndexOffset);

 // The stateful commands within indirectCommandsLayout will not
 // affect the state of subsequent commands in the target
 // command buffer (cmd)
 ---------------------------------------------------

 [NOTE]
 .Note
 ====
 It is important to note that the state that may be affected through
 generated commands must: be considered undefined for the commands following
 them.
 It is not possible to setup generated state and provoking work that uses
 this state outside of the generated sequence.
 ====
	== Indirect Commands Generation

	[open,refpage='vkCmdReserveSpaceForCommandsNVX',desc='Perform a reservation of command buffer space',type='protos']
	--

	Command space for generated commands recorded into a secondary command
	buffer must: be reserved by calling:

	include::../../api/protos/vkCmdReserveSpaceForCommandsNVX.txt[]

	* pname:commandBuffer is the secondary command buffer in which the space
	for device-generated commands is reserved.
	* pname:pProcessCommandsInfo is a pointer to an instance of the
	slink:vkCmdReserveSpaceForCommandsNVX structure containing parameters
	affecting the reservation of command buffer space.

	.Valid Usage
	****
	* [[VUID-vkCmdReserveSpaceForCommandsNVX-commandBuffer-01329]]
	The provided pname:commandBuffer must: not have had a prior space
	reservation since its creation or the last reset.
	* [[VUID-vkCmdReserveSpaceForCommandsNVX-commandBuffer-01330]]
	The state of the pname:commandBuffer must: be legal to execute all
	commands within the sequence provided by the
	pname:indirectCommandsLayout member of pname:pProcessCommandsInfo.
	****

	include::../../validity/protos/vkCmdReserveSpaceForCommandsNVX.txt[]
	--

	[open,refpage='VkCmdReserveSpaceForCommandsInfoNVX',desc='Structure specifying parameters for the reservation of command buffer space',type='structs']
	--

	include::../../api/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[]

	* pname:sType is the type of this structure.
	* pname:pNext is `NULL` or a pointer to an extension-specific structure.
	* pname:objectTable is the slink:VkObjectTableNVX to be used for the
	generation process.
	Only registered objects at the time
	flink:vkCmdReserveSpaceForCommandsNVX is called, will be taken into
	account for the reservation.
	* pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNVX
	that must: also be used at generation time.
	* pname:maxSequencesCount is the maximum number of sequences for which
	command buffer space will be reserved.

	include::../../validity/structs/VkCmdReserveSpaceForCommandsInfoNVX.txt[]
	--

	The generated commands will behave as if they were recorded within the call
	to fname:vkCmdReserveSpaceForCommandsNVX, that means they can inherit state
	defined in the command buffer prior this call.
	However, given the stateless nature of the generated sequences, they will
	not affect commands after the reserved space.
	Treat the state that can: be affected by the provided
	sname:VkIndirectCommandsLayoutNVX as undefined.

	[open,refpage='vkCmdProcessCommandsNVX',desc='Performs the generation of commands on the device',type='protos']
	--

	The actual generation on the device is handled with:

	include::../../api/protos/vkCmdProcessCommandsNVX.txt[]

	* pname:commandBuffer is the primary command buffer in which the
	generation process takes space.
	* pname:pProcessCommandsInfo is a pointer to an instance of the
	slink:VkCmdProcessCommandsInfoNVX structure containing parameters
	affecting the processing of commands.

	include::../../validity/protos/vkCmdProcessCommandsNVX.txt[]
	--

	[open,refpage='VkCmdProcessCommandsInfoNVX',desc='Structure specifying parameters for the generation of commands',type='structs']
	--

	include::../../api/structs/VkCmdProcessCommandsInfoNVX.txt[]

	* pname:sType is the type of this structure.
	* pname:pNext is `NULL` or a pointer to an extension-specific structure.
	* pname:objectTable is the slink:VkObjectTableNVX to be used for the
	generation process.
	Only registered objects at the time
	flink:vkCmdReserveSpaceForCommandsNVX is called, will be taken into
	account for the reservation.
	* pname:indirectCommandsLayout is the slink:VkIndirectCommandsLayoutNVX
	that provides the command sequence to generate.
	* pname:indirectCommandsTokenCount defines the number of input tokens
	used.
	* pname:pIndirectCommandsTokens provides an array of
	slink:VkIndirectCommandsTokenNVX that reference the input data for each
	token command.
	* pname:maxSequencesCount is the maximum number of sequences for which
	command buffer space will be reserved.
	If pname:sequencesCountBuffer is dlink:VK_NULL_HANDLE, this is also the
	actual number of sequences generated.
	* pname:targetCommandBuffer can: be the secondary slink:VkCommandBuffer in
	which the commands should be recorded.
	If pname:targetCommandBuffer is `NULL` an implicit reservation as well
	as execution takes place on the processing sname:VkCommandBuffer.
	* pname:sequencesCountBuffer can: be slink:VkBuffer from which the actual
	amount of sequences is sourced from as ftext:uint32_t value.
	* pname:sequencesCountOffset is the byte offset into
	pname:sequencesCountBuffer where the count value is stored.
	* pname:sequencesIndexBuffer must: be set if
	pname:indirectCommandsLayout's
	ename:VK_INDIRECT_COMMANDS_LAYOUT_USAGE_INDEXED_SEQUENCES_BIT is set and
	provides the used sequence indices as ftext:uint32_t array.
	Otherwise it must: be dlink:VK_NULL_HANDLE.
	* pname:sequencesIndexOffset is the byte offset into
	pname:sequencesIndexBuffer where the index values start.


	.Valid Usage
	****
	* [[VUID-VkCmdProcessCommandsInfoNVX-objectTable-01331]]
	The provided pname:objectTable must: include all objects referenced by
	the generation process.
	* [[VUID-VkCmdProcessCommandsInfoNVX-indirectCommandsTokenCount-01332]]
	pname:indirectCommandsTokenCount must: match the
	pname:indirectCommandsLayout's pname:tokenCount.
	* [[VUID-VkCmdProcessCommandsInfoNVX-tokenType-01333]]
	The pname:tokenType member of each entry in the
	pname:pIndirectCommandsTokens array must: match the values used at
	creation time of pname:indirectCommandsLayout
	* [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01334]]
	If pname:targetCommandBuffer is provided, it must: have reserved command
	space.
	* [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01335]]
	If pname:targetCommandBuffer is provided, the pname:objectTable must:
	match the reservation's objectTable and must: have had all referenced
	objects registered at reservation time.
	* [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01336]]
	If pname:targetCommandBuffer is provided, the
	pname:indirectCommandsLayout must: match the reservation's
	indirectCommandsLayout.
	* [[VUID-VkCmdProcessCommandsInfoNVX-targetCommandBuffer-01337]]
	If pname:targetCommandBuffer is provided, the pname:maxSequencesCount
	must: not exceed the reservation's maxSequencesCount.
	* [[VUID-VkCmdProcessCommandsInfoNVX-sequencesCountBuffer-01338]]
	If pname:sequencesCountBuffer is used, its usage flag must: have
	ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set.
	* [[VUID-VkCmdProcessCommandsInfoNVX-sequencesCountBuffer-01339]]
	If pname:sequencesCountBuffer is used, pname:sequencesCountOffset must:
	be aligned to
	sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceCountBufferOffsetAlignment.
	* [[VUID-VkCmdProcessCommandsInfoNVX-sequencesIndexBuffer-01340]]
	If pname:sequencesIndexBuffer is used, its usage flag must: have
	ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set.
	* [[VUID-VkCmdProcessCommandsInfoNVX-sequencesIndexBuffer-01341]]
	If pname:sequencesIndexBuffer is used, pname:sequencesIndexOffset must:
	be aligned to
	sname:VkDeviceGeneratedCommandsLimitsNVX::pname:minSequenceIndexBufferOffsetAlignment.
	****

	include::../../validity/structs/VkCmdProcessCommandsInfoNVX.txt[]
	--

	Referencing the functions defined in <<indirectmdslayout>>,
	fname:vkCmdProcessCommandsNVX behaves as:

	[source,c]
	---------------------------------------------------
	// For targetCommandBuffers the existing reservedSpace is reset & overwritten.

	VkCommandBuffer cmd = targetCommandBuffer ?
	targetCommandBuffer.reservedSpace :
	commandBuffer;

	uint32_t sequencesCount = sequencesCountBuffer ?
	min(maxSequencesCount, sequencesCountBuffer.load_uint32(sequencesCountOffset) :
	maxSequencesCount;


	cmdProcessAllSequences(cmd, objectTable,
	indirectCommandsLayout, pIndirectCommandsTokens,
	sequencesCount,
	sequencesIndexBuffer, sequencesIndexOffset);

	// The stateful commands within indirectCommandsLayout will not
	// affect the state of subsequent commands in the target
	// command buffer (cmd)
	---------------------------------------------------

	[NOTE]
	.Note
	====
	It is important to note that the state that may be affected through
	generated commands must: be considered undefined for the commands following
	them.
	It is not possible to setup generated state and provoking work that uses
	this state outside of the generated sequence.
	====