Sampler API#

Sampler Device APIs.

Enumerations#

uint32_t CupvaSamplerIndexInterleavingMode

Supported modes for interleaving indices.

uint32_t CupvaSamplerIndexRoundingMode

Supported modes for handling round/truncate/interpolation.

uint32_t CupvaSamplerIndexType

Supported index data types.

uint32_t CupvaSamplerInput2DFlags

Supported flags for CupvaSamplerInput2D struct initialization.

uint32_t CupvaSamplerInputType

Supported lookup table pixel formats.

uint32_t CupvaSamplerMode

Supported task mode.

uint32_t CupvaSamplerTaskOutOfRangeHandlingMode

Supported modes for out of range handling.

uint32_t CupvaSamplerTileTraversalMode

Supported modes for tile traversal.

uint32_t CupvaSamplerTileType

Supported modes for tile coordinates.

Functions#

void cupvaSamplerLink(CupvaSampler *task, CupvaSampler const *next)

Link together a list of samplers.

void cupvaSamplerSetup(CupvaSampler *task, CupvaSamplerInput2D const *input, CupvaSamplerIndices2D const *indices, CupvaSamplerOutput const *output)

Configure a sampler for 2D indexing.

void cupvaSamplerSetup(CupvaSampler *task, CupvaSamplerInput1D const *input, CupvaSamplerIndices1D const *indices, CupvaSamplerOutput const *output)

Configure a sampler for 1D indexing.

void cupvaSamplerSetup(CupvaSampler *task, CupvaSamplerInput2D const *input, CupvaSamplerTiles const *tiles, CupvaSamplerOutput const *output)

Configure a sampler for tile sampling.

void cupvaSamplerStart(CupvaSampler const *head)

Start processing an asynchronous list of sampler tasks.

void cupvaSamplerUpdateAddrs(CupvaSampler *task, void const *input, void const *indices, void *output)

Update sampler buffers.

void cupvaSamplerUpdateInputAttributes(CupvaSampler *task, uint32_t const width, uint32_t const height, uint32_t const linePitch)

Update sampler input buffer attributes.

void cupvaSamplerWait(void)

Wait for currently active lookup task list to complete.

Data Structures#

CupvaSampler

Object representing a sampler which runs concurrently with the VPU.

CupvaSamplerIndices1D

Configure a 2D array of indices for sampling into a 1D input buffer.

CupvaSamplerIndices2D

Configure a 2D array of indices for sampling into a 2D input buffer.

CupvaSamplerInput1D

Configure a 1D input buffer for sampling.

CupvaSamplerInput2D

Configure a 2D input buffer for sampling.

CupvaSamplerOutput

Configure a buffer for sampler output.

CupvaSamplerTiles

Configure an array of tile coordinates for sampling 2D patches with bilinear interpolation.

Enumerations#

enum CupvaSamplerIndexInterleavingMode#

Supported modes for interleaving indices.

  • Maturity: GA

Values:

enumerator SAMPLER_INTERLEAVING_ELEMENTS#

Indices are in form x,y,x,y,x,y….

enumerator SAMPLER_INTERLEAVING_32B#

Indices are in 32 byte groups, x,x,x,….,y,y,y,…,x,x,x….,y,y,y….

enum CupvaSamplerIndexRoundingMode#

Supported modes for handling round/truncate/interpolation.

  • Maturity: GA

Values:

enumerator SAMPLER_FRAC_HANDLING_TRUNCATE#

Truncate mode

enumerator SAMPLER_FRAC_HANDLING_ROUND#

Round mode

enumerator SAMPLER_FRAC_HANDLING_INTERPOLATE#

Interpolation mode

enum CupvaSamplerIndexType#

Supported index data types.

  • Maturity: GA

Values:

enumerator SAMPLER_INDEX_TYPE_U16#
enumerator SAMPLER_INDEX_TYPE_U32#
enum CupvaSamplerInput2DFlags#

Supported flags for CupvaSamplerInput2D struct initialization.

  • Maturity: GA

Values:

enumerator NO_DEFAULT_LINE_PITCH#

Flag to force not default initializing the line pitch to width. This may be useful to set input line pitch to 0 for doing 1D lookup using only the x or y indices of an interleaved indices table

enum CupvaSamplerInputType#

Supported lookup table pixel formats.

  • Maturity: GA

Values:

enumerator SAMPLER_INPUT_TYPE_S8#

8-bit signed integer

enumerator SAMPLER_INPUT_TYPE_S16#

16-bit signed integer

enumerator SAMPLER_INPUT_TYPE_S32#

32-bit signed integer

enumerator SAMPLER_INPUT_TYPE_U8#

8-bit unsigned integer

enumerator SAMPLER_INPUT_TYPE_U16#

16-bit unsigned integer

enumerator SAMPLER_INPUT_TYPE_U32#

32-bit unsigned integer

enum CupvaSamplerMode#

Supported task mode.

  • Maturity: GA

Values:

enumerator SAMPLER_LOOKUP_1D#

1D lookup (one common table)

enumerator SAMPLER_LOOKUP_2D#

2D lookup (one common table)

enumerator SAMPLER_INTERP_1D#

1D lookup with linear interpolation (one common table)

enumerator SAMPLER_INTERP_2D#

2D lookup with linear interpolation (one common table)

enumerator SAMPLER_CONFLICT_FREE_2D_INTERP#

Unsupported sampler mode

enumerator SAMPLER_TABLE_REFORMAT#

Unsupported sampler mode

