CUDA Runtime API (PDF) - v9.2.88 (older) - Last updated April 12, 2018 - Send Feedback

## 4.24. Surface Reference Management

This section describes the low level surface reference management functions of the CUDA runtime application programming interface.

Some functions have overloaded C++ API template versions documented separately in the C++ API Routines module.

### Functions

__host__ ​cudaError_t cudaBindSurfaceToArray ( const surfaceReference* surfref, cudaArray_const_t array, const cudaChannelFormatDesc* desc )
  Binds an array to a surface.
__host__ ​cudaError_t cudaGetSurfaceReference ( const surfaceReference** surfref, const void* symbol )
  Get the surface reference associated with a symbol.

### Functions

__host__ ​cudaError_t cudaBindSurfaceToArray ( const surfaceReference* surfref, cudaArray_const_t array, const cudaChannelFormatDesc* desc )
  Binds an array to a surface.

  ###### Parameters

  `surfref`
    - Surface to bind
  `array`
    - Memory array on device
  `desc`
    - Channel format

  ###### Returns

  cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidSurface

  ###### Description

  Binds the CUDA array `array` to the surface reference `surfref`. `desc` describes how the memory is interpreted when fetching values from the surface. Any CUDA array previously bound to `surfref` is unbound.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaBindSurfaceToArray ( C++ API), cudaBindSurfaceToArray ( C++ API, inherited channel descriptor), cudaGetSurfaceReference, cuSurfRefSetArray

__host__ ​cudaError_t cudaGetSurfaceReference ( const surfaceReference** surfref, const void* symbol )
  Get the surface reference associated with a symbol.

  ###### Parameters

  `surfref`
    - Surface reference associated with symbol
  `symbol`
    - Surface to get reference for

  ###### Returns

  cudaSuccess, cudaErrorInvalidSurface

  ###### Description

  Returns in `*surfref` the structure associated to the surface reference defined by symbol `symbol`.

  Note:

  - Note that this function may also return error codes from previous, asynchronous launches.

  - Use of a string naming a variable as the `symbol` paramater was removed in CUDA 5.0.

  See also:

  cudaBindSurfaceToArray ( C API), cuModuleGetSurfRef