// Copyright (c) 2022 NVIDIA Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

[[memory-decompression]]
= Memory Decompression

[open,refpage='vkCmdDecompressMemoryNV',desc='Decompress data between memory regions',type='protos']
--
To decompress data between one or more memory regions call:

include::{generated}/api/protos/vkCmdDecompressMemoryNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:decompressRegionCount is the number of memory regions to
    decompress.
  * pname:pDecompressMemoryRegions is a pointer to an array of
    pname:decompressRegionCount slink:VkDecompressMemoryRegionNV structures
    specifying decompression parameters.

Each region specified in pname:pDecompressMemoryRegions is decompressed from
the source to destination region based on the specified decompression
method.

.Valid Usage
****
  * [[VUID-vkCmdDecompressMemoryNV-None-07684]]
    The <<features-memoryDecompression, pname:memoryDecompression>> feature
    must: be enabled
****

include::{generated}/validity/protos/vkCmdDecompressMemoryNV.adoc[]
--

[open,refpage='VkDecompressMemoryRegionNV',desc='Structure specifying decompression parameters',type='structs']
--
The sname:VkDecompressMemoryRegionNV structure is defined as:

include::{generated}/api/structs/VkDecompressMemoryRegionNV.adoc[]

  * pname:srcAddress is the address where compressed data is stored.
  * pname:dstAddress is the destination address where decompressed data will
    be written.
  * pname:compressedSize is the size of compressed data in bytes.
  * pname:decompressedSize is the size of decompressed data in bytes.
  * pname:decompressionMethod is a bitmask of
    ename:VkMemoryDecompressionMethodFlagBitsNV with a single bit set
    specifying the method used to decompress data.

.Valid Usage
****
  * [[VUID-VkDecompressMemoryRegionNV-srcAddress-07685]]
    The pname:srcAddress must: be 4 byte aligned
  * [[VUID-VkDecompressMemoryRegionNV-srcAddress-07686]]
    The memory in range pname:srcAddress and pname:srcAddress {plus}
    pname:compressedSize must: be valid and bound to a sname:VkDeviceMemory
    object
  * [[VUID-VkDecompressMemoryRegionNV-dstAddress-07687]]
    The pname:dstAddress must: be 4 byte aligned
  * [[VUID-VkDecompressMemoryRegionNV-decompressionMethod-09395]]
    If pname:decompressionMethod is
    ename:VK_MEMORY_DECOMPRESSION_METHOD_GDEFLATE_1_0_BIT_NV, then
    pname:decompressedSize must: be less than or equal to 65536 bytes
  * [[VUID-VkDecompressMemoryRegionNV-dstAddress-07688]]
    The memory in range pname:dstAddress and pname:dstAddress {plus}
    pname:decompressedSize must: be valid and bound to a
    sname:VkDeviceMemory object
  * [[VUID-VkDecompressMemoryRegionNV-decompressedSize-07689]]
    The pname:decompressedSize must: be large enough to hold the
    decompressed data based on the pname:decompressionMethod
  * [[VUID-VkDecompressMemoryRegionNV-decompressionMethod-07690]]
    The pname:decompressionMethod must: have a single bit set
  * [[VUID-VkDecompressMemoryRegionNV-srcAddress-07691]]
    The pname:srcAddress to pname:srcAddress {plus} pname:compressedSize
    region must: not overlap with the pname:dstAddress and pname:dstAddress
    {plus} pname:decompressedSize region
****

include::{generated}/validity/structs/VkDecompressMemoryRegionNV.adoc[]
--

[open,refpage='vkCmdDecompressMemoryIndirectCountNV',desc='Indirect decompress data between memory regions',type='protos']
--
To decompress data between one or more memory regions by specifying
decompression parameters indirectly in a buffer, call:

