VkAndroidHardwareBufferFormatPropertiesANDROID
To obtain format properties of an Android hardware buffer, include a
VkAndroidHardwareBufferFormatPropertiesANDROID
structure in the
pNext
chain of the VkAndroidHardwareBufferPropertiesANDROID
structure passed to vkGetAndroidHardwareBufferPropertiesANDROID.
This structure is defined as:
typedef struct VkAndroidHardwareBufferFormatPropertiesANDROID {
VkStructureType sType;
void* pNext;
VkFormat format;
uint64_t externalFormat;
VkFormatFeatureFlags formatFeatures;
VkComponentMapping samplerYcbcrConversionComponents;
VkSamplerYcbcrModelConversion suggestedYcbcrModel;
VkSamplerYcbcrRange suggestedYcbcrRange;
VkChromaLocation suggestedXChromaOffset;
VkChromaLocation suggestedYChromaOffset;
} VkAndroidHardwareBufferFormatPropertiesANDROID;
sType
is a VkStructureType value identifying this structure.pNext
isNULL
or a pointer to a structure extending this structure.format
is the Vulkan format corresponding to the Android hardware buffer’s format, orVK_FORMAT_UNDEFINED
if there is not an equivalent Vulkan format.externalFormat
is an implementation-defined external format identifier for use with VkExternalFormatANDROID. It must not be zero.formatFeatures
describes the capabilities of this external format when used with an image bound to memory imported frombuffer
.samplerYcbcrConversionComponents
is the component swizzle that should be used in VkSamplerYcbcrConversionCreateInfo.suggestedYcbcrModel
is a suggested color model to use in the VkSamplerYcbcrConversionCreateInfo.suggestedYcbcrRange
is a suggested numerical value range to use in VkSamplerYcbcrConversionCreateInfo.suggestedXChromaOffset
is a suggested X chroma offset to use in VkSamplerYcbcrConversionCreateInfo.suggestedYChromaOffset
is a suggested Y chroma offset to use in VkSamplerYcbcrConversionCreateInfo.
If the Android hardware buffer has one of the formats listed in the
Format Equivalence
table, then format
must have the equivalent Vulkan format listed in
the table.
Otherwise, format
may be VK_FORMAT_UNDEFINED
, indicating the
Android hardware buffer can only be used with an external format.
The formatFeatures
member must include
VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT
and at least one of
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT
or
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
, and should include
VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
and
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT
.
The formatFeatures
member only indicates the features available when
using an
external-format
image created from the Android hardware buffer.
Images from Android hardware buffers with a format other than
VK_FORMAT_UNDEFINED
are subject to the format capabilities obtained
from vkGetPhysicalDeviceFormatProperties2, and
vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters.
These sets of features are independent of each other, e.g. the external
format will support sampler Y′CBCR conversion even if the non-external
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
support for VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
,
VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT
,
VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
,
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT
,
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT
,
and
VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT
.
in formatFeatures
.
Other format features may differ between Android hardware buffers that have
the same external format.
This allows applications to use the same VkSamplerYcbcrConversion
object (and samplers and pipelines created from them) for any Android
hardware buffers that have the same external format.
If format
is not VK_FORMAT_UNDEFINED
, then the value of
samplerYcbcrConversionComponents
must be valid when used as the
components
member of VkSamplerYcbcrConversionCreateInfo with
that format.
If format
is VK_FORMAT_UNDEFINED
, all members of
samplerYcbcrConversionComponents
must be the
identity swizzle.
Implementations may not always be able to determine the color model,
numerical range, or chroma offsets of the image contents, so the values in
VkAndroidHardwareBufferFormatPropertiesANDROID
are only suggestions.
Applications should treat these values as sensible defaults to use in the
absence of more reliable information obtained through some other means.
If the underlying physical device is also usable via OpenGL ES with the
GL_OES_EGL_image_external
extension, the implementation should suggest values that will produce
similar sampled values as would be obtained by sampling the same external
image via samplerExternalOES
in OpenGL ES using equivalent sampler
parameters.
Since
GL_OES_EGL_image_external
does not require the same sampling and conversion calculations as Vulkan
does, achieving identical results between APIs may not be possible on some
implementations.
Valid Usage (Implicit)
VUID-VkAndroidHardwareBufferFormatPropertiesANDROID-sType-sType
sType
must be VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID