Sampler API#

Sampler Device APIs.

Enumerations#

CupvaSamplerIndexInterleavingMode: Supported modes for interleaving indices.
CupvaSamplerIndexRoundingMode: Supported modes for handling round/truncate/interpolation.
CupvaSamplerIndexType: Supported index data types.
CupvaSamplerInput2DFlags: Supported flags for CupvaSamplerInput2D struct initialization.
CupvaSamplerInputType: Supported lookup table pixel formats.
CupvaSamplerMode: Supported task mode.
CupvaSamplerTaskOutOfRangeHandlingMode: Supported modes for out of range handling.
CupvaSamplerTileTraversalMode: Supported modes for tile traversal.
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.

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.

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.

Values:

enumerator SAMPLER_INDEX_TYPE_U16#

enumerator SAMPLER_INDEX_TYPE_U32#

enum CupvaSamplerInput2DFlags#

Supported flags for CupvaSamplerInput2D struct initialization.

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.

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.

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.

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.

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.

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. This API must be called after cupvaSamplerSetup.

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

Parameters:

task – Pointer to sampler to be linked
next – Sampler which will come after task

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.

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

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.

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

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.

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

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:

Call cupvaSamplerSetup APIs to set up a sampler task.
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.

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.

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

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.

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

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.