include::{generated}/api/protos/vkCmdDecompressMemoryIndirectCountNV.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:indirectCommandsAddress is the device address containing
    decompression parameters laid out as an array of
    slink:VkDecompressMemoryRegionNV structures.
  * pname:indirectCommandsCountAddress is the device address containing the
    decompression count.
  * pname:stride is the byte stride between successive sets of decompression
    parameters located starting from pname:indirectCommandsAddress.

Each region specified in pname:indirectCommandsAddress is decompressed from
the source to destination region based on the specified decompression
method.

.Valid Usage
****
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-None-07692]]
    The <<features-memoryDecompression, pname:memoryDecompression>> feature
    must: be enabled
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsAddress-07693]]
    If pname:indirectCommandsAddress comes from a non-sparse buffer then it
    must: be bound completely and contiguously to a single
    sname:VkDeviceMemory object
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsAddress-07694]]
    The slink:VkBuffer that pname:indirectCommandsAddress comes from must:
    have been created with the ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit
    set
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-offset-07695]]
    pname:offset must: be a multiple of `4`
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsCountAddress-07696]]
    If pname:indirectCommandsCountAddress comes from a non-sparse buffer
    then it must: be bound completely and contiguously to a single
    sname:VkDeviceMemory object
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsCountAddress-07697]]
    The slink:VkBuffer that pname:indirectCommandsCountAddress comes from
    must: have been created with the
    ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsCountAddress-07698]]
    pname:indirectCommandsCountAddress must: be a multiple of `4`
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsCountAddress-07699]]
    The count stored in pname:indirectCommandsCountAddress must: be less
    than or equal to
    sname:VkPhysicalDeviceMemoryDecompressionPropertiesNV::pname:maxDecompressionIndirectCount
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-stride-07700]]
    pname:stride must: be a multiple of `4` and must: be greater than or
    equal to sizeof(sname:VkDecompressMemoryRegionNV)
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsCountAddress-07701]]
    If the count stored in pname:indirectCommandsCountAddress is equal to
    `1`, [eq]#(pname:offset {plus}
    sizeof(sname:VkDecompressMemoryRegionNV))# must: be less than or equal
    to the size of the slink:VkBuffer that pname:indirectCommandsAddress
    comes from
  * [[VUID-vkCmdDecompressMemoryIndirectCountNV-indirectCommandsCountAddress-07702]]
    If the count stored in pname:indirectCommandsCountAddress is greater
    than `1`, pname:indirectCommandsAddress {plus}
    sizeof(sname:VkDecompressMemoryRegionNV) {plus} [eq]#(pname:stride
    {times} (count stored in pname:countBuffer - 1))# must: be less than or
    equal to the last valid address in the slink:VkBuffer that
    pname:indirectCommandsAddress was created from
****

include::{generated}/validity/protos/vkCmdDecompressMemoryIndirectCountNV.adoc[]
--

[open,refpage='VkMemoryDecompressionMethodFlagBitsNV',desc='List the supported memory decompression methods',type='enums']
--
Bits which can: be set in
sname:VkDecompressMemoryRegionNV::pname:decompressionMethod specifying the
decompression method to select, or returned in
sname:VkPhysicalDeviceMemoryDecompressionPropertiesNV::pname:decompressionMethods
specifying the available decompression methods are:

include::{generated}/api/enums/VkMemoryDecompressionMethodFlagBitsNV.adoc[]

  * ename:VK_MEMORY_DECOMPRESSION_METHOD_GDEFLATE_1_0_BIT_NV specifies that
    the GDeflate 1.0 algorithm is used to decompress data.
--

[open,refpage='VkMemoryDecompressionMethodFlagsNV',desc='Bitmask of VkMemoryDecompressionMethodFlagBitsNV',type='flags']
--
include::{generated}/api/flags/VkMemoryDecompressionMethodFlagsNV.adoc[]

tname:VkMemoryDecompressionMethodFlagsNV is a bitmask type for specifying a
mask of one or more ename:VkMemoryDecompressionMethodFlagBitsNV:
--
