vulkan-3.2.0.0: Bindings to the Vulkan graphics API.

Safe HaskellNone
LanguageHaskell2010

Graphics.Vulkan.Core10.Image

Synopsis

Documentation

createImage :: forall a io. (PokeChain a, MonadIO io) => Device -> ImageCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> io Image Source #

vkCreateImage - Create a new image object

Parameters

  • device is the logical device that creates the image.
  • pCreateInfo is a pointer to a ImageCreateInfo structure containing parameters to be used to create the image.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.
  • pImage is a pointer to a Image handle in which the resulting image object is returned.

Valid Usage

Valid Usage (Implicit)

  • device must be a valid Device handle
  • pCreateInfo must be a valid pointer to a valid ImageCreateInfo structure
  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
  • pImage must be a valid pointer to a Image handle

Return Codes

Success
Failure

See Also

AllocationCallbacks, Device, Image, ImageCreateInfo

withImage :: forall a io r. (PokeChain a, MonadIO io) => (io Image -> (Image -> io ()) -> r) -> Device -> ImageCreateInfo a -> Maybe AllocationCallbacks -> r Source #

A convenience wrapper to make a compatible pair of calls to createImage and destroyImage

To ensure that destroyImage is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass '(,)' as the first argument.

destroyImage :: forall io. MonadIO io => Device -> Image -> ("allocator" ::: Maybe AllocationCallbacks) -> io () Source #

vkDestroyImage - Destroy an image object

Parameters

  • device is the logical device that destroys the image.
  • image is the image to destroy.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • All submitted commands that refer to image, either directly or via a ImageView, must have completed execution
  • If AllocationCallbacks were provided when image was created, a compatible set of callbacks must be provided here
  • If no AllocationCallbacks were provided when image was created, pAllocator must be NULL

Valid Usage (Implicit)

  • device must be a valid Device handle
  • If image is not NULL_HANDLE, image must be a valid Image handle
  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
  • If image is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to image must be externally synchronized

See Also

AllocationCallbacks, Device, Image

getImageSubresourceLayout :: forall io. MonadIO io => Device -> Image -> ImageSubresource -> io SubresourceLayout Source #

vkGetImageSubresourceLayout - Retrieve information about an image subresource

Parameters

  • device is the logical device that owns the image.
  • image is the image whose layout is being queried.
  • pSubresource is a pointer to a ImageSubresource structure selecting a specific image for the image subresource.
  • pLayout is a pointer to a SubresourceLayout structure in which the layout is returned.

Description

If the image is linear, then the returned layout is valid for host access.

If the image’s tiling is IMAGE_TILING_LINEAR and its format is a multi-planar format, then getImageSubresourceLayout describes one format plane of the image. If the image’s tiling is IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then getImageSubresourceLayout describes one memory plane of the image. If the image’s tiling is IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and the image is non-linear, then the returned layout has an implementation-dependent meaning; the vendor of the image’s DRM format modifier may provide documentation that explains how to interpret the returned layout.

getImageSubresourceLayout is invariant for the lifetime of a single image. However, the subresource layout of images in Android hardware buffer external memory is not known until the image has been bound to memory, so applications must not call getImageSubresourceLayout for such an image before it has been bound.

Valid Usage

Valid Usage (Implicit)

  • device must be a valid Device handle
  • image must be a valid Image handle
  • pSubresource must be a valid pointer to a valid ImageSubresource structure
  • pLayout must be a valid pointer to a SubresourceLayout structure
  • image must have been created, allocated, or retrieved from device

See Also

Device, Image, ImageSubresource, SubresourceLayout

data ImageSubresource Source #

VkImageSubresource - Structure specifying an image subresource

Valid Usage (Implicit)

See Also

ImageAspectFlags, SparseImageMemoryBind, getImageSubresourceLayout

Constructors

ImageSubresource 

Fields

Instances
Show ImageSubresource Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

Storable ImageSubresource Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

FromCStruct ImageSubresource Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

ToCStruct ImageSubresource Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

Zero ImageSubresource Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

data ImageCreateInfo (es :: [Type]) Source #

VkImageCreateInfo - Structure specifying the parameters of a newly created image object

Description

Images created with tiling equal to IMAGE_TILING_LINEAR have further restrictions on their limits and capabilities compared to images created with tiling equal to IMAGE_TILING_OPTIMAL. Creation of images with tiling IMAGE_TILING_LINEAR may not be supported unless other parameters meet all of the constraints:

Images created with a format from one of those listed in https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#formats-requiring-sampler-ycbcr-conversion have further restrictions on their limits and capabilities compared to images created with other formats. Creation of images with a format requiring Y′CBCR conversion may not be supported unless other parameters meet all of the constraints:

Implementations may support additional limits and capabilities beyond those listed above.

To determine the set of valid usage bits for a given format, call getPhysicalDeviceFormatProperties.

