Safe Haskell | None |
---|---|
Language | Haskell2010 |
Vulkan.Extensions.VK_ANDROID_external_memory_android_hardware_buffer
Description
Name
VK_ANDROID_external_memory_android_hardware_buffer - device extension
VK_ANDROID_external_memory_android_hardware_buffer
- Name String
VK_ANDROID_external_memory_android_hardware_buffer
- Extension Type
- Device extension
- Registered Extension Number
- 130
- Revision
- 3
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Requires
VK_KHR_sampler_ycbcr_conversion
- Requires
VK_KHR_external_memory
- Requires
VK_EXT_queue_family_foreign
- Requires
VK_KHR_dedicated_allocation
- Contact
Other Extension Metadata
- Last Modified Date
- 2019-08-27
- IP Status
- No known IP claims.
- Contributors
- Ray Smith, ARM
- Chad Versace, Google
- Jesse Hall, Google
- Tobias Hector, Imagination
- James Jones, NVIDIA
- Tony Zlatinski, NVIDIA
- Matthew Netsch, Qualcomm
- Andrew Garrard, Samsung
Description
This extension enables an application to import Android
AHardwareBuffer
objects created outside of the Vulkan device into
Vulkan memory objects, where they can be bound to images and buffers.
It also allows exporting an AHardwareBuffer
from a Vulkan memory
object for symmetry with other operating systems. But since not all
AHardwareBuffer
usages and formats have Vulkan equivalents, exporting
from Vulkan provides strictly less functionality than creating the
AHardwareBuffer
externally and importing it.
Some AHardwareBuffer
images have implementation-defined /external
formats that may/ not correspond to Vulkan formats. Sampler Y′CBCR
conversion can be used to sample from these images and convert them to
a known color space.
New Base Types
New Commands
New Structures
MemoryGetAndroidHardwareBufferInfoANDROID
Extending
AndroidHardwareBufferPropertiesANDROID
:Extending
ImageCreateInfo
,SamplerYcbcrConversionCreateInfo
:Extending
ImageFormatProperties2
:Extending
MemoryAllocateInfo
:
New Enum Constants
ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_SPEC_VERSION
Extending
ExternalMemoryHandleTypeFlagBits
:Extending
StructureType
:STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID
STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID
STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID
STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID
STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
Issues
1) Other external memory objects are represented as weakly-typed handles
(e.g. Win32 HANDLE
or
POSIX file descriptor), and require a handle type parameter along with
handles. AHardwareBuffer
is strongly typed, so naming the handle type
is redundant. Does symmetry justify adding handle type
parameters/fields anyway?
RESOLVED: No. The handle type is already provided in places that
treat external memory objects generically. In the places we would add
it, the application code that would have to provide the handle type
value is already dealing with AHardwareBuffer
-specific
commands/structures; the extra symmetry would not be enough to make
that code generic.
2) The internal layout and therefore size of a AHardwareBuffer
image
may depend on native usage flags that do not have corresponding Vulkan
counterparts. Do we provide this information to
createImage
somehow, or allow the allocation size
reported by getImageMemoryRequirements
to be approximate?
RESOLVED: Allow the allocation size to be unspecified when
allocating the memory. It has to work this way for exported image memory
anyway, since AHardwareBuffer
allocation happens in
allocateMemory
, and internally is performed by a
separate HAL, not the Vulkan implementation itself. There is a similar
issue with getImageSubresourceLayout
: the layout
is determined by the allocator HAL, so it is not known until the image
is bound to memory.
3) Should the result of sampling an external-format image with the
suggested Y′CBCR conversion parameters yield the same results as using a
samplerExternalOES
in OpenGL ES?
RESOLVED: This would be desirable, so that apps converting from OpenGL ES to Vulkan could get the same output given the same input. But since sampling and conversion from Y′CBCR images is so loosely defined in OpenGL ES, multiple implementations do it in a way that does not conform to Vulkan’s requirements. Modifying the OpenGL ES implementation would be difficult, and would change the output of existing unmodified applications. Changing the output only for applications that are being modified gives developers the chance to notice and mitigate any problems. Implementations are encouraged to minimize differences as much as possible without causing compatibility problems for existing OpenGL ES applications or violating Vulkan requirements.
4) Should an AHardwareBuffer
with AHARDWAREBUFFER_USAGE_CPU_*
usage
be mappable in Vulkan? Should it be possible to export an
AHardwareBuffers
with such usage?
RESOLVED: Optional, and mapping in Vulkan is not the same as
AHardwareBuffer_lock
. The semantics of these are different: mapping in
memory is persistent, just gives a raw view of the memory contents, and
does not involve ownership. AHardwareBuffer_lock
gives the host
exclusive access to the buffer, is temporary, and allows for
reformatting copy-in/copy-out. Implementations are not required to
support host-visible memory types for imported Android hardware buffers
or resources backed by them. If a host-visible memory type is supported
and used, the memory can be mapped in Vulkan, but doing so follows
Vulkan semantics: it is just a raw view of the data and does not imply
ownership (this means implementations must not internally call
AHardwareBuffer_lock
to implement mapMemory
, or
assume the application has done so). Implementations are not required to
support linear-tiled images backed by Android hardware buffers, even if
the AHardwareBuffer
has CPU usage. There is no reliable way to
allocate memory in Vulkan that can be exported to a AHardwareBuffer
with CPU usage.
5) Android may add new AHardwareBuffer
formats and usage flags over
time. Can reference to them be added to this extension, or do they need
a new extension?
RESOLVED: This extension can document the interaction between the
new AHB formats/usages and existing Vulkan features. No new Vulkan
features or implementation requirements can be added. The extension
version number will be incremented when this additional documentation is
added, but the version number does not indicate that an implementaiton
supports Vulkan memory or resources that map to the new
AHardwareBuffer
features: support for that must be queried with
getPhysicalDeviceImageFormatProperties2
or is implied by successfully allocating a AHardwareBuffer
outside of
Vulkan that uses the new feature and has a GPU usage flag.
In essence, these are new features added to a new Android API level, rather than new Vulkan features. The extension will only document how existing Vulkan features map to that new Android feature.
Version History
Revision 3, 2019-08-27 (Jon Leech)
- Update revision history to correspond to XML version number
Revision 2, 2018-04-09 (Petr Kraus)
- Markup fixes and remove incorrect Draft status
Revision 1, 2018-03-04 (Jesse Hall)
- Initial version
See Also
AHardwareBuffer
, AndroidHardwareBufferFormatPropertiesANDROID
,
AndroidHardwareBufferPropertiesANDROID
,
AndroidHardwareBufferUsageANDROID
, ExternalFormatANDROID
,
ImportAndroidHardwareBufferInfoANDROID
,
MemoryGetAndroidHardwareBufferInfoANDROID
,
getAndroidHardwareBufferPropertiesANDROID
,
getMemoryAndroidHardwareBufferANDROID
Document Notes
For more information, see the Vulkan Specification
This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.
Synopsis
- getAndroidHardwareBufferPropertiesANDROID :: forall a io. (Extendss AndroidHardwareBufferPropertiesANDROID a, PokeChain a, PeekChain a, MonadIO io) => Device -> Ptr AHardwareBuffer -> io (AndroidHardwareBufferPropertiesANDROID a)
- getMemoryAndroidHardwareBufferANDROID :: forall io. MonadIO io => Device -> MemoryGetAndroidHardwareBufferInfoANDROID -> io (Ptr AHardwareBuffer)
- data ImportAndroidHardwareBufferInfoANDROID = ImportAndroidHardwareBufferInfoANDROID {}
- data AndroidHardwareBufferUsageANDROID = AndroidHardwareBufferUsageANDROID {}
- data AndroidHardwareBufferPropertiesANDROID (es :: [Type]) = AndroidHardwareBufferPropertiesANDROID {
- next :: Chain es
- allocationSize :: DeviceSize
- memoryTypeBits :: Word32
- data MemoryGetAndroidHardwareBufferInfoANDROID = MemoryGetAndroidHardwareBufferInfoANDROID {}
- data AndroidHardwareBufferFormatPropertiesANDROID = AndroidHardwareBufferFormatPropertiesANDROID {}
- data ExternalFormatANDROID = ExternalFormatANDROID {}
- type ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_SPEC_VERSION = 3
- pattern ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_SPEC_VERSION :: forall a. Integral a => a
- type ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_EXTENSION_NAME = "VK_ANDROID_external_memory_android_hardware_buffer"
- pattern ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
- data AHardwareBuffer
Documentation
getAndroidHardwareBufferPropertiesANDROID Source #
Arguments
:: forall a io. (Extendss AndroidHardwareBufferPropertiesANDROID a, PokeChain a, PeekChain a, MonadIO io) | |
=> Device |
|
-> Ptr AHardwareBuffer |
|
-> io (AndroidHardwareBufferPropertiesANDROID a) |
vkGetAndroidHardwareBufferPropertiesANDROID - Get Properties of External Memory Android Hardware Buffers
Return Codes
See Also
getMemoryAndroidHardwareBufferANDROID Source #
Arguments
:: forall io. MonadIO io | |
=> Device |
|
-> MemoryGetAndroidHardwareBufferInfoANDROID |
|
-> io (Ptr AHardwareBuffer) |
vkGetMemoryAndroidHardwareBufferANDROID - Get an Android hardware buffer for a memory object
Description
Each call to getMemoryAndroidHardwareBufferANDROID
must return an
Android hardware buffer with a new reference acquired in addition to the
reference held by the DeviceMemory
. To avoid
leaking resources, the application must release the reference by
calling AHardwareBuffer_release
when it is no longer needed. When
called with the same handle in
MemoryGetAndroidHardwareBufferInfoANDROID
::memory
,
getMemoryAndroidHardwareBufferANDROID
must return the same Android
hardware buffer object. If the device memory was created by importing an
Android hardware buffer, getMemoryAndroidHardwareBufferANDROID
must
return that same Android hardware buffer object.
Return Codes
See Also
data ImportAndroidHardwareBufferInfoANDROID Source #
VkImportAndroidHardwareBufferInfoANDROID - Import memory from an Android hardware buffer
Description
If the allocateMemory
command succeeds, the
implementation must acquire a reference to the imported hardware
buffer, which it must release when the device memory object is freed.
If the command fails, the implementation must not retain a reference.
Valid Usage
- If
buffer
is notNULL
, Android hardware buffers must be supported for import, as reported byExternalImageFormatProperties
orExternalBufferProperties
- If
buffer
is notNULL
, it must be a valid Android hardware buffer object withAHardwareBuffer_Desc
::usage
compatible with Vulkan as described in Android Hardware Buffers
Valid Usage (Implicit)
-
buffer
must be a valid pointer to anAHardwareBuffer
value
See Also
Constructors
ImportAndroidHardwareBufferInfoANDROID | |
Fields
|
Instances
data AndroidHardwareBufferUsageANDROID Source #
VkAndroidHardwareBufferUsageANDROID - Struct containing Android hardware buffer usage flags
Description
The androidHardwareBufferUsage
field must include Android hardware
buffer usage flags listed in the
AHardwareBuffer Usage Equivalence
table when the corresponding Vulkan image usage or image creation flags
are included in the usage
or flags
fields of
PhysicalDeviceImageFormatInfo2
.
It must include at least one GPU usage flag
(AHARDWAREBUFFER_USAGE_GPU_*
), even if none of the corresponding
Vulkan usages or flags are requested.
Note
Requiring at least one GPU usage flag ensures that Android hardware
buffer memory will be allocated in a memory pool accessible to the
Vulkan implementation, and that specializing the memory layout based on
usage flags does not prevent it from being compatible with Vulkan.
Implementations may avoid unnecessary restrictions caused by this
requirement by using vendor usage flags to indicate that only the Vulkan
uses indicated in
ImageFormatProperties2
are required.
Valid Usage (Implicit)
See Also
Constructors
AndroidHardwareBufferUsageANDROID | |
Fields
|
Instances
data AndroidHardwareBufferPropertiesANDROID (es :: [Type]) Source #
VkAndroidHardwareBufferPropertiesANDROID - Properties of External Memory Android Hardware Buffers
Valid Usage (Implicit)
-
pNext
must beNULL
or a pointer to a valid instance ofAndroidHardwareBufferFormatPropertiesANDROID
- The
sType
value of each struct in thepNext
chain must be unique
See Also
DeviceSize
,
StructureType
,
getAndroidHardwareBufferPropertiesANDROID
Constructors
AndroidHardwareBufferPropertiesANDROID | |
Fields
|
Instances
data MemoryGetAndroidHardwareBufferInfoANDROID Source #
VkMemoryGetAndroidHardwareBufferInfoANDROID - Structure describing an Android hardware buffer memory export operation
Valid Usage
-
EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
must have been included inExportMemoryAllocateInfo
::handleTypes
whenmemory
was created
- If
the
pNext
chain of theMemoryAllocateInfo
used to allocatememory
included aMemoryDedicatedAllocateInfo
with non-NULL
image
member, then thatimage
must already be bound tomemory
Valid Usage (Implicit)
-
pNext
must beNULL
-
memory
must be a validDeviceMemory
handle
See Also
DeviceMemory
,
StructureType
,
getMemoryAndroidHardwareBufferANDROID
Constructors
MemoryGetAndroidHardwareBufferInfoANDROID | |
Fields
|
Instances
data AndroidHardwareBufferFormatPropertiesANDROID Source #
VkAndroidHardwareBufferFormatPropertiesANDROID - Structure describing the image format properties of an Android hardware buffer
Description
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
FORMAT_UNDEFINED
, indicating the Android
hardware buffer can only be used with an external format.
The formatFeatures
member must include
FORMAT_FEATURE_SAMPLED_IMAGE_BIT
and at least one of
FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT
or
FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
,
and should include
FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
and
FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT
.
Note
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
FORMAT_UNDEFINED
are subject to the format
capabilities obtained from
getPhysicalDeviceFormatProperties2
,
and
getPhysicalDeviceImageFormatProperties2
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 writing to
non-external format images is possible but writing to external format
images is not.
Android hardware buffers with the same external format must have the
same support for
FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT
,
FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT
,
FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
,
FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT
,
FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT
,
and
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
SamplerYcbcrConversion
object (and samplers and
pipelines created from them) for any Android hardware buffers that have
the same external format.
If format
is not FORMAT_UNDEFINED
, then
the value of samplerYcbcrConversionComponents
must be valid when
used as the components
member of
SamplerYcbcrConversionCreateInfo
with that format. If format
is
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 AndroidHardwareBufferFormatPropertiesANDROID
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.
Note
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)
See Also
ChromaLocation
,
ComponentMapping
,
Format
,
FormatFeatureFlags
,
SamplerYcbcrModelConversion
,
SamplerYcbcrRange
,
StructureType
Constructors
AndroidHardwareBufferFormatPropertiesANDROID | |
Fields
|
Instances
data ExternalFormatANDROID Source #
VkExternalFormatANDROID - Structure containing an Android hardware buffer external format
Description
If externalFormat
is zero, the effect is as if the
ExternalFormatANDROID
structure was not present. Otherwise, the
image
will have the specified external format.
Valid Usage (Implicit)
See Also
Constructors
ExternalFormatANDROID | |
Fields
|
Instances
pattern ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_SPEC_VERSION :: forall a. Integral a => a Source #
type ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_EXTENSION_NAME = "VK_ANDROID_external_memory_android_hardware_buffer" Source #
pattern ANDROID_EXTERNAL_MEMORY_ANDROID_HARDWARE_BUFFER_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #
data AHardwareBuffer Source #