Package org.lwjgl.vulkan

Class VkBufferImageCopy

  • All Implemented Interfaces:
    java.lang.AutoCloseable, org.lwjgl.system.NativeResource, org.lwjgl.system.Pointer
    public class VkBufferImageCopy
extends org.lwjgl.system.Struct
implements org.lwjgl.system.NativeResource
    Structure specifying a buffer image copy operation.
    Description

    When copying to or from a depth or stencil aspect, the data in buffer memory uses a layout that is a (mostly) tightly packed representation of the depth or stencil data. Specifically:

    Note

    To copy both the depth and stencil aspects of a depth/stencil format, two entries in pRegions can be used, where one specifies the depth aspect in imageSubresource, and the other specifies the stencil aspect.

    Because depth or stencil aspect buffer to image copies may require format conversions on some implementations, they are not supported on queues that do not support graphics.

    When copying to a depth aspect, and the VK_EXT_depth_range_unrestricted extension is not enabled, the data in buffer memory must be in the range [0,1], or the resulting values are undefined.

    Copies are done layer by layer starting with image layer baseArrayLayer member of imageSubresource. layerCount layers are copied from the source image or to the destination image.

    Valid Usage
    • If the calling command’s VkImage parameter’s format is not a depth/stencil format or a multi-planar format, then bufferOffset must be a multiple of the format’s texel block size.
    • If the calling command’s VkImage parameter’s format is a multi-planar format, then bufferOffset must be a multiple of the element size of the compatible format for the format and the aspectMask of the imageSubresource as defined in Compatible formats of planes of multi-planar formats
    • bufferOffset must be a multiple of 4
    • bufferRowLength must be 0, or greater than or equal to the width member of imageExtent
    • bufferImageHeight must be 0, or greater than or equal to the height member of imageExtent
    • imageOffset.x and (imageExtent.width imageOffset.x) must both be greater than or equal to 0 and less than or equal to the image subresource width where this refers to the width of the plane of the image involved in the copy in the case of a multi-planar format
    • imageOffset.y and (imageExtent.height imageOffset.y) must both be greater than or equal to 0 and less than or equal to the image subresource height where this refers to the height of the plane of the image involved in the copy in the case of a multi-planar format
    • If the calling command’s srcImage (CmdCopyImageToBuffer) or dstImage (CmdCopyBufferToImage) is of type IMAGE_TYPE_1D, then imageOffset.y must be 0 and imageExtent.height must be 1.
    • imageOffset.z and (imageExtent.depth imageOffset.z) must both be greater than or equal to 0 and less than or equal to the image subresource depth
    • If the calling command’s srcImage (CmdCopyImageToBuffer) or dstImage (CmdCopyBufferToImage) is of type IMAGE_TYPE_1D or IMAGE_TYPE_2D, then imageOffset.z must be 0 and imageExtent.depth must be 1
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, bufferRowLength must be a multiple of the compressed texel block width
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, bufferImageHeight must be a multiple of the compressed texel block height
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, all members of imageOffset must be a multiple of the corresponding dimensions of the compressed texel block
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, bufferOffset must be a multiple of the compressed texel block size in bytes
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.width must be a multiple of the compressed texel block width or (imageExtent.width imageOffset.x) must equal the image subresource width
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.height must be a multiple of the compressed texel block height or (imageExtent.height imageOffset.y) must equal the image subresource height
    • If the calling command’s VkImage parameter is a compressed image, or a single-plane, “_422” image format, imageExtent.depth must be a multiple of the compressed texel block depth or (imageExtent.depth imageOffset.z) must equal the image subresource depth
    • The aspectMask member of imageSubresource must specify aspects present in the calling command’s VkImage parameter
    • If the calling command’s VkImage parameter’s format is a multi-planar format, then the aspectMask member of imageSubresource must be IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, or IMAGE_ASPECT_PLANE_2_BIT (with IMAGE_ASPECT_PLANE_2_BIT valid only for image formats with three planes)
    • The aspectMask member of imageSubresource must only have a single bit set
    • If the calling command’s VkImage parameter is of VkImageType IMAGE_TYPE_3D, the baseArrayLayer and layerCount members of imageSubresource must be 0 and 1, respectively
    Valid Usage (Implicit)
    See Also

    VkExtent3D, VkImageSubresourceLayers, VkOffset3D, CmdCopyBufferToImage, CmdCopyImageToBuffer

    Member documentation

    • bufferOffset – the offset in bytes from the start of the buffer object where the image data is copied from or to.
    • bufferRowLength – bufferRowLength and bufferImageHeight specify in texels a subregion of a larger two- or three-dimensional image in buffer memory, and control the addressing calculations. If either of these values is zero, that aspect of the buffer memory is considered to be tightly packed according to the imageExtent.
    • bufferImageHeight – see bufferRowLength
    • imageSubresource – a VkImageSubresourceLayers used to specify the specific image subresources of the image used for the source or destination image data.
    • imageOffset – selects the initial x, y, z offsets in texels of the sub-region of the source or destination image data.
    • imageExtent – the size in texels of the image to copy in width, height and depth.

    Layout

    
 struct VkBufferImageCopy {
     VkDeviceSize bufferOffset;
     uint32_t bufferRowLength;
     uint32_t bufferImageHeight;
     VkImageSubresourceLayers imageSubresource;
     VkOffset3D imageOffset;
     VkExtent3D imageExtent;
 }

    • Field Detail

      • SIZEOF

        The struct size in bytes.

      • ALIGNOF

        The struct alignment in bytes.

      • BUFFEROFFSET, BUFFERROWLENGTH, BUFFERIMAGEHEIGHT, IMAGESUBRESOURCE, IMAGEOFFSET, IMAGEEXTENT

        The struct member offsets.

    • Constructor Detail

      • VkBufferImageCopy

        public VkBufferImageCopy​(java.nio.ByteBuffer container)
        Creates a VkBufferImageCopy instance at the current position of the specified ByteBuffer container. Changes to the buffer's content will be visible to the struct instance and vice versa.

        The created instance holds a strong reference to the container object.

    • Method Detail

      • sizeof

        public int sizeof()
        Specified by:
        sizeof in class org.lwjgl.system.Struct

      • bufferOffset

        public long bufferOffset()
        Returns the value of the bufferOffset field.

      • bufferRowLength

        public int bufferRowLength()
        Returns the value of the bufferRowLength field.

      • bufferImageHeight

        public int bufferImageHeight()
        Returns the value of the bufferImageHeight field.

      • bufferOffset

        public VkBufferImageCopy bufferOffset​(long value)
        Sets the specified value to the bufferOffset field.

      • bufferRowLength

        public VkBufferImageCopy bufferRowLength​(int value)
        Sets the specified value to the bufferRowLength field.

      • bufferImageHeight

        public VkBufferImageCopy bufferImageHeight​(int value)
        Sets the specified value to the bufferImageHeight field.

      • imageOffset

        public VkBufferImageCopy imageOffset​(java.util.function.Consumer<VkOffset3D> consumer)
        Passes the imageOffset field to the specified Consumer.

      • imageExtent

        public VkBufferImageCopy imageExtent​(java.util.function.Consumer<VkExtent3D> consumer)
        Passes the imageExtent field to the specified Consumer.

      • malloc

        public static VkBufferImageCopy malloc()
        Returns a new VkBufferImageCopy instance allocated with memAlloc. The instance must be explicitly freed.

      • calloc

        public static VkBufferImageCopy calloc()
        Returns a new VkBufferImageCopy instance allocated with memCalloc. The instance must be explicitly freed.

      • create

        public static VkBufferImageCopy create()
        Returns a new VkBufferImageCopy instance allocated with BufferUtils.

      • create

        public static VkBufferImageCopy create​(long address)
        Returns a new VkBufferImageCopy instance for the specified memory address.

      • createSafe

        @Nullable