If the size of the resultant image would exceed maxResourceSize, then createImage must fail and return ERROR_OUT_OF_DEVICE_MEMORY. This failure may occur even when all image creation parameters satisfy their valid usage requirements.

Note

For images created without IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for the format the image is created with.

For images created with IMAGE_CREATE_EXTENDED_USAGE_BIT a usage bit is valid if it is supported for at least one of the formats a ImageView created from the image can have (see Image Views for more detail).

Valid values for some image creation parameters are limited by a numerical upper bound or by inclusion in a bitset. For example, ImageCreateInfo::arrayLayers is limited by imageCreateMaxArrayLayers, defined below; and ImageCreateInfo::samples is limited by imageCreateSampleCounts, also defined below.

Several limiting values are defined below, as well as assisting values from which the limiting values are derived. The limiting values are referenced by the relevant valid usage statements of ImageCreateInfo.

Valid Usage

  • Each of the following values (as described in Image Creation Limits) must not be undefined imageCreateMaxMipLevels, imageCreateMaxArrayLayers, imageCreateMaxExtent, and imageCreateSampleCounts

Valid Usage (Implicit)

</section> = See Also

Extent3D, Format, ImageCreateFlags, ImageLayout, ImageTiling, ImageType, ImageUsageFlags, SampleCountFlagBits, SharingMode, StructureType, createImage

Constructors

ImageCreateInfo 

Fields

data SubresourceLayout Source #

VkSubresourceLayout - Structure specifying subresource layout

Description

If the image is linear, then rowPitch, arrayPitch and depthPitch describe the layout of the image subresource in linear memory. For uncompressed formats, rowPitch is the number of bytes between texels with the same x coordinate in adjacent rows (y coordinates differ by one). arrayPitch is the number of bytes between texels with the same x and y coordinate in adjacent array layers of the image (array layer values differ by one). depthPitch is the number of bytes between texels with the same x and y coordinate in adjacent slices of a 3D image (z coordinates differ by one). Expressed as an addressing formula, the starting byte of a texel in the image subresource has address:

// (x,y,z,layer) are in texel coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset

For compressed formats, the rowPitch is the number of bytes between compressed texel blocks in adjacent rows. arrayPitch is the number of bytes between compressed texel blocks in adjacent array layers. depthPitch is the number of bytes between compressed texel blocks in adjacent slices of a 3D image.

// (x,y,z,layer) are in compressed texel block coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;

The value of arrayPitch is undefined for images that were not created as arrays. depthPitch is defined only for 3D images.

If the image has a single-plane color format and its tiling is IMAGE_TILING_LINEAR , then the aspectMask member of ImageSubresource must be IMAGE_ASPECT_COLOR_BIT.

If the image has a depth/stencil format and its tiling is IMAGE_TILING_LINEAR , then aspectMask must be either IMAGE_ASPECT_DEPTH_BIT or IMAGE_ASPECT_STENCIL_BIT. On implementations that store depth and stencil aspects separately, querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that aspect. On implementations that store depth and stencil aspects interleaved, the same offset and size are returned and represent the interleaved memory allocation.

If the image has a multi-planar format and its tiling is IMAGE_TILING_LINEAR , then the aspectMask member of ImageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or (for 3-plane formats only) IMAGE_ASPECT_PLANE_2_BIT. Querying each of these image subresource layouts will return a different offset and size representing the region of memory used for that plane. If the image is disjoint, then the offset is relative to the base address of the plane. If the image is non-disjoint, then the offset is relative to the base address of the image.

If the image’s tiling is IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of ImageSubresource must be one of VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT, where the maximum allowed plane index i is defined by the DrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s ImageCreateInfo::format and modifier. The memory range used by the subresource is described by offset and size. If the image is disjoint, then the offset is relative to the base address of the memory plane. If the image is non-disjoint, then the offset is relative to the base address of the image. If the image is non-linear, then rowPitch, arrayPitch, and depthPitch have an implementation-dependent meaning.

See Also

DeviceSize, ImageDrmFormatModifierExplicitCreateInfoEXT, getImageSubresourceLayout

Constructors

SubresourceLayout 

Fields

  • offset :: DeviceSize

    offset is the byte offset from the start of the image or the plane where the image subresource begins.

  • size :: DeviceSize

    size is the size in bytes of the image subresource. size includes any extra memory that is required based on rowPitch.

  • rowPitch :: DeviceSize

    rowPitch describes the number of bytes between each row of texels in an image.

  • arrayPitch :: DeviceSize

    arrayPitch describes the number of bytes between each array layer of an image.

  • depthPitch :: DeviceSize

    depthPitch describes the number of bytes between each slice of 3D image.

Instances
Show SubresourceLayout Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

Storable SubresourceLayout Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

FromCStruct SubresourceLayout Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

ToCStruct SubresourceLayout Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image

Zero SubresourceLayout Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Image