enumerator SAMPLER_INTERP_2D_AUTO_IDX#

2D lookup/interpolation automatically generated index data

enum CupvaSamplerTaskOutOfRangeHandlingMode#

Supported modes for out of range handling.

  • Maturity: GA

Values:

enumerator SAMPLER_OUT_OF_RANGE_CONSTANT#

Return constant values for out-of-bounds lookups

enumerator SAMPLER_OUT_OF_RANGE_PREDICATE_OFF#

Out-of-bounds lookups will not occur, and writes which have a dependency on out-of-bounds lookups will not take place

enum CupvaSamplerTileTraversalMode#

Supported modes for tile traversal.

When using cupvaSamplerTaskCfgTiles, the user can specify the order in which the hardware issues lookups within each tile. This does not affect correctness of output, but adjusting this may reduce conflicts for some lookup patterns.

  • Maturity: GA

Values:

enumerator SAMPLER_TRAVERSAL_STANDARD#

Tile pixels are looked up in standard raster scan pattern

enumerator SAMPLER_TRAVERSAL_TRANSPOSED#

Tile pixels are looked up in transposed pattern (y is the inner dimension)

enum CupvaSamplerTileType#

Supported modes for tile coordinates.

  • Maturity: GA

Values:

enumerator SAMPLER_TILE_TRANS_ONLY#

Tile coords array is in the form [x,y],[x,y],….

enumerator SAMPLER_TILE_TRANS_SCALE#

Tile coords array is in the form [x,y,stepx,stepy],[x,y,stepx,stepy],….

Functions#

inline void cupvaSamplerLink(
CupvaSampler *task,
CupvaSampler const *next,
)#

Link together a list of samplers.

Samplers may be composed in a linked list, so that calling cupvaSamplerStart will execute multiple samplers sequentially.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • task – Pointer to sampler to be linked

  • next – Sampler which will come after task

Pre:

cupvaSamplerSetup must be called prior to calling this API.

inline void cupvaSamplerSetup(
CupvaSampler *task,
CupvaSamplerInput2D const *input,
CupvaSamplerIndices2D const *indices,
CupvaSamplerOutput const *output,
)#

Configure a sampler for 2D indexing.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • task – Pointer to the sampler to be configured

  • input – Input buffer for sampling

  • indices – Buffer containing indices for sampling

  • output – Output buffer to write result

Pre:

None

inline void cupvaSamplerSetup(
CupvaSampler *task,
CupvaSamplerInput1D const *input,
CupvaSamplerIndices1D const *indices,
CupvaSamplerOutput const *output,
)#

Configure a sampler for 1D indexing.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • task – Pointer to the sampler to be configured

  • input – Input buffer for sampling

  • indices – Buffer containing indices for sampling

  • output – Output buffer to write result

Pre:

None

inline void cupvaSamplerSetup(
CupvaSampler *task,
CupvaSamplerInput2D const *input,
CupvaSamplerTiles const *tiles,
CupvaSamplerOutput const *output,
)#

Configure a sampler for tile sampling.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • task – Pointer to the sampler to be configured

  • input – Input buffer for sampling

  • tiles – Buffer containing tile coords/scales for sampling

  • output – Output buffer to write result

Pre:

None

inline void cupvaSamplerStart(CupvaSampler const *head)#

Start processing an asynchronous list of sampler tasks.

This API instructs sampler to start processing sampler tasks. Before calling this API, the users shall do the followings:

  1. Call cupvaSamplerSetup APIs to set up a sampler task.

  2. Call cupvaSamplerLink API to link multiple tasks so that they can be processed together(This is optional).

Only one chain of sampler tasks may be active at any one time. Calling this function while another chain is already active is undefined behavior.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Pre:

None

inline void cupvaSamplerUpdateAddrs(
CupvaSampler *task,
void const *input,
void const *indices,
void *output,
)#

Update sampler buffers.

Samplers which have already been setup using cupvaSamplerSetup() may have the underlying buffers updated using this API. The API can be called to update the buffer addresses for next task while sampler is processing current task. This may be useful for configuring ping/pong arrangements.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • task – Pointer to the sampler to be updated

  • input – Pointer to input data buffer to be sampled

  • indices – Pointer to buffer containing indices or tiles

  • output – Pointer to output buffer

Pre:

None

inline void cupvaSamplerUpdateInputAttributes(
CupvaSampler *task,
uint32_t const width,
uint32_t const height,
uint32_t const linePitch,
)#

Update sampler input buffer attributes.

Samplers which have already been setup using cupvaSamplerSetup() may have the underlying input buffer attributes updated using this API. The API can be called to update the input buffer attributes for next task while sampler is processing current task. This may be useful for configuring ping/pong arrangements.

Pointers passed to this function must be valid and must not be NULL. Failure to do so will result in undefined behavior.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Parameters:

  • task – Pointer to the sampler to be updated

  • width – Width of input buffers

  • height – Height of input buffers

  • linePitch – Line pitch of input buffers

Pre:

None

inline void cupvaSamplerWait(void)#

Wait for currently active lookup task list to complete.

A task list of lookups must have already been started with cupvaSamplerStart before calling this function.

Usage considerations

  • Allowed context for the API call

    • Interrupt handler: No

    • Signal handler: No

    • Thread-safe: No

    • Re-entrant: No

    • Async/Sync: Sync

  • Required privileges: None

  • Allowed execution state

    • Initialization: Yes

    • Operational: Yes

    • Reinit/Deinit Preparation: Yes

  • Maturity: GA

Pre:

None