public static VkBufferImageCopy createSafe​(long address)
        Like create, but returns null if address is NULL.

      • createSafe

        @Nullable
public static VkBufferImageCopy.Buffer createSafe​(long address,
                                                  int capacity)
        Like create, but returns null if address is NULL.

      • mallocStack

        public static VkBufferImageCopy mallocStack()
        Returns a new VkBufferImageCopy instance allocated on the thread-local MemoryStack.

      • callocStack

        public static VkBufferImageCopy callocStack()
        Returns a new VkBufferImageCopy instance allocated on the thread-local MemoryStack and initializes all its bits to zero.

      • mallocStack

        public static VkBufferImageCopy mallocStack​(org.lwjgl.system.MemoryStack stack)
        Returns a new VkBufferImageCopy instance allocated on the specified MemoryStack.
        Parameters:
        stack - the stack from which to allocate

      • callocStack

        public static VkBufferImageCopy callocStack​(org.lwjgl.system.MemoryStack stack)
        Returns a new VkBufferImageCopy instance allocated on the specified MemoryStack and initializes all its bits to zero.
        Parameters:
        stack - the stack from which to allocate

      • callocStack

        public static VkBufferImageCopy.Buffer callocStack​(int capacity)
        Returns a new VkBufferImageCopy.Buffer instance allocated on the thread-local MemoryStack and initializes all its bits to zero.
        Parameters:
        capacity - the buffer capacity

      • mallocStack

        public static VkBufferImageCopy.Buffer mallocStack​(int capacity,
                                                   org.lwjgl.system.MemoryStack stack)
        Returns a new VkBufferImageCopy.Buffer instance allocated on the specified MemoryStack.
        Parameters:
        stack - the stack from which to allocate
        capacity - the buffer capacity

      • callocStack

        public static VkBufferImageCopy.Buffer callocStack​(int capacity,
                                                   org.lwjgl.system.MemoryStack stack)
        Returns a new VkBufferImageCopy.Buffer instance allocated on the specified MemoryStack and initializes all its bits to zero.
        Parameters:
        stack - the stack from which to allocate
        capacity - the buffer capacity

      • nbufferOffset

        public static long nbufferOffset​(long struct)
        Unsafe version of bufferOffset().

      • nbufferRowLength

        public static int nbufferRowLength​(long struct)
        Unsafe version of bufferRowLength().

      • nbufferImageHeight

        public static int nbufferImageHeight​(long struct)
        Unsafe version of bufferImageHeight().

      • nbufferOffset

        public static void nbufferOffset​(long struct,
                                 long value)
        Unsafe version of bufferOffset.

      • nbufferRowLength

        public static void nbufferRowLength​(long struct,
                                    int value)
        Unsafe version of bufferRowLength.

      • nbufferImageHeight

        public static void nbufferImageHeight​(long struct,
                                      int value)
        Unsafe version of bufferImageHeight.

      • nimageOffset

        public static void nimageOffset​(long struct,
                                VkOffset3D value)
        Unsafe version of imageOffset.

      • nimageExtent

        public static void nimageExtent​(long struct,
                                VkExtent3D value)
        Unsafe version of imageExtent.