Function rcudnn::cudaMalloc3DArray[−][src]

pub unsafe extern "C" fn cudaMalloc3DArray(
    array: *mut *mut cudaArray, 
    desc: *const cudaChannelFormatDesc, 
    extent: cudaExtent, 
    flags: u32
) -> cudaError
Expand description

\brief Allocate an array on the device

Allocates a CUDA array according to the ::cudaChannelFormatDesc structure \p desc and returns a handle to the new CUDA array in \p *array.

The ::cudaChannelFormatDesc is defined as: \code struct cudaChannelFormatDesc { int x, y, z, w; enum cudaChannelFormatKind f; }; \endcode where ::cudaChannelFormatKind is one of ::cudaChannelFormatKindSigned, ::cudaChannelFormatKindUnsigned, or ::cudaChannelFormatKindFloat.

::cudaMalloc3DArray() can allocate the following:

  • A 1D array is allocated if the height and depth extents are both zero.
  • A 2D array is allocated if only the depth extent is zero.
  • A 3D array is allocated if all three extents are non-zero.
  • A 1D layered CUDA array is allocated if only the height extent is zero and the cudaArrayLayered flag is set. Each layer is a 1D array. The number of layers is determined by the depth extent.
  • A 2D layered CUDA array is allocated if all three extents are non-zero and the cudaArrayLayered flag is set. Each layer is a 2D array. The number of layers is determined by the depth extent.
  • A cubemap CUDA array is allocated if all three extents are non-zero and the cudaArrayCubemap flag is set. Width must be equal to height, and depth must be six. A cubemap is a special type of 2D layered CUDA array, where the six layers represent the six faces of a cube. The order of the six layers in memory is the same as that listed in ::cudaGraphicsCubeFace.
  • A cubemap layered CUDA array is allocated if all three extents are non-zero, and both, cudaArrayCubemap and cudaArrayLayered flags are set. Width must be equal to height, and depth must be a multiple of six. A cubemap layered CUDA array is a special type of 2D layered CUDA array that consists of a collection of cubemaps. The first six layers represent the first cubemap, the next six layers form the second cubemap, and so on.

The \p flags parameter enables different options to be specified that affect the allocation, as follows.

  • ::cudaArrayDefault: This flag’s value is defined to be 0 and provides default array allocation
  • ::cudaArrayLayered: Allocates a layered CUDA array, with the depth extent indicating the number of layers
  • ::cudaArrayCubemap: Allocates a cubemap CUDA array. Width must be equal to height, and depth must be six. If the cudaArrayLayered flag is also set, depth must be a multiple of six.
  • ::cudaArraySurfaceLoadStore: Allocates a CUDA array that could be read from or written to using a surface reference.
  • ::cudaArrayTextureGather: This flag indicates that texture gather operations will be performed on the CUDA array. Texture gather can only be performed on 2D CUDA arrays.
  • ::cudaArraySparse: Allocates a CUDA array without physical backing memory. The subregions within this sparse array can later be mapped to physical memory by calling ::cuMemMapArrayAsync. This flag can only be used for creating 2D, 3D or 2D layered sparse CUDA arrays. The physical backing memory must be allocated via ::cuMemCreate.

The width, height and depth extents must meet certain size requirements as listed in the following table. All values are specified in elements.

Note that 2D CUDA arrays have different size requirements if the ::cudaArrayTextureGather flag is set. In that case, the valid range for (width, height, depth) is ((1,maxTexture2DGather[0]), (1,maxTexture2DGather[1]), 0).

\xmlonly

CUDA array type Valid extents that must always be met {(width range in elements), (height range), (depth range)} Valid extents with cudaArraySurfaceLoadStore set {(width range in elements), (height range), (depth range)} 1D { (1,maxTexture1D), 0, 0 } { (1,maxSurface1D), 0, 0 } 2D { (1,maxTexture2D[0]), (1,maxTexture2D[1]), 0 } { (1,maxSurface2D[0]), (1,maxSurface2D[1]), 0 } 3D { (1,maxTexture3D[0]), (1,maxTexture3D[1]), (1,maxTexture3D[2]) } OR { (1,maxTexture3DAlt[0]), (1,maxTexture3DAlt[1]), (1,maxTexture3DAlt[2]) } { (1,maxSurface3D[0]), (1,maxSurface3D[1]), (1,maxSurface3D[2]) } 1D Layered { (1,maxTexture1DLayered[0]), 0, (1,maxTexture1DLayered[1]) } { (1,maxSurface1DLayered[0]), 0, (1,maxSurface1DLayered[1]) } 2D Layered { (1,maxTexture2DLayered[0]), (1,maxTexture2DLayered[1]), (1,maxTexture2DLayered[2]) } { (1,maxSurface2DLayered[0]), (1,maxSurface2DLayered[1]), (1,maxSurface2DLayered[2]) } Cubemap { (1,maxTextureCubemap), (1,maxTextureCubemap), 6 } { (1,maxSurfaceCubemap), (1,maxSurfaceCubemap), 6 } Cubemap Layered { (1,maxTextureCubemapLayered[0]), (1,maxTextureCubemapLayered[0]), (1,maxTextureCubemapLayered[1]) } { (1,maxSurfaceCubemapLayered[0]), (1,maxSurfaceCubemapLayered[0]), (1,maxSurfaceCubemapLayered[1]) }
\endxmlonly

\param array - Pointer to allocated array in device memory \param desc - Requested channel format \param extent - Requested allocation size (\p width field in elements) \param flags - Flags for extensions

\return ::cudaSuccess, ::cudaErrorInvalidValue, ::cudaErrorMemoryAllocation \notefnerr \note_init_rt \note_callback

\sa ::cudaMalloc3D, ::cudaMalloc, ::cudaMallocPitch, ::cudaFree, ::cudaFreeArray, \ref ::cudaMallocHost(void**, size_t) “cudaMallocHost (C API)”, ::cudaFreeHost, ::cudaHostAlloc, ::make_cudaExtent, ::cuArray3DCreate