diff --git a/ChangeLog.adoc b/ChangeLog.adoc index 6485655da..33a6f5132 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -14,6 +14,32 @@ appears frequently in the change log. ----------------------------------------------------- +Change log for September 29, 2023 Vulkan 1.3.266 spec update: + +Github Issues + + * Fix slink:VkGraphicsPipelineCreateInfo VU to say a valid pipeline layout + is always needed without a graphics pipeline library (public issue + 2168). + * Add missing "`not`" to <> VU 04917 (public PR 2229). + * Add riscv64 64-bit platform to `vk_platform.h` (public PR 2238). + * Add driver ID for AGXV (Asahi) (public PR 2238). + +Internal Issues + + * Fix common draw dynamic state VUs to check for pname:stencilTestEnable + and pname:depthBoundsTestEnable (internal issue 3486) + * Fix stride passed to flink:vkGetQueryPoolResults in example code in + apiext:VK_KHR_performance_query appendix (internal MR 6148). + +New Extensions + + * apiext:VK_ANDROID_external_format_resolve + * apiext:VK_NV_low_latency2 + +----------------------------------------------------- + Change log for September 22, 2023 Vulkan 1.3.265 spec update: Github Issues diff --git a/Makefile b/Makefile index 4469a71de..3ebe0ac48 100644 --- a/Makefile +++ b/Makefile @@ -126,7 +126,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 265 +PATCHVERSION = 266 BASEOPTS = ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS))) diff --git a/appendices/VK_ANDROID_external_format_resolve.adoc b/appendices/VK_ANDROID_external_format_resolve.adoc new file mode 100644 index 000000000..79a1ee76a --- /dev/null +++ b/appendices/VK_ANDROID_external_format_resolve.adoc @@ -0,0 +1,38 @@ +// Copyright 2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_ANDROID_external_format_resolve.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-05-03 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Tobias Hector, AMD + - Chris Forbes, Google + - Jan-Harald Fredriksen, Arm + - Shahbaz Youssefi, Google + - Matthew Netsch, Qualcomm + - Tony Zlatsinki, Nvidia + - Daniel Koch, Nvidia + - Jeff Leger, Qualcomm + - Alex Walters, Imagination + - Andrew Garrard, Imagination + - Ralph Potter, Samsung + - Ian Elliott, Google + +=== Description + +This extension enables rendering to Android Hardware Buffers with external +formats which cannot be directly represented as renderable in Vulkan, +including {YCbCr} formats. + +include::{generated}/interfaces/VK_ANDROID_external_format_resolve.adoc[] + +=== Version History + + * Revision 1, 2023-05-34 (Tobias Hector) + ** Initial version diff --git a/appendices/VK_KHR_performance_query.adoc b/appendices/VK_KHR_performance_query.adoc index db2dc0f1c..23f098d30 100644 --- a/appendices/VK_KHR_performance_query.adoc +++ b/appendices/VK_KHR_performance_query.adoc @@ -294,7 +294,7 @@ result = vkGetQueryPoolResults( 1, sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount, recordedCounters, - sizeof(VkPerformanceCounterResultKHR), + sizeof(VkPerformanceCounterResultKHR) * enabledCounterCount, NULL); // recordedCounters is filled with our counters, we will look at one for posterity diff --git a/appendices/VK_NV_low_latency2.adoc b/appendices/VK_NV_low_latency2.adoc new file mode 100644 index 000000000..3461b3610 --- /dev/null +++ b/appendices/VK_NV_low_latency2.adoc @@ -0,0 +1,44 @@ +// Copyright 2019-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_NV_low_latency2.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-09-25 +*Contributors*:: + - Charles Hansen, NVIDIA + - Liam Middlebrook, NVIDIA + - Lionel Duc, NVIDIA + - James Jones, NVIDIA + - Eric Sullivan, NVIDIA + +include::{generated}/interfaces/VK_NV_low_latency2.adoc[] + +=== Description + +This extension gives applications timing suggestions on when to start the +recording of new frames to reduce the latency between input sampling and +frame presentation. +Applications can accomplish this through the extension by calling +flink:vkSetLatencySleepModeNV to allow the driver to pace a given swapchain, +then calling flink:vkLatencySleepNV before input sampling to delay the start +of the CPU side work. +Additional methods and structures are provided to give insight into the +latency pipeline of an application through the latency markers. +`apiext:VK_NV_low_latency` provides legacy support for applications that +make use of the NVIDIA Reflex SDK whereas new implementations should use the +`apiext:VK_NV_low_latency2` extension. + +=== Issues + +1) How does Low Latency 2 work with applications that utilize device groups? + +Low Latency 2 does not support device groups. + +=== Version History + + * Revision 1, 2023-09-25 (Charles Hansen) + ** Internal revisions diff --git a/chapters/VK_NV_low_latency2/low_latency2.adoc b/chapters/VK_NV_low_latency2/low_latency2.adoc new file mode 100644 index 000000000..24dcba06b --- /dev/null +++ b/chapters/VK_NV_low_latency2/low_latency2.adoc @@ -0,0 +1,384 @@ +// Copyright 2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + + +ifdef::VK_NV_low_latency2[] + +[[low-latency2]] += Low Latency 2 + +== Latency Reduction +[open,refpage='vkSetLatencySleepModeNV',desc='Enable or Disable low latency mode on a swapchain',type='protos'] +-- +To enable or disable low latency mode on a swapchain, call: + +include::{generated}/api/protos/vkSetLatencySleepModeNV.adoc[] + + * pname:device is the device associated with pname:swapchain. + * pname:swapchain is the swapchain to enable or disable low latency mode + on. + * pname:pSleepModeInfo is `NULL` or a pointer to a + slink:VkLatencySleepModeInfoNV structure specifying the parameters of + the latency sleep mode. + +If pname:pSleepModeInfo is `NULL`, fname:vkSetLatencySleepModeNV will +disable low latency mode, low latency boost, and set the minimum present +interval previously specified by slink:VkLatencySleepModeInfoNV to zero on +pname:swapchain. + +include::{generated}/validity/protos/vkSetLatencySleepModeNV.adoc[] +-- + +[open,refpage='VkLatencySleepModeInfoNV',desc='Structure to set low latency mode',type='structs'] +-- +The sname:VkLatencySleepModeInfoNV structure is defined as: + +include::{generated}/api/structs/VkLatencySleepModeInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:lowLatencyMode is the toggle to enable or disable low latency + mode. + * pname:lowLatencyBoost allows an application to hint to the GPU to + increase performance to provide additional latency savings at a cost of + increased power consumption. + * pname:minimumPresentIntervalUs is the microseconds between + flink:vkQueuePresentKHR calls for a given swapchain that + flink:vkLatencySleepNV will enforce. + +If pname:lowLatencyMode is set to ename:VK_FALSE, pname:lowLatencyBoost will +still hint to the GPU to increase its power state and fname:vkLatencySleepNV +will still enforce pname:minimumIntervalUs between fname:vkQueuePresentKHR +calls. + +include::{generated}/validity/structs/VkLatencySleepModeInfoNV.adoc[] +-- + +[open, refpage='vkLatencySleepNV',desc='Trigger low latency mode Sleep',type='protos'] +-- +To provide the synchronization primitive used to delay host CPU work for +lower latency rendering, call: + +include::{generated}/api/protos/vkLatencySleepNV.adoc[] + + * pname:device is the device associated with pname:swapchain. + * pname:swapchain is the swapchain to delay associated CPU work based on + slink:VkLatencySubmissionPresentIdNV submissions. + * pname:pSleepInfo is a pointer to a slink:VkLatencySleepInfoNV structure + specifying the parameters of the latency sleep. + +fname:vkLatencySleepNV returns immediately. +Applications should: use flink:vkWaitSemaphores with +pname:pSleepInfo::pname:signalSemaphore to delay host CPU work. +CPU work refers to application work done before presenting which includes +but is not limited to: input sampling, simulation, command buffer recording, +command buffer submission, and present submission. +It is recommended to call this function before input sampling. +When using this function, it should: be called exactly once between +presents. + +include::{generated}/validity/protos/vkLatencySleepNV.adoc[] +-- + +[open, refpage='VkLatencySleepInfoNV',desc='Structure specifying the parameters of vkLatencySleepNV',type='structs'] +-- +The sname:VkLatencySleepInfoNV structure is defined as: + +include::{generated}/api/structs/VkLatencySleepInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:signalSemaphore is a semaphore that is signaled to indicate that + the application should: resume input sampling work. + * pname:value is the value that pname:signalSemaphore is set to for + resuming sampling work. + +.Valid Usage +**** + * [[VUID-VkLatencySleepInfoNV-signalSemaphore-09361]] + pname:signalSemaphore must: be a timeline semaphore +**** + +include::{generated}/validity/structs/VkLatencySleepInfoNV.adoc[] +-- + +[open, refpage='vkSetLatencyMarkerNV',desc='Pass in marker for timing info',type='protos'] +-- +An application can: provide timestamps at various stages of its frame +generation work by calling: + +include::{generated}/api/protos/vkSetLatencyMarkerNV.adoc[] + + * pname:device is the device associated with pname:swapchain. + * pname:swapchain is the swapchain to capture timestamps on. + * pname:pSetLatencyMarkerInfo is a pointer to a + slink:VkSetLatencyMarkerInfoNV structure specifying the parameters of + the marker to set. + +At the beginning and end of simulation and render threads and beginning and +end of flink:vkQueuePresentKHR calls, fname:vkSetLatencyMarkerNV can: be +called to provide timestamps for the application's reference. +These timestamps are returned with a call to flink:vkGetLatencyTimingsNV +alongside driver provided timestamps at various points of interest with +regards to latency within the application. + +include::{generated}/validity/protos/vkSetLatencyMarkerNV.adoc[] +-- + +[open, refpage='VkSetLatencyMarkerInfoNV',desc='Structure specifying the parameters of vkSetLatencyMarkerNV',type='structs'] +-- +The sname:VkSetLatencyMarkerInfoNV structure is defined as: + +include::{generated}/api/structs/VkSetLatencyMarkerInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:presentId is an application provided value that is used to + associate the timestamp with a fname:vkQueuePresentKHR command using + slink:VkPresentIdKHR::pname:pPresentIds for a given present. + * pname:marker is the type of timestamp to be recorded. + +include::{generated}/validity/structs/VkSetLatencyMarkerInfoNV.adoc[] +-- + +[open,refpage='VkLatencyMarkerNV',desc='Structure used to mark different points in latency',type='enums'] +-- +The elink:VkLatencyMarkerNV enum is defined as: + +include::{generated}/api/enums/VkLatencyMarkerNV.adoc[] + +The members of the elink:VkLatencyMarkerNV are used as arguments for +flink:vkSetLatencyMarkerNV in the use cases described below: + + * ename:VK_LATENCY_MARKER_SIMULATION_START_NV should: be called at the + start of the simulation execution each frame, but after the call to + fname:vkLatencySleepNV. + * ename:VK_LATENCY_MARKER_SIMULATION_END_NV should: be called at the end + of the simulation execution each frame. + * ename:VK_LATENCY_MARKER_RENDERSUBMIT_START_NV should: be called at the + beginning of the render submission execution each frame. + This should: be wherever Vulkan API calls are made and must: not span + into asynchronous rendering. + * ename:VK_LATENCY_MARKER_RENDERSUBMIT_END_NV should: be called at the end + of the render submission execution each frame. + * ename:VK_LATENCY_MARKER_PRESENT_START_NV should: be called just before + fname:vkQueuePresentKHR. + * ename:VK_LATENCY_MARKER_PRESENT_END_NV should: be called when + fname:vkQueuePresentKHR returns. + * ename:VK_LATENCY_MARKER_INPUT_SAMPLE_NV should: be called just before + the application gathers input data. + * ename:VK_LATENCY_MARKER_TRIGGER_FLASH_NV should: be called anywhere + between ename:VK_LATENCY_MARKER_SIMULATION_START_NV and + ename:VK_LATENCY_MARKER_SIMULATION_END_NV whenever a left mouse click + occurs. +-- + +[open, refpage='vkGetLatencyTimingsNV',desc='Get latency marker results',type='protos'] +-- +To get an array containing the newest collected latency data, call: + +include::{generated}/api/protos/vkGetLatencyTimingsNV.adoc[] + + * pname:device is the device associated with pname:swapchain. + * pname:swapchain is the swapchain to return data from. + * pname:pTimingCount is a pointer to an integer related to the number of + of previous frames of latency data available or queried, as described + below. + * pname:pGetLatencyMarkerInfo is a pointer to a + slink:VkGetLatencyMarkerInfoNV structure specifying the parameters for + returning latency information. + +The timings returned by fname:vkGetLatencyTimingsNV contain the timestamps +requested from flink:vkSetLatencyMarkerNV and additional +implementation-specific markers defined in +slink:VkLatencyTimingsFrameReportNV. +If pname:pTimings is `NULL`, then the maximum number of queryable frame data +is returned in pname:pTimingCount. +Otherwise, pname:pTimingCount must: point to a variable set by the user to +the number of elements in the pname:pTimings array in +pname:pGetLatencyMarkerInfo, and on return the variable is overwritten with +the number of values actually written to pname:pTimings. + +include::{generated}/validity/protos/vkGetLatencyTimingsNV.adoc[] +-- + +[open, refpage='VkGetLatencyMarkerInfoNV',desc='Structure specifying the parameters of vkGetLatencyTimingsNV',type='structs'] +-- +The sname:VkGetLatencyMarkerInfoNV structure is defined as: + +include::{generated}/api/structs/VkGetLatencyMarkerInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is either `NULL` or a pointer to a structure extending this + structure. + * pname:pTimings is either `NULL` or a pointer to an array of + slink:VkLatencyTimingsFrameReportNV structures. + +The elements of pname:pTimings are arranged in the order they were requested +in, with the oldest data in the first entry. + +include::{generated}/validity/structs/VkGetLatencyMarkerInfoNV.adoc[] +-- + +[open,refpage='VkLatencyTimingsFrameReportNV',desc='Structure containing latency data',type='structs'] +-- +The slink:VkLatencyTimingsFrameReportNV structure describes latency data +returned by flink:vkGetLatencyTimingsNV + +include::{generated}/api/structs/VkLatencyTimingsFrameReportNV.adoc[] + +The members of the slink:VkLatencyTimingsFrameReportNV structure describe +the following: + + * pname:presentId is the application provided value that is used to + associate the timestamp with a fname:vkQueuePresentKHR command using + slink:VkPresentIdKHR::pname:pPresentIds for a given present. + * pname:simStartTimeUs is the timestamp written when + fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV + enum ename:VK_LATENCY_MARKER_SIMULATION_START_NV. + * pname:simEndTimeUs is the timestamp written when + fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV + enum ename:VK_LATENCY_MARKER_SIMULATION_END_NV + * pname:renderStartTimeUs is the timestamp written when + fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV + enum ename:VK_LATENCY_MARKER_RENDERSUBMIT_START_NV. + * pname:renderEndTimeUs is the timestamp written when + fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV + enum ename:VK_LATENCY_MARKER_RENDERSUBMIT_END_NV. + * pname:presentStartTimeUs is the timestamp written when + fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV + enum ename:VK_LATENCY_MARKER_PRESENT_START_NV. + * pname:presentEndTimeUs is the timestamp written when + fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV + enum ename:VK_LATENCY_MARKER_PRESENT_END_NV. + * pname:driverStartTimeUs is the timestamp written when the first + fname:vkQueueSubmit for the frame is called. + * pname:driverEndTimeUs is the timestamp written when the final + fname:vkQueueSubmit hands off from the Vulkan Driver. + * pname:osRenderQueueStartTimeUs is the timestamp written when the final + fname:vkQueueSubmit hands off from the Vulkan Driver. + * pname:osRenderQueueEndTimeUs is the timestamp written when the first + submission reaches the GPU. + * pname:gpuRenderStartTimeUs is the timestamp written when the first + submission reaches the GPU. + * pname:gpuRenderEndTimeUs is the timestamp written when the final + submission finishes on the GPU for the frame. + +include::{generated}/validity/structs/VkLatencyTimingsFrameReportNV.adoc[] +-- + +[open,refpage='VkLatencySubmissionPresentIdNV',desc='Structure used to associate a queueSubmit with a presentId',type='structs'] +-- +The slink:VkLatencySubmissionPresentIdNV structure is defined as: + +include::{generated}/api/structs/VkLatencySubmissionPresentIdNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:presentId is used to associate the fname:vkQueueSubmit with the + presentId used for a given fname:vkQueuePresentKHR via + slink:VkPresentIdKHR::pname:pPresentIds. + +For any submission to be tracked with low latency mode pacing, it needs to +be associated with other submissions in a given present. +Applications :must include the VkLatencySubmissionPresentIdNV in the pNext +chain of flink:vkQueueSubmit to associate that submission with the +pname:presentId present for low latency mode. + +include::{generated}/validity/structs/VkLatencySubmissionPresentIdNV.adoc[] +-- + +[open,refpage='vkQueueNotifyOutOfBandNV',desc='Notify out of band queue',type='protos'] +-- +An application can mark a queue as Out of Band to indicate that all +fname:vkQueueSubmit calls on this queue are ignored for latency evaluation +by calling: +include::{generated}/api/protos/vkQueueNotifyOutOfBandNV.adoc[] + + * pname:queue is the VkQueue to be marked as out of band. + * pname:pQueueTypeInfo is a pointer to a slink:VkOutOfBandQueueTypeInfoNV + structure specifying the queue type. + +include::{generated}/validity/protos/vkQueueNotifyOutOfBandNV.adoc[] +-- + +[open,refpage='VkOutOfBandQueueTypeInfoNV',desc='Structure used to describe the queue that is being marked as Out of Band',type='structs'] +-- +The slink:VkOutOfBandQueueTypeInfoNV structure is defined as: + +include::{generated}/api/structs/VkOutOfBandQueueTypeInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:queueType describes the usage of the queue to be marked as out of + band. + +include::{generated}/validity/structs/VkOutOfBandQueueTypeInfoNV.adoc[] +-- + +[open,refpage='VkOutOfBandQueueTypeNV',desc='Type of out of band queue',type='enums'] +-- +The elink:VkOutOfBandQueueTypeNV enum is defined as: + +include::{generated}/api/enums/VkOutOfBandQueueTypeNV.adoc[] + +The members of the elink:VkOutOfBandQueueTypeNV are used to describe the +queue type in slink:VkOutOfBandQueueTypeInfoNV as described below: + + * ename:VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV indicates that work will be + submitted to this queue. + * ename:VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV indicates that this queue + will be presented from. +-- + +[open,refpage='VkSwapchainLatencyCreateInfoNV',desc='Specify that a swapchain will use low latency mode',type='structs'] +-- +To allow low latency mode to be used by a swapchain, add a +sname:VkSwapchainLatencyCreateInfoNV structure to the pname:pNext chain of +slink:VkSwapchainCreateInfoKHR. + +The sname:VkSwapchainLatencyCreateInfoNV structure is defined as: + +include::{generated}/api/structs/VkSwapchainLatencyCreateInfoNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:lowLatencyModeEnable indicates if the swapchain created will + utilize low latency mode. + +include::{generated}/validity/structs/VkSwapchainLatencyCreateInfoNV.adoc[] +-- + +[open,refpage='VkLatencySurfaceCapabilitiesNV',desc='Structure describing surface optimized presentation modes for use with low latency mode',type='structs'] +-- +The sname:VkLatencySurfaceCapabilitiesNV structure is defined as: + +include::{generated}/api/structs/VkLatencySurfaceCapabilitiesNV.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:presentModeCount is the number of presentation modes provided. + * pname:pPresentModes is list of presentation modes optimized for use with + low latency mode with pname:presentModeCount entries. + +If pname:pPresentModes is `NULL`, then the number of present modes that are +optimized for use with low latency mode returned in pname:presentModeCount. +Otherwise, pname:presentModeCount must be set by the user to the number of +elements in the pname:pPresentModes array, and on return the variable is +overwritten with the number of values actually written to +pname:pPresentModes. +If the value of pname:presentModeCount is less than the number of optimized +present modes, at most pname:presentModeCount values will be written to +pname:pPresentModes. + +include::{generated}/validity/structs/VkLatencySurfaceCapabilitiesNV.adoc[] +-- +endif::VK_NV_low_latency2[] diff --git a/chapters/clears.adoc b/chapters/clears.adoc index 3faca90f6..80aa04ec3 100644 --- a/chapters/clears.adoc +++ b/chapters/clears.adoc @@ -360,6 +360,12 @@ ifdef::VK_VERSION_1_1,VK_KHR_multiview[] If the render pass instance this is recorded in uses multiview, then pname:baseArrayLayer must: be zero and pname:layerCount must: be one endif::VK_VERSION_1_1,VK_KHR_multiview[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-vkCmdClearAttachments-aspectMask-09298]] + If the subpass this is recorded in performs an external format resolve, + the pname:aspectMask member of any element of pname:pAttachments must: + not include `VK_IMAGE_ASPECT_PLANE__{ibit}__BIT_EXT` for any index _i_ +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/protos/vkCmdClearAttachments.adoc[] diff --git a/chapters/cmdbuffers.adoc b/chapters/cmdbuffers.adoc index 1363bfea5..6b0987615 100644 --- a/chapters/cmdbuffers.adoc +++ b/chapters/cmdbuffers.adoc @@ -3132,6 +3132,27 @@ ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples must: be equal to the sample count used to create that image view endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-vkCmdExecuteCommands-pNext-09299]] + If fname:vkCmdExecuteCommands is being called within a render pass + instance begun with flink:vkCmdBeginRendering, with any color attachment + using a resolve mode of + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, the + pname:pNext chain of slink:VkCommandBufferInheritanceInfo used to create + each element of pname:pCommandBuffers must: include a + slink:VkExternalFormatANDROID structure with a pname:externalFormat + matching that used to create the resolve attachment in the render pass + * [[VUID-vkCmdExecuteCommands-pNext-09300]] + If fname:vkCmdExecuteCommands is being called within a render pass + instance begun with flink:vkCmdBeginRendering with any color attachment + using a resolve mode of + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the + pname:pNext chain of slink:VkCommandBufferInheritanceInfo does not + include a slink:VkAttachmentSampleCountInfoAMD or + slink:VkAttachmentSampleCountInfoNV structure, the value of + slink:VkCommandBufferInheritanceRenderingInfo::pname:rasterizationSamples + must: be ename:VK_SAMPLE_COUNT_1_BIT +endif::VK_ANDROID_external_format_resolve[] endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] **** diff --git a/chapters/commonvalidity/attachment_description_common.adoc b/chapters/commonvalidity/attachment_description_common.adoc index d11ca17af..8c286f632 100644 --- a/chapters/commonvalidity/attachment_description_common.adoc +++ b/chapters/commonvalidity/attachment_description_common.adoc @@ -4,8 +4,6 @@ // Common Valid Usage // Common to attachment description structures - * [[VUID-{refpage}-format-06698]] - pname:format must: not be ename:VK_FORMAT_UNDEFINED * [[VUID-{refpage}-format-06699]] If pname:format includes a color or depth component and pname:loadOp is ename:VK_ATTACHMENT_LOAD_OP_LOAD, then pname:initialLayout must: not be diff --git a/chapters/commonvalidity/draw_common.adoc b/chapters/commonvalidity/draw_common.adoc index 94a7f6589..4747a7cb0 100644 --- a/chapters/commonvalidity/draw_common.adoc +++ b/chapters/commonvalidity/draw_common.adoc @@ -220,7 +220,8 @@ ifdef::VK_EXT_shader_object[] endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07836]] If the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled then + ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS dynamic state enabled, and if the + current pname:depthBoundsTestEnable state is ename:VK_TRUE, then flink:vkCmdSetDepthBounds must: have been called in the current command buffer prior to this drawing command ifdef::VK_EXT_shader_object[] @@ -235,7 +236,8 @@ ifdef::VK_EXT_shader_object[] endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07837]] If the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled then + ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK dynamic state enabled, and + if the current pname:stencilTestEnable state is ename:VK_TRUE, then flink:vkCmdSetStencilCompareMask must: have been called in the current command buffer prior to this drawing command ifdef::VK_EXT_shader_object[] @@ -248,7 +250,8 @@ ifdef::VK_EXT_shader_object[] endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07838]] If the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled then + ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK dynamic state enabled, and if + the current pname:stencilTestEnable state is ename:VK_TRUE, then flink:vkCmdSetStencilWriteMask must: have been called in the current command buffer prior to this drawing command ifdef::VK_EXT_shader_object[] @@ -261,7 +264,8 @@ ifdef::VK_EXT_shader_object[] endif::VK_EXT_shader_object[] * [[VUID-{refpage}-None-07839]] If the bound graphics pipeline state was created with the - ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled then + ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE dynamic state enabled, and if + the current pname:stencilTestEnable state is ename:VK_TRUE, then flink:vkCmdSetStencilReference must: have been called in the current command buffer prior to this drawing command ifdef::VK_EXT_shader_object[] @@ -841,6 +845,117 @@ ifdef::VK_EXT_dynamic_rendering_unused_attachments[] to create the currently bound pipeline equal to ename:VK_FORMAT_UNDEFINED endif::VK_EXT_dynamic_rendering_unused_attachments[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-{refpage}-colorAttachmentCount-09362]] + If the current render pass instance was begun with + flink:vkCmdBeginRendering, with a + slink:VkRenderingInfo::pname:colorAttachmentCount equal to `1`, +ifdef::VK_EXT_shader_object[] + there is no shader object bound to any graphics stage, +endif::VK_EXT_shader_object[] + and a color attachment with a resolve mode of + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, each element + of the slink:VkRenderingInfo::pname:pColorAttachments array with a + pname:resolveImageView not equal to dlink:VK_NULL_HANDLE must: have been + created with an image created with a + slink:VkExternalFormatANDROID::pname:externalFormat value equal to the + slink:VkExternalFormatANDROID::pname:externalFormat value used to create + the currently bound graphics pipeline + * [[VUID-{refpage}-None-09363]] + If +ifdef::VK_EXT_shader_object[] + there is no shader object bound to any graphics stage, +endif::VK_EXT_shader_object[] + the current render pass instance was begun with + flink:vkCmdBeginRendering and a + slink:VkRenderingInfo::pname:colorAttachmentCount equal to `1`, and a + color attachment with a resolve mode of + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, each element + of the slink:VkRenderingInfo::pname:pColorAttachments array with a + pname:imageView not equal to dlink:VK_NULL_HANDLE must: have been + created with an image created with a + slink:VkExternalFormatANDROID::pname:externalFormat value equal to the + slink:VkExternalFormatANDROID::pname:externalFormat value used to create + the currently bound graphics pipeline +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-{refpage}-None-09364]] + If the current render pass instance was begun with + flink:vkCmdBeginRendering, +ifdef::VK_EXT_shader_object[] + there is no shader object bound to any graphics stage, +endif::VK_EXT_shader_object[] + and the currently bound graphics pipeline was created with a non-zero + slink:VkExternalFormatANDROID::pname:externalFormat value and with the + ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT dynamic state enabled, + then flink:vkCmdSetColorBlendEnableEXT must: have set the blend enable + to ename:VK_FALSE prior to this drawing command + * [[VUID-{refpage}-None-09365]] + If the current render pass instance was begun with + flink:vkCmdBeginRendering, +ifdef::VK_EXT_shader_object[] + there is no shader object bound to any graphics stage, +endif::VK_EXT_shader_object[] + and the currently bound graphics pipeline was created with a non-zero + slink:VkExternalFormatANDROID::pname:externalFormat value and with the + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT dynamic state enabled, + then flink:vkCmdSetRasterizationSamplesEXT must: have set + pname:rasterizationSamples to ename:VK_SAMPLE_COUNT_1_BIT prior to this + drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-None-09366]] + If there is a shader object bound to any graphics stage, and the current + render pass includes a color attachment that uses the + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID resolve mode, + then flink:vkCmdSetColorBlendEnableEXT must: have set blend enable to + ename:VK_FALSE prior to this drawing command + * [[VUID-{refpage}-rasterizationSamples-09367]] + If there is a shader object bound to any graphics stage, and the current + render pass includes a color attachment that uses the + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID resolve mode, + then flink:vkCmdSetRasterizationSamplesEXT must: have set + pname:rasterizationSamples to ename:VK_SAMPLE_COUNT_1_BIT prior to this + drawing command +endif::VK_EXT_shader_object[] +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-{refpage}-None-09368]] + If the current render pass instance was begun with + flink:vkCmdBeginRendering, +ifdef::VK_EXT_shader_object[] + there is no shader object bound to any graphics stage, +endif::VK_EXT_shader_object[] + and the currently bound graphics pipeline was created with a non-zero + slink:VkExternalFormatANDROID::pname:externalFormat value and with the + ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR dynamic state enabled, + then flink:vkCmdSetFragmentShadingRateKHR must: have set + pname:pFragmentSize->width to `1` prior to this drawing command + * [[VUID-{refpage}-None-09369]] + If the current render pass instance was begun with + flink:vkCmdBeginRendering, +ifdef::VK_EXT_shader_object[] + there is no shader object bound to any graphics stage, +endif::VK_EXT_shader_object[] + and the currently bound graphics pipeline was created with a non-zero + slink:VkExternalFormatANDROID::pname:externalFormat value and with the + ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR dynamic state enabled, + then flink:vkCmdSetFragmentShadingRateKHR must: have set + pname:pFragmentSize->height to `1` prior to this drawing command +ifdef::VK_EXT_shader_object[] + * [[VUID-{refpage}-pFragmentSize-09370]] + If there is a shader object bound to any graphics stage, and the current + render pass includes a color attachment that uses the + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID resolve mode, + then flink:vkCmdSetFragmentShadingRateKHR must: have set + pname:pFragmentSize->width to `1` prior to this drawing command + * [[VUID-{refpage}-pFragmentSize-09371]] + If there is a shader object bound to any graphics stage, and the current + render pass includes a color attachment that uses the + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID resolve mode, + then flink:vkCmdSetFragmentShadingRateKHR must: have set + pname:pFragmentSize->height to `1` prior to this drawing command +endif::VK_EXT_shader_object[] +endif::VK_KHR_fragment_shading_rate[] +endif::VK_ANDROID_external_format_resolve[] ifdef::VK_EXT_color_write_enable[] * [[VUID-{refpage}-None-07749]] If the bound graphics pipeline state was created with the @@ -2238,6 +2353,16 @@ endif::VK_EXT_mesh_shader[] * [[VUID-{refpage}-None-08879]] All bound graphics shader objects must: have been created with identical or identically defined arrays of descriptor set layouts +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-{refpage}-colorAttachmentCount-09372]] + If the current render pass instance was begun with + flink:vkCmdBeginRendering and a + slink:VkRenderingInfo::pname:colorAttachmentCount equal to `1`, a color + attachment with a resolve mode of + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and a fragment + shader is bound, it must: not declare the code:DepthReplacing or + code:StencilRefReplacingEXT execution modes +endif::VK_ANDROID_external_format_resolve[] endif::VK_EXT_shader_object[] ifdef::VK_EXT_attachment_feedback_loop_dynamic_state[] * [[VUID-{refpage}-None-08880]] diff --git a/chapters/commonvalidity/pipeline_barrier_common.adoc b/chapters/commonvalidity/pipeline_barrier_common.adoc index 57231db39..10fe328bf 100644 --- a/chapters/commonvalidity/pipeline_barrier_common.adoc +++ b/chapters/commonvalidity/pipeline_barrier_common.adoc @@ -35,8 +35,24 @@ endif::VK_KHR_multiview,VK_VERSION_1_1[] If fname:{refpage} is called within a render pass instance using a slink:VkRenderPass object, the pname:image member of any image memory barrier included in this command must: be an attachment used in the - current subpass both as an input attachment, and as either a color or - depth/stencil attachment + current subpass both as an input attachment, and as either a color, +ifdef::VK_ANDROID_external_format_resolve[] + color resolve, +endif::VK_ANDROID_external_format_resolve[] + or depth/stencil attachment +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-{refpage}-image-09373]] + If fname:{refpage} is called within a render pass instance using a + slink:VkRenderPass object, and the pname:image member of any image + memory barrier is a color resolve attachment, the corresponding color + attachment must: be ename:VK_ATTACHMENT_UNUSED + * [[VUID-{refpage}-image-09374]] + If fname:{refpage} is called within a render pass instance using a + slink:VkRenderPass object, and the pname:image member of any image + memory barrier is a color resolve attachment, it must: have been created + with a non-zero slink:VkExternalFormatANDROID::pname:externalFormat + value +endif::VK_ANDROID_external_format_resolve[] * [[VUID-{refpage}-oldLayout-01181]] If fname:{refpage} is called within a render pass instance, the pname:oldLayout and pname:newLayout members of any image memory barrier diff --git a/chapters/features.adoc b/chapters/features.adoc index a8af34332..aa8a7ed25 100644 --- a/chapters/features.adoc +++ b/chapters/features.adoc @@ -7071,6 +7071,29 @@ include::{generated}/validity/structs/VkPhysicalDeviceDescriptorPoolOverallocati endif::VK_NV_descriptor_pool_overallocation[] +ifdef::VK_ANDROID_external_format_resolve[] + +[open,refpage='VkPhysicalDeviceExternalFormatResolveFeaturesANDROID',desc='Structure describing whether external format resolves are supported',type='structs'] +-- +The sname:VkPhysicalDeviceExternalFormatResolveFeaturesANDROID structure is +defined as: + +include::{generated}/api/structs/VkPhysicalDeviceExternalFormatResolveFeaturesANDROID.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-externalFormatResolve]] pname:externalFormatResolve specifies + whether external format resolves are supported. + +:refpage: VkPhysicalDeviceExternalFormatResolveFeaturesANDROID +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceExternalFormatResolveFeaturesANDROID.adoc[] +-- + +endif::VK_ANDROID_external_format_resolve[] + [[features-requirements]] == Feature Requirements @@ -7892,6 +7915,10 @@ ifdef::VK_NV_descriptor_pool_overallocation[] if the `apiext:VK_NV_descriptor_pool_overallocation` extension is supported. endif::VK_NV_descriptor_pool_overallocation[] +ifdef::VK_ANDROID_external_format_resolve[] + * <>, if the + `apiext:VK_ANDROID_external_format_resolve` extension is supported. +endif::VK_ANDROID_external_format_resolve[] All other features defined in the Specification are optional:. diff --git a/chapters/limits.adoc b/chapters/limits.adoc index f9a51fa2b..dc79063f3 100644 --- a/chapters/limits.adoc +++ b/chapters/limits.adoc @@ -4283,6 +4283,46 @@ include::{generated}/validity/structs/VkPhysicalDeviceShaderEnqueuePropertiesAMD endif::VK_AMDX_shader_enqueue[] +ifdef::VK_ANDROID_external_format_resolve[] +[open,refpage='VkPhysicalDeviceExternalFormatResolvePropertiesANDROID',desc='Structure describing external format resolve supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceExternalFormatResolvePropertiesANDROID structure +is defined as: + +include::{generated}/api/structs/VkPhysicalDeviceExternalFormatResolvePropertiesANDROID.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[limits-nullColorAttachmentWithExternalFormatResolve]] + pname:nullColorAttachmentWithExternalFormatResolve indicates that there + must: be no color attachment image when performing external format + resolves if it is ename:VK_TRUE. + * [[limits-externalFormatResolveChromaOffsetX]] + pname:externalFormatResolveChromaOffsetX indicates the + elink:VkChromaLocation that an implementation uses in the X axis for + accesses to an external format image as a resolve attachment. + This must: be consistent between external format resolves and load + operations from external format resolve attachments to color attachments + when pname:nullColorAttachmentWithExternalFormatResolve is + ename:VK_TRUE. + * [[limits-externalFormatResolveChromaOffsetY]] + pname:externalFormatResolveChromaOffsetY indicates the + elink:VkChromaLocation that an implementation uses in the Y axis for + accesses to an external format image as a resolve attachment. + This must: be consistent between external format resolves and load + operations from external format resolve attachments to color attachments + when pname:nullColorAttachmentWithExternalFormatResolve is + ename:VK_TRUE. + +:refpage: VkPhysicalDeviceExternalFormatResolvePropertiesANDROID +include::{chapters}/limits.adoc[tag=limits_desc] + +include::{generated}/validity/structs/VkPhysicalDeviceExternalFormatResolvePropertiesANDROID.adoc[] +-- +endif::VK_ANDROID_external_format_resolve[] + + [[limits-minmax]] == Limit Requirements diff --git a/chapters/memory.adoc b/chapters/memory.adoc index a2954a32a..3e46ad2e3 100644 --- a/chapters/memory.adoc +++ b/chapters/memory.adoc @@ -2820,8 +2820,8 @@ from flink:vkGetPhysicalDeviceFormatProperties2, and flink:vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters. These sets of features are independent of each other, e.g. the external format will support sampler {YCbCr} conversion even if the non-external -format does not, and writing to non-external format images is possible but -writing to external format images is not. +format does not, and rendering directly to the external format will not be +supported even if the non-external format does support this. ==== Android hardware buffers with the same external format must: have the same @@ -2913,6 +2913,44 @@ sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures. include::{generated}/validity/structs/VkAndroidHardwareBufferFormatProperties2ANDROID.adoc[] -- endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] + +ifdef::VK_ANDROID_external_format_resolve[] +[open,refpage='VkAndroidHardwareBufferFormatResolvePropertiesANDROID',desc='Structure defining properties of resolves using an external format',type='structs'] +-- +The slink:VkAndroidHardwareBufferFormatResolvePropertiesANDROID structure is +defined as: + +include::{generated}/api/structs/VkAndroidHardwareBufferFormatResolvePropertiesANDROID.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:colorAttachmentFormat is a elink:VkFormat specifying the format of + color attachment images that must: be used for color attachments when + resolving to the specified external format. + If the implementation supports external format resolves for the + specified external format, this value will be set to a color format + supporting the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT in + slink:VkFormatProperties::pname:optimalTilingFeatures as returned by + flink:vkGetPhysicalDeviceFormatProperties with pname:format equal to + pname:colorAttachmentFormat If external format resolves are not + supported, this value will be set to `VK_FORMAT_UNDEFINED`. + +Any Android hardware buffer created with the code:GRALLOC_USAGE_HW_RENDER +flag must: be renderable in some way in Vulkan, either: + + * slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format must: + be a format that supports ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT + or ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT in + slink:VkFormatProperties::pname:optimalTilingFeatures; or + * pname:colorAttachmentFormat must: be a format that supports + ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT in + slink:VkFormatProperties::pname:optimalTilingFeatures. + +include::{generated}/validity/structs/VkAndroidHardwareBufferFormatResolvePropertiesANDROID.adoc[] +-- +endif::VK_ANDROID_external_format_resolve[] + endif::VK_ANDROID_external_memory_android_hardware_buffer[] @@ -4132,9 +4170,13 @@ Such _external formats_ are commonly used by external image sources such as video decoders or cameras. Vulkan can: import Android hardware buffers that have external formats, but since the image contents are in an undiscoverable and possibly proprietary -representation, images with external formats must: only be used as sampled -images, must: only be sampled with a sampler that has {YCbCr} conversion -enabled, and must: have optimal tiling. +representation, images with external formats must: only be used as +ifdef::VK_ANDROID_external_format_resolve[] +resolve images or +endif::VK_ANDROID_external_format_resolve[] +sampled images, and must: have optimal tiling. +Images with external formats must: only be sampled with a sampler that has +{YCbCr} conversion enabled. Images that will be backed by an Android hardware buffer can: use an external format by setting slink:VkImageCreateInfo::pname:format to diff --git a/chapters/pipelines.adoc b/chapters/pipelines.adoc index ccd863bc1..24a57733a 100644 --- a/chapters/pipelines.adoc +++ b/chapters/pipelines.adoc @@ -1717,6 +1717,9 @@ endif::VK_AMD_mixed_attachment_samples[] ifdef::VK_NV_framebuffer_mixed_samples[] * slink:VkAttachmentSampleCountInfoNV endif::VK_NV_framebuffer_mixed_samples[] +ifdef::VK_ANDROID_external_format_resolve[] + * slink:VkExternalFormatANDROID +endif::VK_ANDROID_external_format_resolve[] endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] ifdef::VK_EXT_attachment_feedback_loop_layout[] * Inclusion/omission of the @@ -3978,8 +3981,9 @@ ifdef::VK_KHR_pipeline_executable_properties[] endif::VK_KHR_pipeline_executable_properties[] * [[VUID-VkGraphicsPipelineCreateInfo-None-07826]] If the pipeline includes a <>, slink:VkPipelineLayout must: be a valid - pipeline layout + complete set of state>>, and there are no libraries included in + slink:VkPipelineLibraryCreateInfoKHR::pname:pLibraries, then + slink:VkPipelineLayout must: be a valid pipeline layout * [[VUID-VkGraphicsPipelineCreateInfo-layout-07827]] If the pipeline includes a <> specified entirely by libraries, and each @@ -4503,6 +4507,178 @@ endif::VK_EXT_extended_dynamic_state3[] must: either include all of ename:VK_COLOR_COMPONENT_R_BIT, ename:VK_COLOR_COMPONENT_G_BIT, and ename:VK_COLOR_COMPONENT_B_BIT, or none of them +ifdef::VK_ANDROID_external_format_resolve[] +ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09301]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, + slink:VkPipelineRenderingCreateInfo::pname:viewMask must: be `0` +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09302]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, + slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples + must: be `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09303]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, the + pname:blendEnable member of each element of + pname:pColorBlendState->pAttachments must: be ename:VK_FALSE +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09304]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, + slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples + must: be `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09305]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, the pname:blendEnable + member of each element of pname:pColorBlendState->pAttachments must: be + ename:VK_FALSE +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09306]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, + slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:width must: + be `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09307]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, + slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:height + must: be `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09308]] + If the <> + feature is enabled, the pipeline requires + <> and <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, the last + <> must: not statically use a variable with the + code:PrimitiveShadingRateKHR built-in +endif::VK_KHR_fragment_shading_rate[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09309]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, + slink:VkPipelineRenderingCreateInfo::pname:colorAttachmentCount must: be + `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09310]] + If the <> + feature is enabled, the pipeline requires + <> + and <>, pname:renderPass is dlink:VK_NULL_HANDLE, and + slink:VkExternalFormatANDROID::pname:externalFormat is not `0`, the + fragment shader must: not declare the code:DepthReplacing or + code:StencilRefReplacingEXT execution modes +endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] +ifndef::VK_EXT_extended_dynamic_state3[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09311]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is not dlink:VK_NULL_HANDLE, pname:subpass + includes an external format resolve attachment, + slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples + must: be ename:VK_SAMPLE_COUNT_1_BIT + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09312]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is not dlink:VK_NULL_HANDLE, pname:subpass + includes an external format resolve attachment, the pname:blendEnable + member of each element of pname:pColorBlendState->pAttachments must: be + ename:VK_FALSE +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_EXT_extended_dynamic_state3[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09313]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is not dlink:VK_NULL_HANDLE, pname:subpass + includes an external format resolve attachment, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, + slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples + must: be ename:VK_SAMPLE_COUNT_1_BIT + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09314]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is not dlink:VK_NULL_HANDLE, pname:subpass + includes an external format resolve attachment, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_COLOR_BLEND_ENABLE_EXT, the pname:blendEnable + member of each element of pname:pColorBlendState->pAttachments must: be + ename:VK_FALSE +endif::VK_EXT_extended_dynamic_state3[] +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09315]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is not dlink:VK_NULL_HANDLE, pname:subpass + includes an external format resolve attachment, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, + slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:width must: + be `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09316]] + If the <> + feature is enabled, the pipeline requires + <>, pname:renderPass is not dlink:VK_NULL_HANDLE, pname:subpass + includes an external format resolve attachment, and + pname:pDynamicState->pDynamicStates does not include + ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR, + slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:height + must: be `1` + * [[VUID-VkGraphicsPipelineCreateInfo-externalFormatResolve-09317]] + If the <> + feature is enabled, the pipeline requires + <> and <>, pname:renderPass is not dlink:VK_NULL_HANDLE, + and pname:subpass includes an external format resolve attachment, the + last <> must: not statically use a variable with the + code:PrimitiveShadingRateKHR built-in +endif::VK_KHR_fragment_shading_rate[] +endif::VK_ANDROID_external_format_resolve[] **** ifdef::VKSC_VERSION_1_0[] ifdef::hidden[] @@ -4561,6 +4737,13 @@ pass. Valid formats indicate that an attachment can: be used - but it is still valid to set the attachment to `NULL` when beginning rendering. +ifdef::VK_ANDROID_external_format_resolve[] +If the render pass is going to be used with an external format resolve +attachment, a slink:VkExternalFormatANDROID structure must: also be included +in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, defining the +external format of the resolve attachment that will be used. +endif::VK_ANDROID_external_format_resolve[] + include::{generated}/validity/structs/VkPipelineRenderingCreateInfo.adoc[] -- endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] diff --git a/chapters/renderpass.adoc b/chapters/renderpass.adoc index 6fc98fdb2..a6a70e81c 100644 --- a/chapters/renderpass.adoc +++ b/chapters/renderpass.adoc @@ -112,8 +112,12 @@ location in the shader, i.e. if the shader declares an output variable decorated with a code:Location value of *X*, then it uses the attachment provided in pname:pColorAttachments[*X*]. If the pname:imageView member of any element of pname:pColorAttachments is -dlink:VK_NULL_HANDLE, writes to the corresponding location by a fragment are -discarded. +dlink:VK_NULL_HANDLE, +ifdef::VK_ANDROID_external_format_resolve[] +and pname:resolveMode is not +ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, +endif::VK_ANDROID_external_format_resolve[] +writes to the corresponding location by a fragment are discarded. .Valid Usage **** @@ -608,6 +612,32 @@ endif::VK_QCOM_multiview_per_view_render_areas[] Valid attachments specified by this structure must: not be bound to memory locations that are bound to any other valid attachments specified by this structure +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkRenderingInfo-pDepthAttachment-09318]] + pname:pDepthAttachment->resolveMode must: not be + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID + * [[VUID-VkRenderingInfo-pStencilAttachment-09319]] + pname:pStencilAttachment->resolveMode must: not be + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID + * [[VUID-VkRenderingInfo-colorAttachmentCount-09320]] + If pname:colorAttachmentCount is not `1`, the pname:resolveMode member + of any element of pname:pColorAttachments must: not be + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID +ifdef::VK_EXT_fragment_density_map[] + * [[VUID-VkRenderingInfo-resolveMode-09321]] + If the pname:resolveMode of any element of pname:pColorAttachments is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + slink:VkRenderingFragmentDensityMapAttachmentInfoEXT::pname:imageView + must: be dlink:VK_NULL_HANDLE +endif::VK_EXT_fragment_density_map[] +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkRenderingInfo-resolveMode-09322]] + If the pname:resolveMode of any element of pname:pColorAttachments is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + slink:VkRenderingFragmentShadingRateAttachmentInfoKHR::pname:imageView + must: be dlink:VK_NULL_HANDLE +endif::VK_KHR_fragment_shading_rate[] +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/structs/VkRenderingInfo.adoc[] @@ -682,9 +712,10 @@ endif::VK_KHR_dynamic_rendering[] * pname:imageLayout is the layout that pname:imageView will be in during rendering. * pname:resolveMode is a elink:VkResolveModeFlagBits value defining how - multisampled data written to pname:imageView will be resolved. - * pname:resolveImageView is an image view used to write resolved - multisample data at the end of rendering. + data written to pname:imageView will be resolved into + pname:resolveImageView. + * pname:resolveImageView is an image view used to write resolved data at + the end of rendering. * pname:resolveImageLayout is the layout that pname:resolveImageView will be in during rendering. * pname:loadOp is a elink:VkAttachmentLoadOp value defining the @@ -701,11 +732,15 @@ ifdef::VK_VERSION_1_1,VK_KHR_device_group[] for each device endif::VK_VERSION_1_1,VK_KHR_device_group[] specified in slink:VkRenderingInfo. -If pname:imageView is dlink:VK_NULL_HANDLE, other members of this structure -are ignored; writes to this attachment will be discarded, and no -<>, <>, or <> -operations will be performed. +If pname:imageView is dlink:VK_NULL_HANDLE, +ifdef::VK_ANDROID_external_format_resolve[] +and pname:resolveMode is not +ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, +endif::VK_ANDROID_external_format_resolve[] +other members of this structure are ignored; writes to this attachment will +be discarded, and no <>, +<>, or <> operations will be performed. If pname:resolveMode is ename:VK_RESOLVE_MODE_NONE, then pname:resolveImageView is ignored. @@ -713,6 +748,14 @@ If pname:resolveMode is not ename:VK_RESOLVE_MODE_NONE, and pname:resolveImageView is not dlink:VK_NULL_HANDLE, a <> is defined for the attachment subresource. +ifdef::VK_ANDROID_external_format_resolve[] +If pname:resolveMode is +ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, and the +<> limit is ename:VK_TRUE, +values are only undefined: once <> have completed. +endif::VK_ANDROID_external_format_resolve[] [NOTE] .Note @@ -732,6 +775,21 @@ instance that does not specify the ename:VK_RENDERING_RESUMING_BIT_KHR flag. Image contents at the end of a suspended render pass instance remain defined for access by a resuming render pass instance. +ifdef::VK_ANDROID_external_format_resolve[] +If the <> limit is ename:VK_TRUE, +and pname:resolveMode is +ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, values in the +color attachment will be loaded from the resolve attachment at the start of +rendering, and may: also be reloaded any time after a resolve occurs or the +resolve attachment is written to; if this occurs it must: happen-before any +writes to the color attachment are performed which happen-after the resolve +that triggers this. +If any color component in the external format is subsampled, values will be +read from the nearest sample in the image when they are loaded. +endif::VK_ANDROID_external_format_resolve[] + + .Valid Usage **** * [[VUID-VkRenderingAttachmentInfo-imageView-06129]] @@ -854,6 +912,55 @@ ifdef::VK_KHR_swapchain[] not ename:VK_RESOLVE_MODE_NONE, pname:resolveImageLayout must: not be ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR endif::VK_KHR_swapchain[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkRenderingAttachmentInfo-externalFormatResolve-09323]] + If <> is not + enabled, pname:resolveMode must: not be + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID + * [[VUID-VkRenderingAttachmentInfo-resolveMode-09324]] + If pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + pname:resolveImageView must: be a valid image view + * [[VUID-VkRenderingAttachmentInfo-nullColorAttachmentWithExternalFormatResolve-09325]] + If the <> property is + ename:VK_TRUE and pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + pname:resolveImageView must: have been created with an image with a + pname:samples value of ename:VK_SAMPLE_COUNT_1_BIT + * [[VUID-VkRenderingAttachmentInfo-resolveMode-09326]] + If pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + pname:resolveImageView must: have been created with an external format + specified by slink:VkExternalFormatANDROID + * [[VUID-VkRenderingAttachmentInfo-resolveMode-09327]] + If pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + pname:resolveImageView must: have been created with a + pname:subresourceRange.layerCount of `1` + * [[VUID-VkRenderingAttachmentInfo-resolveMode-09328]] + If pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID and + <> is ename:VK_TRUE, + pname:imageView must: be dlink:VK_NULL_HANDLE + * [[VUID-VkRenderingAttachmentInfo-resolveMode-09329]] + If pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID and + <> is ename:VK_FALSE, + pname:imageView must: be a valid slink:VkImageView + * [[VUID-VkRenderingAttachmentInfo-resolveMode-09330]] + If pname:resolveMode is + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID and + <> is ename:VK_FALSE, + pname:imageView must: have a format equal to the value of + slink:VkAndroidHardwareBufferFormatResolvePropertiesANDROID::pname:colorAttachmentFormat + as returned by a call to + flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android + hardware buffer that was used to create pname:resolveImageView +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/structs/VkRenderingAttachmentInfo.adoc[] @@ -1916,6 +2023,8 @@ attachments on multiple uses via ename:VK_ATTACHMENT_LOAD_OP_CLEAR. .Valid Usage **** include::{chapters}/commonvalidity/attachment_description_common.adoc[] + * [[VUID-VkAttachmentDescription-format-06698]] + pname:format must: not be VK_FORMAT_UNDEFINED * [[VUID-VkAttachmentDescription-format-06700]] If pname:format includes a stencil component and pname:stencilLoadOp is ename:VK_ATTACHMENT_LOAD_OP_LOAD, then pname:initialLayout must: not be @@ -3201,6 +3310,16 @@ ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] pname:pAttachments with an index equal to pname:attachment must: not have a pname:format that includes only a stencil component endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] +ifdef::VK_ANDROID_external_format_resolve[] +ifdef::VK_EXT_fragment_density_map[] + * [[VUID-VkRenderPassCreateInfo2-pResolveAttachments-09331]] + If any element of pname:pResolveAttachments of any element of + pname:pSubpasses references an attachment description with a format of + ename:VK_FORMAT_UNDEFINED, + slink:VkRenderPassFragmentDensityMapCreateInfoEXT::pname:fragmentDensityMapAttachment->attachment + must: be ename:VK_ATTACHMENT_UNUSED +endif::VK_EXT_fragment_density_map[] +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/structs/VkRenderPassCreateInfo2.adoc[] @@ -3324,6 +3443,19 @@ ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] +ifndef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkAttachmentDescription2-format-09332]] + pname:format must: not be VK_FORMAT_UNDEFINED +endif::VK_ANDROID_external_format_resolve[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkAttachmentDescription2-externalFormatResolve-09333]] + If <> is not + enabled, pname:format must: not be ename:VK_FORMAT_UNDEFINED + * [[VUID-VkAttachmentDescription2-format-09334]] + If pname:format is ename:VK_FORMAT_UNDEFINED, there must: be a + slink:VkExternalFormatANDROID structure in the pname:pNext chain with a + pname:externalFormat that is not equal to `0` +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/structs/VkAttachmentDescription2.adoc[] @@ -3439,6 +3571,74 @@ identified attachment defines a fragment shading rate attachment for that subpass. endif::VK_KHR_fragment_shading_rate[] +ifdef::VK_ANDROID_external_format_resolve[] +If any element of pname:pResolveAttachments is an image specified with an +slink:VkExternalFormatANDROID, values in the corresponding color attachment +will be resolved to the resolve attachment in the same manner as specified +for <>. + +If the <> limit is ename:VK_TRUE, +values in the color attachment will be loaded from the resolve attachment at +the start of rendering, and may: also be reloaded any time after a resolve +occurs or the resolve attachment is written to; if this occurs it must: +happen-before any writes to the color attachment are performed which +happen-after the resolve that triggers this. +If any color component in the external format is subsampled, values will be +read from the nearest sample in the image when they are loaded. +If the color attachment is also used as an input attachment, the same +behavior applies. + +Setting the color attachment to ename:VK_ATTACHMENT_UNUSED when an external +resolve attachment is used and the +<> limit is ename:VK_TRUE +will not result in color attachment writes to be discarded for that +attachment. + +When <> is ename:VK_TRUE, the +color output from the subpass can still be read via an input attachment; but +the application cannot bind an image view for the color attachment as there +is no such image view bound. +Instead to access the data as an input attachment applications can: use the +resolve attachment in its place - using the resolve attachment image for the +descriptor, and setting the corresponding element of pname:pInputAttachments +to the index of the resolve attachment. + +Loads or input attachment reads from the resolve attachment are performed as +if using a slink:VkSamplerYcbcrConversionCreateInfo with the following +parameters: + +[source,c] +---- +VkSamplerYcbcrConversionCreateInfo createInfo = { + .sType = VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO, + .pNext = NULL, + .format = VK_FORMAT_UNDEFINED, + .ycbcrModel = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, + .ycbcrRange = VK_SAMPLER_YCBCR_RANGE_ITU_FULL, + .components = { + .r = VK_COMPONENT_SWIZZLE_B + .g = VK_COMPONENT_SWIZZLE_R + .b = VK_COMPONENT_SWIZZLE_G + .a = VK_COMPONENT_SWIZZLE_IDENTITY}, + .xChromaOffset = properties.chromaOffsetX, + .yChromaOffset = properties.chromaOffsetY, + .chromaFilter = ename:VK_FILTER_NEAREST, + .forceExplicitReconstruction = ... }; +---- + +where `properties` is equal to +slink:VkPhysicalDeviceExternalFormatResolvePropertiesANDROID returned by the +device and `forceExplicitReconstruction` is effectively ignored as the +ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY model is used. +The applied swizzle is the same effective swizzle that would be applied by +the ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY model, but no +range expansion is applied. +endif::VK_ANDROID_external_format_resolve[] + .Valid Usage **** include::{chapters}/commonvalidity/subpass_description_common.adoc[] @@ -3468,6 +3668,7 @@ endif::VK_HUAWEI_subpass_shading[] attachment, and the attachment is not also used as a color or depth/stencil attachment in the same subpass, then pname:loadOp must: not be ename:VK_ATTACHMENT_LOAD_OP_CLEAR +ifndef::VK_ANDROID_external_format_resolve[] * [[VUID-VkSubpassDescription2-pResolveAttachments-03065]] If pname:pResolveAttachments is not `NULL`, for each resolve attachment that does not have the value ename:VK_ATTACHMENT_UNUSED, the @@ -3477,13 +3678,46 @@ endif::VK_HUAWEI_subpass_shading[] If pname:pResolveAttachments is not `NULL`, for each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED, the corresponding color attachment must: not have a sample count of ename:VK_SAMPLE_COUNT_1_BIT + * [[VUID-VkSubpassDescription2-pResolveAttachments-03068]] + Each element of pname:pResolveAttachments must: have the same + elink:VkFormat as its corresponding color attachment +endif::VK_ANDROID_external_format_resolve[] * [[VUID-VkSubpassDescription2-pResolveAttachments-03067]] If pname:pResolveAttachments is not `NULL`, each resolve attachment that is not ename:VK_ATTACHMENT_UNUSED must: have a sample count of ename:VK_SAMPLE_COUNT_1_BIT - * [[VUID-VkSubpassDescription2-pResolveAttachments-03068]] - Each element of pname:pResolveAttachments must: have the same +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkSubpassDescription2-externalFormatResolve-09335]] + If <> is not + enabled and pname:pResolveAttachments is not `NULL`, for each resolve + attachment that does not have the value ename:VK_ATTACHMENT_UNUSED, the + corresponding color attachment must: not have the value + ename:VK_ATTACHMENT_UNUSED + * [[VUID-VkSubpassDescription2-nullColorAttachmentWithExternalFormatResolve-09336]] + If the <> property is + ename:VK_FALSE and pname:pResolveAttachments is not `NULL`, for each + resolve attachment that has a format of ename:VK_FORMAT_UNDEFINED, the + corresponding color attachment must: not have the value + ename:VK_ATTACHMENT_UNUSED + * [[VUID-VkSubpassDescription2-nullColorAttachmentWithExternalFormatResolve-09337]] + If the <> property is + ename:VK_TRUE and pname:pResolveAttachments is not `NULL`, for each + resolve attachment that has a format of ename:VK_FORMAT_UNDEFINED, the + corresponding color attachment must: have the value + ename:VK_ATTACHMENT_UNUSED + * [[VUID-VkSubpassDescription2-externalFormatResolve-09338]] + If <> is not + enabled and pname:pResolveAttachments is not `NULL`, for each resolve + attachment that is not ename:VK_ATTACHMENT_UNUSED, the corresponding + color attachment must: not have a sample count of + ename:VK_SAMPLE_COUNT_1_BIT + * [[VUID-VkSubpassDescription2-externalFormatResolve-09339]] + If <> is not + enabled, each element of pname:pResolveAttachments must: have the same elink:VkFormat as its corresponding color attachment +endif::VK_ANDROID_external_format_resolve[] ifdef::VK_EXT_multisampled_render_to_single_sampled[] * [[VUID-VkSubpassDescription2-multisampledRenderToSingleSampled-06869]] If none of the `apiext:VK_AMD_mixed_attachment_samples` extension, the @@ -3493,22 +3727,58 @@ ifdef::VK_EXT_multisampled_render_to_single_sampled[] attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have the same sample count endif::VK_EXT_multisampled_render_to_single_sampled[] +ifndef::VK_ANDROID_external_format_resolve[] * [[VUID-VkSubpassDescription2-pInputAttachments-02897]] All attachments in pname:pInputAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain at least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT +endif::VK_ANDROID_external_format_resolve[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkSubpassDescription2-externalFormatResolve-09340]] + If the <> + feature is not enabled, all attachments in pname:pInputAttachments that + are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose + <> contain at + least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT + * [[VUID-VkSubpassDescription2-nullColorAttachmentWithExternalFormatResolve-09341]] + If the <> property is + ename:VK_FALSE, all attachments in pname:pInputAttachments that are not + ename:VK_ATTACHMENT_UNUSED must: have image formats whose + <> contain at + least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT + * [[VUID-VkSubpassDescription2-pInputAttachments-09342]] + All attachments in pname:pInputAttachments that are not + ename:VK_ATTACHMENT_UNUSED and do not have a non-zero value of + slink:VkExternalFormatANDROID::pname:externalFormat must: have image + formats whose <> + contain at least ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT +endif::VK_ANDROID_external_format_resolve[] * [[VUID-VkSubpassDescription2-pColorAttachments-02898]] All attachments in pname:pColorAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT +ifndef::VK_ANDROID_external_format_resolve[] * [[VUID-VkSubpassDescription2-pResolveAttachments-02899]] All attachments in pname:pResolveAttachments that are not ename:VK_ATTACHMENT_UNUSED must: have image formats whose <> contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT +endif::VK_ANDROID_external_format_resolve[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkSubpassDescription2-pResolveAttachments-09343]] + All attachments in pname:pResolveAttachments that are not + ename:VK_ATTACHMENT_UNUSED and do not have an image format of + ename:VK_FORMAT_UNDEFINED must: have image formats whose + <> contain + ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT +endif::VK_ANDROID_external_format_resolve[] * [[VUID-VkSubpassDescription2-pDepthStencilAttachment-02900]] If pname:pDepthStencilAttachment is not `NULL` and the attachment is not ename:VK_ATTACHMENT_UNUSED then it must: have an image format whose @@ -3627,6 +3897,44 @@ ifdef::VK_VERSION_1_1,VK_KHR_multiview[] The index of the most significant bit in pname:viewMask must: be less than <> endif::VK_VERSION_1_1,VK_KHR_multiview[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkSubpassDescription2-externalFormatResolve-09344]] + If <> is + enabled, pname:pResolveAttachments is not `NULL`, and + pname:colorAttachmentCount is not `1`, any element of + pname:pResolveAttachments that is not `VK_ATTACHMENT_UNUSED`, must: not + have a format of ename:VK_FORMAT_UNDEFINED + * [[VUID-VkSubpassDescription2-externalFormatResolve-09345]] + If <> is + enabled, pname:pResolveAttachments is not `NULL`, any element of + pname:pResolveAttachments is not ename:VK_ATTACHMENT_UNUSED and has a + format of ename:VK_FORMAT_UNDEFINED, and the corresponding element of + pname:pColorAttachments is not ename:VK_ATTACHMENT_UNUSED, the color + attachment must: have a pname:samples value of `1` + * [[VUID-VkSubpassDescription2-externalFormatResolve-09346]] + If <> is + enabled, pname:pResolveAttachments is not `NULL`, and any element of + pname:pResolveAttachments is not ename:VK_ATTACHMENT_UNUSED and has a + format of ename:VK_FORMAT_UNDEFINED, pname:viewMask must: be `0` +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkSubpassDescription2-externalFormatResolve-09347]] + If <> is + enabled, pname:pResolveAttachments is not `NULL`, and any element of + pname:pResolveAttachments is not ename:VK_ATTACHMENT_UNUSED and has a + format of ename:VK_FORMAT_UNDEFINED, + slink:VkFragmentShadingRateAttachmentInfoKHR::pname:pFragmentShadingRateAttachment + must: either be `NULL` or a slink:VkAttachmentReference2 structure with + a pname:attachment value of ename:VK_ATTACHMENT_UNUSED +endif::VK_KHR_fragment_shading_rate[] + * [[VUID-VkSubpassDescription2-externalFormatResolve-09348]] + If <> is + enabled, pname:pResolveAttachments is not `NULL`, and any element of + pname:pResolveAttachments is not ename:VK_ATTACHMENT_UNUSED and has a + format of ename:VK_FORMAT_UNDEFINED, elements of pname:pInputAttachments + referencing either a color attachment or resolve attachment used in this + subpass must: not include `VK_IMAGE_ASPECT_PLANE__{ibit}__BIT_EXT` for + any index _i_ in its pname:aspectMask +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/structs/VkSubpassDescription2.adoc[] @@ -4738,6 +5046,51 @@ ifdef::VK_EXT_multisampled_render_to_single_sampled[] count specified in slink:VkMultisampledRenderToSingleSampledInfoEXT::pname:rasterizationSamples endif::VK_EXT_multisampled_render_to_single_sampled[] +ifdef::VK_ANDROID_external_format_resolve[] +ifndef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] + * [[VUID-VkFramebufferCreateInfo-nullColorAttachmentWithExternalFormatResolve-09349]] + If the <> is ename:VK_FALSE, + the format of the color attachment for each subpass in pname:renderPass + that includes an external format image as a resolve attachment must: + have a format equal to the value of + slink:VkAndroidHardwareBufferFormatResolvePropertiesANDROID::pname:colorAttachmentFormat + as returned by a call to + flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android + hardware buffer that was used to create the image view use as its + resolve attachment + * [[VUID-VkFramebufferCreateInfo-pAttachments-09350]] + Each element of pname:pAttachments with a format of + ename:VK_FORMAT_UNDEFINED must: have been created with a + slink:VkExternalFormatANDROID::pname:externalFormat value identical to + that provided in the slink:VkExternalFormatANDROID::pname:externalFormat + specified by the corresponding slink:VkAttachmentDescription2 in + pname:renderPass +endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] +ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] + * [[VUID-VkFramebufferCreateInfo-flags-09351]] + If pname:flags does not include + ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT and the + <> is ename:VK_FALSE, + the format of the color attachment for each subpass in pname:renderPass + that includes an external format image as a resolve attachment must: + have a format equal to the value of + slink:VkAndroidHardwareBufferFormatResolvePropertiesANDROID::pname:colorAttachmentFormat + as returned by a call to + flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android + hardware buffer that was used to create the image view used as its + resolve attachment + * [[VUID-VkFramebufferCreateInfo-flags-09352]] + If pname:flags does not include + ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of + pname:pAttachments with a format of ename:VK_FORMAT_UNDEFINED must: have + been created with a slink:VkExternalFormatANDROID::pname:externalFormat + value identical to that provided in the + slink:VkExternalFormatANDROID::pname:externalFormat specified by the + corresponding slink:VkAttachmentDescription2 in pname:renderPass +endif::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] +endif::VK_ANDROID_external_format_resolve[] **** include::{generated}/validity/structs/VkFramebufferCreateInfo.adoc[] @@ -5142,9 +5495,43 @@ endif::VK_KHR_depth_stencil_resolve[] operation is the minimum of the sample values. * ename:VK_RESOLVE_MODE_MAX_BIT indicates that result of the resolve operation is the maximum of the sample values. - -When no resolve mode is specified, ename:VK_RESOLVE_MODE_AVERAGE_BIT is -used. +ifdef::VK_ANDROID_external_format_resolve[] + * ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID indicates that + rather than a multisample resolve, a single sampled color attachment + will be downsampled into a {YCbCr} format image specified by an external + Android format. + Unlike other resolve modes, implementations can resolve multiple times + during rendering, or even bypass writing to the color attachment + altogether, as long as the final value is resolved to the resolve + attachment. + Values in the [eq]#G#, [eq]#B#, and [eq]#R# channels of the color + attachment will be written to the [eq]#Y#, [eq]#C~B~#, and [eq]#C~R~# + channels of the external format image, respectively. + Chroma values are calculated as if sampling with a linear filter from + the color attachment at full rate, at the location the chroma values sit + according to + slink:VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::pname:chromaOffsetX, + slink:VkPhysicalDeviceExternalFormatResolvePropertiesANDROID::pname:chromaOffsetY, + and the chroma sample rate of the resolved image. +endif::VK_ANDROID_external_format_resolve[] + +If no resolve mode is otherwise specified, ename:VK_RESOLVE_MODE_AVERAGE_BIT +is used. + +ifdef::VK_ANDROID_external_format_resolve[] +[NOTE] +.Note +==== +No range compression or {YCbCr} model conversion is performed by +ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID; applications have +to do these conversions themselves. +Value outputs are expected to match those that would be read through a +<>. +The color space that the values should be in is defined by the platform and +is not exposed via Vulkan. +==== +endif::VK_ANDROID_external_format_resolve[] -- [open,refpage='VkResolveModeFlags',desc='Bitmask of VkResolveModeFlagBits',type='flags',alias='VkResolveModeFlagsKHR'] @@ -5809,6 +6196,33 @@ ifdef::VK_VERSION_1_2,VK_KHR_imageless_framebuffer[] of an image created with a value of slink:VkImageViewCreateInfo::pname:format equal to the corresponding value of slink:VkAttachmentDescription::pname:format in pname:renderPass +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkRenderPassBeginInfo-framebuffer-09353]] + If pname:framebuffer was created with a + slink:VkFramebufferCreateInfo::pname:flags value that included + ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, and the + <> is ename:VK_FALSE, + the format of the color attachment for each subpass that includes an + external format image as a resolve attachment must: have a format equal + to the value of + slink:VkAndroidHardwareBufferFormatResolvePropertiesANDROID::pname:colorAttachmentFormat + as returned by a call to + flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android + hardware buffer that was used to create the image view use as its + resolve attachment + * [[VUID-VkRenderPassBeginInfo-framebuffer-09354]] + If pname:framebuffer was created with a + slink:VkFramebufferCreateInfo::pname:flags value that included + ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the + pname:pAttachments member of a slink:VkRenderPassAttachmentBeginInfo + structure included in the pname:pNext chain must: be a slink:VkImageView + of an image created with a value of + slink:VkExternalFormatANDROID::pname:externalFormat equal to + slink:VkExternalFormatANDROID::pname:externalFormat in the pname:pNext + chain of the corresponding slink:VkAttachmentDescription2 structure used + to create pname:renderPass +endif::VK_ANDROID_external_format_resolve[] * [[VUID-VkRenderPassBeginInfo-framebuffer-09047]] If pname:framebuffer was created with a slink:VkFramebufferCreateInfo::pname:flags value that included diff --git a/chapters/resources.adoc b/chapters/resources.adoc index eb10e6859..990ecd595 100644 --- a/chapters/resources.adoc +++ b/chapters/resources.adoc @@ -2522,10 +2522,6 @@ endif::VK_NV_external_memory[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] [open,refpage='VkExternalFormatANDROID',desc='Structure containing an Android hardware buffer external format',type='structs'] -- -To create an image with an -<>, add a sname:VkExternalFormatANDROID structure in the pname:pNext -chain of slink:VkImageCreateInfo. sname:VkExternalFormatANDROID is defined as: include::{generated}/api/structs/VkExternalFormatANDROID.adoc[] @@ -2536,9 +2532,14 @@ include::{generated}/api/structs/VkExternalFormatANDROID.adoc[] * pname:externalFormat is an implementation-defined identifier for the external format -If pname:externalFormat is zero, the effect is as if the -sname:VkExternalFormatANDROID structure was not present. -Otherwise, the pname:image will have the specified external format. +When included in the pname:pNext chain of another structure, it indicates +<> beyond what is provided by ename:VkFormat values for an +Android hardware buffer. +If pname:externalFormat is zero, it indicates that no external format is +used, and implementations should rely only on other format information. +If this structure is not present, it is equivalent to setting +pname:externalFormat to zero. .Valid Usage **** @@ -4678,14 +4679,42 @@ endif::VK_NV_linear_color_attachment[] <> must: contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT ifndef::VK_NV_linear_color_attachment[] +ifndef::VK_ANDROID_external_format_resolve[] * [[VUID-VkImageViewCreateInfo-usage-02652]] If pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view's <> must: contain at least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT +endif::VK_ANDROID_external_format_resolve[] +ifdef::VK_ANDROID_external_format_resolve[] + * [[VUID-VkImageViewCreateInfo-externalFormatResolve-09355]] + If the <> + feature is not enabled and pname:usage contains + ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view's + <> must: contain + at least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT + * [[VUID-VkImageViewCreateInfo-nullColorAttachmentWithExternalFormatResolve-09356]] + If the <> property is + ename:VK_FALSE and pname:usage contains + ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view's + <> must: contain + at least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT + * [[VUID-VkImageViewCreateInfo-image-09357]] + If pname:image was created with a + slink:VkExternalFormatANDROID::pname:externalFormat value of 0 and + pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the + image view's <> + must: contain at least one of + ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT +endif::VK_ANDROID_external_format_resolve[] endif::VK_NV_linear_color_attachment[] ifdef::VK_NV_linear_color_attachment[] +ifndef::VK_ANDROID_external_format_resolve[] * [[VUID-VkImageViewCreateInfo-usage-08932]] If pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view's <> + feature is not enabled and pname:usage contains + ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view's + <> must: contain + at least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, or + ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV + * [[VUID-VkImageViewCreateInfo-nullColorAttachmentWithExternalFormatResolve-09359]] + If the <> property is + ename:VK_FALSE and pname:usage contains + ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the image view's + <> must: contain + at least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, or + ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV + * [[VUID-VkImageViewCreateInfo-image-09360]] + If pname:image was created with a + slink:VkExternalFormatANDROID::pname:externalFormat value of 0 and + pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then the + image view's <> + must: contain at least one of + ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, or + ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV +endif::VK_ANDROID_external_format_resolve[] endif::VK_NV_linear_color_attachment[] * [[VUID-VkImageViewCreateInfo-subresourceRange-01478]] pname:subresourceRange.baseMipLevel must: be less than the diff --git a/proposals/VK_ANDROID_external_format_resolve.adoc b/proposals/VK_ANDROID_external_format_resolve.adoc new file mode 100644 index 000000000..52328d140 --- /dev/null +++ b/proposals/VK_ANDROID_external_format_resolve.adoc @@ -0,0 +1,361 @@ +// Copyright 2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_ANDROID_external_format_resolve +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This extension enables rendering to Android Hardware Buffers with external formats which cannot be directly represented as renderable in Vulkan, including YC~B~C~R~ formats. + + +== Problem Statement + +Applications can render to unknown formats on Android today in OpenGL ES using GL_EXT_yuv_target, which enables direct rendering to images with an unknown external YC~B~C~R~ format. +In order to support these applications running on top of Vulkan (either via porting or through ANGLE), similar functionality is required for Vulkan. + +One issue that needs to be overcome however, is that GL_EXT_yuv_target is very opaque, and in OpenGL ES this allows implementations to hide a lot of gnarly details. +For Vulkan, it is much harder to hide those details, so an alternative which meets the needs of all potential implementations is required, including those that have no direct support for rendering to YC~B~C~R~ images. + + +== Solution Space + +Any solution needs to meet the following requirements: + + * It must provide functionality on par with that provided by GL_EXT_yuv_target + * It must be possible to emulate GL_EXT_yuv_target in ANGLE via this extension + * It must be cleanly implementable on all implementations + * It must perform well on implementations that support direct YC~B~C~R~ rendering + * It must be relatively straightforward for applications to use + * It must support render pass objects and dynamic rendering + +The naive solution would be to directly allow rendering to YC~B~C~R~ images in Vulkan; this would meet most requirements but likely fail at being cleanly implementable, or a lot of awkward detail would need to be exposed to developers. + +Another idea that has been suggested would be to enable something via a similar mechanism used for resolving multisampled images at the end of a render pass; resolve operations. +Care is needed to ensure implementations can still use direct rendering, but it should be able to meet all of the above requirements. + + +== Proposal + +This extension extends both render pass objects and dynamic rendering functionality. + + +=== Dynamic Rendering + +When using dynamic rendering, a new resolve mode is added to specify that the resolve attachment will have an external format: + +[source,c] +---- + VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID; +---- + +When this resolve mode is specified, the `resolveImageView` member of link:{refpage}VkRenderingAttachmentInfo.html[VkRenderingAttachmentInfo] used as a color attachment must be set to a `VkImageView` created with an image with a non-zero external format. +If chroma planes of the external format are subsampled, the implementation will reduce the relevant planes by either averaging the corresponding values in the color attachment, or by simply selecting one of the values as representative. +Implementations may resolve a color attachment to an external format resolve attachment at any time, or bypass writing to a color attachment altogether. + +With the resolve mode set to `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`, the following additional constraints also apply: + + * If `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE`, `imageView` must be `VK_NULL_HANDLE`. + ** Values in the color attachment during rendering are loaded from the external format attachment, resampling to the fragment rate as necessary. + * If `imageView` is not `NULL`, it must be a single sampled image with a layer count of `1`. + * The `layerCount` and `colorAttachmentCount` members of link:{refpage}VkRenderingInfo.html[VkRenderingInfo] must be 1. + * The `viewMask` member of link:{refpage}VkRenderingInfo.html[VkRenderingInfo] must be 0. + * There must not be a fragment density map image + * There must not be a fragment shading rate image + * The fragment shading rate must be 1x1 + +Implementations may need to know that an external format YC~B~C~R~ format is being used when creating a pipeline, so when dynamic rendering is used, link:{refpage}VkExternalFormatANDROID.html[VkExternalFormatANDROID] can be chained to `VkGraphicsPipelineCreateInfo`, indicating the format of the resolve image. +When rendering, the format of the resolve image specified here and the actual image view used for that color resolve attachment must be the same. +Graphics pipelines that include a link:{refpage}VkExternalFormatANDROID.html[VkExternalFormatANDROID] structure with a non-zero value must only write to a single color attachment, must not export depth or stencil from the fragment shader, and must disable blending. + +==== Inheritance Info + +When dynamic rendering is used with secondary command buffer inheritance, the external format must: be made known to the secondary command buffers by including link:{refpage}VkExternalFormatANDROID.html[VkExternalFormatANDROID] in the `pNext` chain of link:{refpage}VkCommandBufferInheritanceInfo.html[VkCommandBufferInheritanceInfo], and the external format must match that in the render pass instance. + +=== Render Pass Objects + +For render pass objects, color resolve attachments can similarly be repurposed for external YC~B~C~R~ format resolves by setting a color resolve attachment in a subpass to an attachment with an external format. +These can only be used with link:{refpage}VkSubpassDescription2.html[VkSubpassDescription2], and similar restrictions apply to this as they do to dynamic rendering: + + * The resolve attachment must be an attachment that has a format of `VK_FORMAT_UNDEFINED` and includes a link:{refpage}VkExternalFormatANDROID.html[VkExternalFormatANDROID] structure in its `pNext` chain + ** This format must match that for the image view bound via the framebuffer + * If `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE`, the `attachment` member of the corresponding color attachment must be `VK_ATTACHMENT_UNUSED`. + * If the color attachment is not `VK_ATTACHMENT_UNUSED`, it must be a single sampled attachment. + * `viewMask` must be 0. + * `colorAttachmentCount` must be 1. + +Color attachment values written during rendering are resolved in the same manner as specified for `VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID`. + + +=== Input Attachments + +If the `nullColorAttachmentWithExternalFormatResolve` property is `VK_FALSE`, applications can bind the color attachment as they normally would with any other color attachment, with value reads working as expected. +Using an external format image as an input attachment is only valid when the feature bits queried via link:{refpage}vkGetAndroidHardwareBufferPropertiesANDROID.html[vkGetAndroidHardwareBufferPropertiesANDROID] advertise this functionality. + +However, if the `nullColorAttachmentWithExternalFormatResolve` property is `VK_TRUE`, applications cannot do that as there is no attachment to use. +Instead, the resolve attachment itself should be bound as the input attachment (both the attachment reference and the descriptor). +When using a resolve attachment in this specific configuration, it can be synchronized as if it were actually the color attachment, allowing for subpass self-dependencies. +If the implementation supports this property, an external format image can be used as an input attachment without the typically required feature bits advertised by link:{refpage}vkGetAndroidHardwareBufferPropertiesANDROID.html[vkGetAndroidHardwareBufferPropertiesANDROID]. + +If an external format resolve image is read as an input attachment and has subsampled chroma planes, these are resampled per above to provide values at the expected rate. +Their values are not converted via color space transforms - as with resolves the application must transform these themselves. + + +=== Format Resolve Properties + +Not all external formats will be usable for an external format resolve; the following property structure indicates whether an external format is supported for resolves or not: + +[source,c] +---- +typedef struct VkAndroidHardwareBufferFormatResolvePropertiesANDROID { + VkStructureType sType; + void* pNext; + VkFormat colorAttachmentFormat; +} VkAndroidHardwareBufferFormatResolvePropertiesANDROID; +---- + +External formats that can be resolved to will indicate a format that color attachments should use when rendering. +If it is not resolvable, it will be set to `VK_FORMAT_UNDEFINED`. + +Any Android hardware buffer that is renderable must be either renderable via existing format paths or via this extension. + +[NOTE] +==== +For implementations that expose `nullColorAttachmentWithExternalFormatResolve`, the format should not be used to create images, but does still serve two additional purposes. + +Firstly, the numeric type of the format indicates the type that is needed in the shader (e.g. an `UNORM` format indicates a floating point color output). + +In addition to that, it indicates the precision of data while the color output remains in the color buffer; as such it should always have a per-channel precision equal to or greater than that of the hardware buffer format. +Implementations that directly render to the resolve attachment and never store data in an intermediate color buffer can set this to a type large enough that it guarantees it will not interfere with the precision of the final value. +As there is no expectation of data remaining in the color buffer, applications should expect a minimum precision according to the lowest precision of each channel between the color buffer format and the format of the Android hardware buffer. +==== + + +=== Device Features + +The following single feature is exposes all the functionality in this extension: + +[source,c] +---- +typedef struct VkPhysicalDeviceExternalFormatResolveFeaturesANDROID { + VkStructureType sType; + void* pNext; + VkBool32 externalFormatResolve; +} VkPhysicalDeviceExternalFormatResolveFeaturesANDROID; +---- + +`externalFormatResolve` must be supported if this extension is advertised. + + +=== Device Properties + +The following properties are exposed: + +[source,c] +---- +typedef struct VkPhysicalDeviceExternalFormatResolvePropertiesANDROID { + VkStructureType sType; + void* pNext; + VkBool32 nullColorAttachmentWithExternalFormatResolve; + VkChromaLocation externalFormatResolveChromaOffsetX; + VkChromaLocation externalFormatResolveChromaOffsetY; +} VkPhysicalDeviceExternalFormatResolvePropertiesANDROID; +---- + +* If `nullColorAttachmentWithExternalFormatResolve` is `VK_TRUE`, applications must omit the color attachment by setting `VkRenderingAttachmentInfo::imageView` to `NULL` for dynamic rendering, or using `VK_ATTACHMENT_UNUSED` for the color attachment when creating a render pass object. +* `externalFormatResolveChromaOffsetX` indicates the chroma offset in the X axis that an implementation uses when resolving to or loading from resolve attachments with an external format. +* `externalFormatResolveChromaOffsetY` indicates the chroma offset in the Y axis that an implementation uses when resolving to or loading from resolve attachments with an external format. + +NOTE: The chroma offsets are consistent between reads and writes inside the Vulkan implementation, but may be inconsistent with other systems writing that data; this may lead to slight inaccuracies when reading from input attachments without writing to them first. If this accuracy is a concern, YC~B~C~R~ sampling can be used for the initial read, where the offset is configurable, rather than reading as an input attachment. + + +== Examples + +=== Creation of a Render Pass Object + +[source,c] +---- +// Create two attachments, a resolve and color attachment +VkAttachmentDescription2 attachments[2] = { + { + VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, + &externalFormat, + 0, + VK_FORMAT_UNDEFINED, + 1, + VK_LOAD_OP_LOAD, + VK_STORE_OP_STORE, + VK_LOAD_OP_LOAD, + VK_STORE_OP_STORE, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL + }, + { + VK_STRUCTURE_TYPE_ATTACHMENT_DESCRIPTION_2, + NULL, + 0, + resolveFormatProperties.colorAttachmentFormat, + 1, + VK_LOAD_OP_LOAD, + VK_STORE_OP_STORE, + VK_LOAD_OP_LOAD, + VK_STORE_OP_STORE, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL + } +}; + +// Resolve attachment always specified +VkAttachmentReference2 resolveAttachment = { + VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, + NULL, + 0, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, + 0}; + +// Color attachment must be UNUSED if nullColorAttachmentWithExternalFormatResolve is VK_TRUE +VkAttachmentReference2 colorAttachment = { + VK_STRUCTURE_TYPE_ATTACHMENT_REFERENCE_2, + NULL, + nullColorAttachmentWithExternalFormatResolve ? VK_ATTACHMENT_UNUSED : 1, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, + 0}; + +// No changes to subpass creation +VkSubpassDescription2 subpass = { + VK_STRUCTURE_TYPE_SUBPASS_DESCRIPTION_2, + NULL, + 0, + VK_PIPELINE_BIND_POINT_GRAPHICS, + 0, + 0, + NULL, + 1, + &colorAttachment, + &resolveAttachment, + NULL, + 0, + NULL}; + +// Only add the color attachment information if nullColorAttachmentWithExternalFormatResolve is VK_FALSE +VkRenderPassCreateInfo2 createInfo = { + VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO_2, + NULL, + 0, + nullColorAttachmentWithExternalFormatResolve ? 1 : 2, + &attachments, + 1, + &subpass, + 0, + 0, + NULL}; + +VkRenderPass renderPass; +vkCreateRenderPass2(device, &createInfo, NULL, &renderPass); +---- + + +=== Dynamic Rendering + +[source,c] +---- +// Do not attach a color image view if nullColorAttachmentWithExternalFormatResolve is VK_TRUE +// Other setup is identical either way +VkRenderingAttachmentInfo colorAttachment = { + VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO, + NULL, + nullColorAttachmentWithExternalFormatResolve ? VK_NULL_HANDLE : colorImageView; + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, + VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, + externalResolveImageView, + VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, + VK_LOAD_OP_LOAD, + VK_STORE_OP_STORE, + clearValue}; + +VkRect2D renderArea = { ... }; +VkRenderingInfo renderingInfo = { + VK_STRUCTURE_TYPE_RENDERING_INFO, + NULL, + 0, + renderArea, + 1, + 0, + 1, + &colorAttachment, + NULL, + NULL}; + +vkCmdBeginRendering(commandBuffer, renderingInfo); +---- + + +== Issues + + +=== GL_EXT_yuv_target had a shader extension, but this does not, why? + +The GLSL portion of that extension consisted of two parts: + +. A designation that a color output would be used as yuv +. YUV conversion helper functions + +For the helper functions, no implementation can accelerate these operations in shader code; so they have been omitted in favor of high level language translation (e.g. glslang) providing these functions. + +The yuv output marker was necessary in GLSL because it substantially affected compilation, and this is the only way OpenGL ES had to make such information known to the compiler. +In Vulkan however there is a pipeline object we can use instead; the pipeline contains enough information to make this information available at the API level. +This does mean this extension will not work with VK_EXT_shader_object or any similar extension without further work. +All of this is a deliberate choice due to time constraints. + + +=== Who is responsible for conversions to and from YC~B~C~R~ color spaces? + +The application is responsible for these conversions; the implementation is only responsible for resampling the values between different sampling rates on the chroma planes. +Output value expectations match those of GL_EXT_yuv_target. + + +=== How do attachment clears work? + +Attachment clears operate as if they were writes to the color attachment, which means that as with color attachment writes, values must be in the correct color space for the external format and in the expected channel order. + + +=== What is the expected channel order for YUV output? + +In GL_EXT_yuv_target, the expected mapping was for the Y, C~B~, and C~R~ channels to map to the R, G, and B channels of the output, respectively. +However, Vulkan established a convention that C~B~ and C~R~ should map to B and R channels, matching their chroma designation. + +This extension matches the Vulkan convention, requiring the Y, C~B~, and C~R~ channels to map to the G, B, and R channels in the output, respectively. + +[NOTE] +.Note +==== +The channel order and color space of an imported external format are opaque to the Vulkan implementation. +Therefore, all external resolve and input attachment accesses are treated as if they were color images in the ycbcr identity model, without range expansion. +For example, images with four components are treated as R = Cr, G = Y, and B = Cb. This means that effectively: + + * Input attachment reads present color components as vec4(R, G, B, A) to the shader and yuv components as (V, Y, U, A) + * External format resolve takes color components from the shader out variable as vec4(R, G, B, A) and yuv components as (V, Y, U, A) + * Clear color given to begin rendering/render pass are taken as (R, G, B, A) for color components and (V, Y, U, A) for yuv components + +Implementations must not expose an external formats representing a depth or stencil format. +Applications must import depth images with link:{refpage}VkFormat.html[VkFormat] in order to render to them. +Images without depth, color, or yuv components are beyond the scope of Vulkan interface and are defined by the format for which effective color components it should be used as, such as for the RAW10 format. +==== + + +=== How is resampling performed for null attachments when `nullColorAttachmentWithExternalFormatResolve` is supported? + +The nearest sample is read from subsampled planes to populate the values in the fragment shader. + + +=== Is there a way we could better unify the two options for the `nullColorAttachmentWithExternalFormatResolve` path? + +This could likely be done, but has been skipped due to time constraints. +A future extension should be able to do a better job of unifying these paths. + + +== Future Work + +This extension is fairly limited, as it is meant to match GL_EXT_yuv_target and do no more due to time constraints. +Further extensions could be introduced to expand the functionality to include things like multisampling, storing both color and YC~B~C~R~ images, tighter controls on precision, and color space conversions. diff --git a/scripts/genvk.py b/scripts/genvk.py index 71e6baf79..676c78c4f 100755 --- a/scripts/genvk.py +++ b/scripts/genvk.py @@ -428,7 +428,8 @@ def makeGenOpts(args): platforms = [ [ 'vulkan_android.h', [ 'VK_KHR_android_surface', - 'VK_ANDROID_external_memory_android_hardware_buffer' + 'VK_ANDROID_external_memory_android_hardware_buffer', + 'VK_ANDROID_external_format_resolve' ], commonSuppressExtensions + [ 'VK_KHR_format_feature_flags2', ] ], diff --git a/vkspec.adoc b/vkspec.adoc index 49503524d..fa017a72b 100644 --- a/vkspec.adoc +++ b/vkspec.adoc @@ -194,6 +194,10 @@ ifdef::VK_AMDX_shader_enqueue[] include::{chapters}/executiongraphs.adoc[] endif::VK_AMDX_shader_enqueue[] +ifdef::VK_NV_low_latency2[] +include::{chapters}/VK_NV_low_latency2/low_latency2.adoc[] +endif::VK_NV_low_latency2[] + // Sort of an appendix include::{chapters}/extensions.adoc[] diff --git a/xml/vk.xml b/xml/vk.xml index fca891b4e..ad17319fc 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -175,7 +175,7 @@ branch of the member gitlab server. #define VKSC_API_VERSION_1_0 VK_MAKE_API_VERSION(VKSC_API_VARIANT, 1, 0, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 265 +#define VK_HEADER_VERSION 266 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION) // Version of this file @@ -865,6 +865,8 @@ typedef void* MTLSharedEvent_id; + + Enumerated types in the header, but not used by the API @@ -4201,7 +4203,7 @@ typedef void* MTLSharedEvent_id; const void* pNext VkBool32 conditionalRenderingEnableWhether this secondary command buffer may be executed during an active conditional rendering - + VkStructureType sType void* pNext uint64_t externalFormat @@ -8673,6 +8675,86 @@ typedef void* MTLSharedEvent_id; void* pNext VkLayeredDriverUnderlyingApiMSFT underlyingAPI + + VkStructureType sType + void* pNext + VkBool32 externalFormatResolve + + + VkStructureType sType + void* pNext + VkBool32 nullColorAttachmentWithExternalFormatResolve + VkChromaLocation externalFormatResolveChromaOffsetX + VkChromaLocation externalFormatResolveChromaOffsetY + + + VkStructureType sType + void* pNext + VkFormat colorAttachmentFormat + + + VkStructureType sType + const void* pNext + VkBool32 lowLatencyMode + VkBool32 lowLatencyBoost + uint32_t minimumIntervalUs + + + VkStructureType sType + const void* pNext + VkSemaphore signalSemaphore + uint64_t value + + + VkStructureType sType + const void* pNext + uint64_t presentID + VkLatencyMarkerNV marker + + + VkStructureType sType + const void* pNext + VkLatencyTimingsFrameReportNV* pTimings + + + VkStructureType sType + const void* pNext + uint64_t presentID + uint64_t inputSampleTimeUs + uint64_t simStartTimeUs + uint64_t simEndTimeUs + uint64_t renderSubmitStartTimeUs + uint64_t renderSubmitEndTimeUs + uint64_t presentStartTimeUs + uint64_t presentEndTimeUs + uint64_t driverStartTimeUs + uint64_t driverEndTimeUs + uint64_t osRenderQueueStartTimeUs + uint64_t osRenderQueueEndTimeUs + uint64_t gpuRenderStartTimeUs + uint64_t gpuRenderEndTimeUs + + + VkStructureType sType + const void* pNext + VkOutOfBandQueueTypeNV queueType + + + VkStructureType sType + const void* pNext + uint64_t presentID + + + VkStructureType sType + const void* pNext + VkBool32 latencyModeEnable + + + VkStructureType sType + const void* pNext + uint32_t presentModeCount + VkPresentModeKHR* pPresentModes + @@ -10770,6 +10852,24 @@ typedef void* MTLSharedEvent_id; + + + + + + + + + + + + + + + + + + @@ -14783,6 +14883,36 @@ typedef void* MTLSharedEvent_id; VkDeviceAddress scratch VkDeviceAddress countInfo + + VkResult vkSetLatencySleepModeNV + VkDevice device + VkSwapchainKHR swapchain + VkLatencySleepModeInfoNV* pSleepModeInfo + + + VkResult vkLatencySleepNV + VkDevice device + VkSwapchainKHR swapchain + VkLatencySleepInfoNV* pSleepInfo + + + void vkSetLatencyMarkerNV + VkDevice device + VkSwapchainKHR swapchain + VkSetLatencyMarkerInfoNV* pLatencyMarkerInfo + + + void vkGetLatencyTimingsNV + VkDevice device + VkSwapchainKHR swapchain + uint32_t* pTimingCount + VkGetLatencyMarkerInfoNV* pLatencyMarkerInfo + + + void vkQueueNotifyOutOfBandNV + VkQueue queue + VkOutOfBandQueueTypeInfoNV pQueueTypeInfo + @@ -22492,11 +22622,19 @@ typedef void* MTLSharedEvent_id; - + - - - + + + + + + + + + + + @@ -23016,10 +23154,35 @@ typedef void* MTLSharedEvent_id; - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + +