2016-02-16 09:53:44 +00:00
|
|
|
vkGetImageSubresourceLayout(3)
|
|
|
|
===============================
|
|
|
|
|
|
|
|
Name
|
|
|
|
----
|
|
|
|
vkGetImageSubresourceLayout - Retrieve information about an image subresource.
|
|
|
|
|
|
|
|
C Specification
|
|
|
|
---------------
|
|
|
|
|
|
|
|
include::../protos/vkGetImageSubresourceLayout.txt[]
|
|
|
|
|
|
|
|
Parameters
|
|
|
|
----------
|
|
|
|
|
|
|
|
pname:device::
|
|
|
|
A handle to the device that owns the image.
|
|
|
|
|
|
|
|
pname:image::
|
|
|
|
A handle to the image about which to retrieve information.
|
|
|
|
|
|
|
|
pname:pSubresource::
|
Change log for April 15, 2016 Vulkan 1.0.10 spec update:
* Bump API patch number and header version number to 10 for this
update.
Github Issues:
* Slightly tweak the <<memory-allocation,Host Memory>> allocator language
so that an application wrapping the standard C alloc/free/realloc
functions is still correct - the previous language was too strong with
regards to freeing memory. Also made certain scenarios clearer - an
implementation may now continue without error if an allocation failed
and it is able to continue correctly (public issue 21).
* Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the
corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the
<<sparsememory-miptail,Mip Tail Regions>> section and related commands
flink:vkCreateBuffer and flink:vkCreateImage (public issue 84).
* Update the <<features,Features, Limits, and Formats>> chapter to clarify
interactions between optional features and dynamic state for the
pname:depthBiasClamp and pname:wideLines features (public issue 89).
* Describe the code:WorkgroupSize builtin in the
<<interfaces-builtin-variables,Built-In Variables>> section, and update
the <<compute-shaders,Compute Shaders>> section to further clarify how
to set the number of workgroups to execute in a compute shader (public
issue 145).
* Use the term *image subresource* everywhere instead of *subresource*,
except for the special case of *host-accessible subresource*, which may
be either an image subresource or buffer range (public issue 120)
* Add a note to the <<features,Features, Limits, and Formats>> section
about extensibility of structures (Public issue 165).
* Fix return code flink:vkAcquireNextImageKHR when the timeout parameter
is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue
170).
* Fix typo in slink:VkLayerProperties::pname:apiVersion field (public
issue 172).
Internal Issues:
* Fix a few minor internally-detected typos.
* Minor formatting tweaks to pseudocode in the <<resources,Resource
Creation>> chapter (internal issue 179).
* Fix typo in the definition of point sampling for
elink:VkCullModeFlagBits (internal issue 268).
2016-04-14 08:58:49 +00:00
|
|
|
A pointer to a structure describing the image subresource.
|
2016-02-16 09:53:44 +00:00
|
|
|
|
|
|
|
pname:pLayout::
|
Change log for April 15, 2016 Vulkan 1.0.10 spec update:
* Bump API patch number and header version number to 10 for this
update.
Github Issues:
* Slightly tweak the <<memory-allocation,Host Memory>> allocator language
so that an application wrapping the standard C alloc/free/realloc
functions is still correct - the previous language was too strong with
regards to freeing memory. Also made certain scenarios clearer - an
implementation may now continue without error if an allocation failed
and it is able to continue correctly (public issue 21).
* Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the
corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the
<<sparsememory-miptail,Mip Tail Regions>> section and related commands
flink:vkCreateBuffer and flink:vkCreateImage (public issue 84).
* Update the <<features,Features, Limits, and Formats>> chapter to clarify
interactions between optional features and dynamic state for the
pname:depthBiasClamp and pname:wideLines features (public issue 89).
* Describe the code:WorkgroupSize builtin in the
<<interfaces-builtin-variables,Built-In Variables>> section, and update
the <<compute-shaders,Compute Shaders>> section to further clarify how
to set the number of workgroups to execute in a compute shader (public
issue 145).
* Use the term *image subresource* everywhere instead of *subresource*,
except for the special case of *host-accessible subresource*, which may
be either an image subresource or buffer range (public issue 120)
* Add a note to the <<features,Features, Limits, and Formats>> section
about extensibility of structures (Public issue 165).
* Fix return code flink:vkAcquireNextImageKHR when the timeout parameter
is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue
170).
* Fix typo in slink:VkLayerProperties::pname:apiVersion field (public
issue 172).
Internal Issues:
* Fix a few minor internally-detected typos.
* Minor formatting tweaks to pseudocode in the <<resources,Resource
Creation>> chapter (internal issue 179).
* Fix typo in the definition of point sampling for
elink:VkCullModeFlagBits (internal issue 268).
2016-04-14 08:58:49 +00:00
|
|
|
A pointer to a structure that will receive information about the image
|
|
|
|
subresource.
|
2016-02-16 09:53:44 +00:00
|
|
|
|
|
|
|
Description
|
|
|
|
-----------
|
|
|
|
|
Change log for April 15, 2016 Vulkan 1.0.10 spec update:
* Bump API patch number and header version number to 10 for this
update.
Github Issues:
* Slightly tweak the <<memory-allocation,Host Memory>> allocator language
so that an application wrapping the standard C alloc/free/realloc
functions is still correct - the previous language was too strong with
regards to freeing memory. Also made certain scenarios clearer - an
implementation may now continue without error if an allocation failed
and it is able to continue correctly (public issue 21).
* Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the
corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the
<<sparsememory-miptail,Mip Tail Regions>> section and related commands
flink:vkCreateBuffer and flink:vkCreateImage (public issue 84).
* Update the <<features,Features, Limits, and Formats>> chapter to clarify
interactions between optional features and dynamic state for the
pname:depthBiasClamp and pname:wideLines features (public issue 89).
* Describe the code:WorkgroupSize builtin in the
<<interfaces-builtin-variables,Built-In Variables>> section, and update
the <<compute-shaders,Compute Shaders>> section to further clarify how
to set the number of workgroups to execute in a compute shader (public
issue 145).
* Use the term *image subresource* everywhere instead of *subresource*,
except for the special case of *host-accessible subresource*, which may
be either an image subresource or buffer range (public issue 120)
* Add a note to the <<features,Features, Limits, and Formats>> section
about extensibility of structures (Public issue 165).
* Fix return code flink:vkAcquireNextImageKHR when the timeout parameter
is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue
170).
* Fix typo in slink:VkLayerProperties::pname:apiVersion field (public
issue 172).
Internal Issues:
* Fix a few minor internally-detected typos.
* Minor formatting tweaks to pseudocode in the <<resources,Resource
Creation>> chapter (internal issue 179).
* Fix typo in the definition of point sampling for
elink:VkCullModeFlagBits (internal issue 268).
2016-04-14 08:58:49 +00:00
|
|
|
fname:vkGetImageSubresourceLayout returns information about the memory
|
Change log for April 29, 2016 Vulkan 1.0.12 spec update:
* Bump API patch number and header version number to 12 for this
update.
Github Issues:
* Change valid usage statements intended to be "sub-points" to
be actual sub-points (public issue 66).
* Replace double negation in description of
slink:VkRenderPassBeginInfo::pname:pClearValues (based on public
merge 142).
* Cleanup minor typos in spec, ref pages and XML, including those
proposed in public pull requests 144, 150, 151, 167, 168, 181, and
186.
* Use *strict subset* in describing the partial order of memory
property types for slink:VkMemoryType, and update the style guide
accordingly (public issue 190).
* Fix various "a image" -> "an image" typos (public issue 191).
* Note in the <<fundamentals-validusage,Valid Usage>> and
<<extensions-interactions,Extension Interactions>> sections that
structures defined by extensions which may be passed in structure
chains using the ptext:pNext member must: include initial
ptext:sType and ptext:pNext members (public issue 192).
Internal Issues:
* Remove duplicate language from the description of the pname:fence
parameter to flink:vkQueueSubmit and improve validity language
(internal issue 91).
* Added documentation for "optional" attribute to XML readme.tex/pdf
(internal issue 149).
* Clarify the host-side data validity rules and behavior of
flink:vkFlushMappedMemoryRanges and
flink:vkInvalidateMappedMemoryRanges (internal issue 266).
Other Commits:
* Added clarification to flink:vkCmdFillBuffer regarding the use of
ename:VK_WHOLE_SIZE.
* Fixed and documented implementation of "validextensionstructs"
attribute. in XML processing scripts and readme.tex/pdf.
* Add missing validity statements to flink:vkResetEvent and
flink:vkCmdResetEvent.
* Fix validity for the
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag.
Correct all the draw/dispatch commands to mention optimally tiled
images as well as linear tiled images, and say image VIEWS instead
of images. Add validity statement to flink:vkCmdBlitImage
* Replace the {apiname} macro with hardcoded "Vulkan", now that we've
committed to that name.
* Add the VK_AMD_rasterization_order extension to vk.xml.
2016-04-29 12:53:46 +00:00
|
|
|
layout of an image subresource of an image. pname:device is a handle to the
|
Change log for April 15, 2016 Vulkan 1.0.10 spec update:
* Bump API patch number and header version number to 10 for this
update.
Github Issues:
* Slightly tweak the <<memory-allocation,Host Memory>> allocator language
so that an application wrapping the standard C alloc/free/realloc
functions is still correct - the previous language was too strong with
regards to freeing memory. Also made certain scenarios clearer - an
implementation may now continue without error if an allocation failed
and it is able to continue correctly (public issue 21).
* Require that etext:VK_*_CREATE_SPARSE_BINDING_BIT is set when the
corresponding etext:VK_*_CREATE_SPARSE_RESIDENCY_BIT is used, in the
<<sparsememory-miptail,Mip Tail Regions>> section and related commands
flink:vkCreateBuffer and flink:vkCreateImage (public issue 84).
* Update the <<features,Features, Limits, and Formats>> chapter to clarify
interactions between optional features and dynamic state for the
pname:depthBiasClamp and pname:wideLines features (public issue 89).
* Describe the code:WorkgroupSize builtin in the
<<interfaces-builtin-variables,Built-In Variables>> section, and update
the <<compute-shaders,Compute Shaders>> section to further clarify how
to set the number of workgroups to execute in a compute shader (public
issue 145).
* Use the term *image subresource* everywhere instead of *subresource*,
except for the special case of *host-accessible subresource*, which may
be either an image subresource or buffer range (public issue 120)
* Add a note to the <<features,Features, Limits, and Formats>> section
about extensibility of structures (Public issue 165).
* Fix return code flink:vkAcquireNextImageKHR when the timeout parameter
is 0 to ename:VK_NOT_READY instead of ename:VK_TIMEOUT (public issue
170).
* Fix typo in slink:VkLayerProperties::pname:apiVersion field (public
issue 172).
Internal Issues:
* Fix a few minor internally-detected typos.
* Minor formatting tweaks to pseudocode in the <<resources,Resource
Creation>> chapter (internal issue 179).
* Fix typo in the definition of point sampling for
elink:VkCullModeFlagBits (internal issue 268).
2016-04-14 08:58:49 +00:00
|
|
|
device that owns pname:image, which is the image about which to retrieve
|
|
|
|
information. A description of the image subresource is passsed to the
|
|
|
|
command through an instance of the slink:VkImageSubresource structure, the
|
|
|
|
address of which is passed in pname:pSubresource. The definition of
|
|
|
|
slink:VkImageSubresource is:
|
2016-02-16 09:53:44 +00:00
|
|
|
|
|
|
|
include::../structs/VkImageSubresource.txt[]
|
|
|
|
|
|
|
|
Within the pname:pSubresource structure, pname:aspectMask is a bitfield describing the aspect of the image and
|
|
|
|
is made up of a single member of the elink:VkImageAspectFlagBits enumeration, the definition of which is:
|
|
|
|
|
|
|
|
include::../enums/VkImageAspectFlagBits.txt[]
|
|
|
|
|
|
|
|
The ename:VK_IMAGE_ASPECT_COLOR_BIT aspect is valid only for image formats that are usable as color. The
|
|
|
|
ename:VK_IMAGE_ASPECT_DEPTH_BIT aspect is valid for formats containing depth information and the
|
|
|
|
ename:VK_IMAGE_ASPECT_STENCIL_BIT aspect is valid only for formats containing stencil information. Note
|
|
|
|
that some formats contain both depth and stencil information, and
|
2016-04-21 08:08:38 +00:00
|
|
|
in this case, pname:aspectMask is used to select which to query. It is not legal to include more than
|
2016-02-16 09:53:44 +00:00
|
|
|
one member of elink:VkImageAspectFlagBits in pname:aspectMask. Some formats also include metadata
|
|
|
|
which may be implementation dependent but is queryable by specifying ename:VK_IMAGE_ASPECT_METADATA_BIT.
|
|
|
|
|
|
|
|
For resources that have mipmaps or are multiple array layers, the pname:mipLevel and pname:arrayLayer members describe
|
|
|
|
the mipmap level and array layer, respectively. For resources that do not have mipmaps or are not layered,
|
|
|
|
pname:mipLevel and pname:arrayLayer, respectively, should be set to zero.
|
|
|
|
|
|
|
|
Information about the selected sub-resource is returned to the caller in the instance of the slink:VkSubresourceLayout
|
|
|
|
structure pointed to by pname:pLayout. The definition of slink:VkSubresourceLayout is:
|
|
|
|
|
|
|
|
include::../structs/VkSubresourceLayout.txt[]
|
|
|
|
|
|
|
|
The pname:offset member of the pname:pLayout structure is filled with the relative offset of the start of the sub-resource
|
|
|
|
from the start of the parent resource's memory binding. The pname:size member is the size of the sub-resource in
|
|
|
|
memory. The pname:rowPitch specifies the distance in memory of the start of each texel row of the sub-resource
|
|
|
|
from the start of the previous row. The pname:depthPitch specififes the distance in memory of the start of each
|
|
|
|
slice of the sub-resource relative to the start of the previous slice. For one-dimensional resources, pname:rowPitch
|
|
|
|
is zero, and for one- and two-dimensional resources, pname:depthPitch is zero. All four parameters are specified
|
|
|
|
in bytes.
|
|
|
|
|
|
|
|
include::../validity/protos/vkGetImageSubresourceLayout.txt[]
|
|
|
|
|
|
|
|
See Also
|
|
|
|
--------
|
|
|
|
|
|
|
|
flink:vkGetPhysicalDeviceImageFormatProperties
|
|
|
|
|
|
|
|
include::footer.txt[]
|