VPI - Vision Programming Interface

1.2 Release

Data layout utilities

Data Structures

struct  VPIPackingParams
 Defines the parameters encoded in a VPIPacking. More...
 

Macros

#define VPI_MAKE_SWIZZLE_ABBREV(x, y, z, w)
 Creates a user-defined swizzle operation, using abbreviated parameters. More...
 
#define VPI_MAKE_SWIZZLE(x, y, z, w)
 Creates a user-defined swizzle operation. More...
 

Enumerations

enum  VPIPacking
 Defines how channels are packed into an image plane element. More...
 
enum  VPIDataType
 Defines the channel data type. More...
 
enum  VPIMemLayout
 Defines how the 2D plane pixels are laid out in memory. More...
 
enum  VPIChannel
 Defines the format channel names. More...
 
enum  VPISwizzle
 Defines the supported channel swizzle operations. More...
 
enum  VPIEndianness
 Endianness of a VPIPacking value. More...
 

Functions

VPISwizzle vpiMakeSwizzle (VPIChannel x, VPIChannel y, VPIChannel z, VPIChannel w)
 Creates a user-defined VPISwizzle operation. More...
 
void vpiSwizzleGetChannels (VPISwizzle swizzle, VPIChannel *channels)
 Get the swizzle channels. More...
 
int vpiSwizzleGetChannelCount (VPISwizzle swizzle)
 Get the number of channels specified by the given swizzle. More...
 
VPIPacking vpiMakePacking (const VPIPackingParams *params)
 Returns a pre-defined VPIPacking given its params. More...
 
void vpiPackingGetParams (VPIPacking packing, VPIPackingParams *params)
 Returns channels' information from a format packing. More...
 
int vpiPackingGetComponentCount (VPIPacking packing)
 Returns the number of components defined by the given packing. More...
 
void vpiPackingGetBitsPerComponent (VPIPacking packing, int32_t *bits)
 Returns the number of bits per packing component. More...
 
int vpiPackingGetBitsPerPixel (VPIPacking packing)
 Returns the number of bits per pixel of the given packing. More...
 

Detailed Description


Data Structure Documentation

◆ VPIPackingParams

struct VPIPackingParams

Defines the parameters encoded in a VPIPacking.

Definition at line 423 of file DataLayout.h.

+ Collaboration diagram for VPIPackingParams:
Data Fields
int bits[4] Number of bits in each channel.

If channel doesn't exist, corresponding bits==0.

VPIEndianness endianness Component ordering in a word.
VPISwizzle swizzle Channel ordering.

Macro Definition Documentation

◆ VPI_MAKE_SWIZZLE

#define VPI_MAKE_SWIZZLE (   x,
  y,
  z,
 
)

#include <vpi/DataLayout.h>

Creates a user-defined swizzle operation.

This macro is used to create a user-defined swizzle operation if it's not predefined. Example:

VPISwizzle
Defines the supported channel swizzle operations.
Definition: DataLayout.h:282
#define VPI_MAKE_SWIZZLE(x, y, z, w)
Creates a user-defined swizzle operation.
Definition: DataLayout.h:379
@ VPI_CHANNEL_Z
Selects the third channel of the color model.
Definition: DataLayout.h:269
@ VPI_CHANNEL_0
Don't select a channel.
Definition: DataLayout.h:266
@ VPI_CHANNEL_W
Selects the fourth channel of the color model.
Definition: DataLayout.h:270
@ VPI_CHANNEL_Y
Selects the second channel of the color model.
Definition: DataLayout.h:268
Parameters
[in]xChannel that will correspond to the first component.
[in]yChannel that will correspond to the second component.
[in]zChannel that will correspond to the third component.
[in]wChannel that will correspond to the component component.
Returns
the user-defined VPISwizzle operation.

Definition at line 379 of file DataLayout.h.

◆ VPI_MAKE_SWIZZLE_ABBREV

#define VPI_MAKE_SWIZZLE_ABBREV (   x,
  y,
  z,
 
)

#include <vpi/DataLayout.h>

Creates a user-defined swizzle operation, using abbreviated parameters.

This macro is used to create a user-defined swizzle operation. Parameters are specified literally by X, Y, Z, 0, 1. They correpond to VPIChannel values. Example:

#define VPI_MAKE_SWIZZLE_ABBREV(x, y, z, w)
Creates a user-defined swizzle operation, using abbreviated parameters.
Definition: DataLayout.h:359
Parameters
[in]xChannel that will correspond to the first component, without the VPI_CHANNEL prefix.
[in]yChannel that will correspond to the second component, without the VPI_CHANNEL prefix.
[in]zChannel that will correspond to the third component, without the VPI_CHANNEL prefix.
[in]wChannel that will correspond to the component component, without the VPI_CHANNEL prefix.
Returns
the user-defined VPISwizzle operation.

Definition at line 359 of file DataLayout.h.

Enumeration Type Documentation

◆ VPIChannel

enum VPIChannel

#include <vpi/DataLayout.h>

Defines the format channel names.

The channels are color model-agnostic.

Enumerator
VPI_CHANNEL_INVALID 

Represents an invalid swizzle channel.

VPI_CHANNEL_0 

Don't select a channel.

VPI_CHANNEL_X 

Selects the first channel of the color model.

VPI_CHANNEL_Y 

Selects the second channel of the color model.

VPI_CHANNEL_Z 

Selects the third channel of the color model.

VPI_CHANNEL_W 

Selects the fourth channel of the color model.

VPI_CHANNEL_1 

Sets the corresponding channel to have its maximum value.

Definition at line 262 of file DataLayout.h.

◆ VPIDataType

#include <vpi/DataLayout.h>

Defines the channel data type.

Enumerator
VPI_DATA_TYPE_UNSIGNED 

Channels are unsigned integer values.

VPI_DATA_TYPE_SIGNED 

Channels are signed integer values.

VPI_DATA_TYPE_FLOAT 

Channel are floating point values.

VPI_DATA_TYPE_FLOATISP 

Proprietary floating point format from NVIDIA.

Definition at line 209 of file DataLayout.h.

◆ VPIEndianness

#include <vpi/DataLayout.h>

Endianness of a VPIPacking value.

Enumerator
VPI_INVALID_ENDIAN 

Invalid endianness value.

VPI_HOST_ENDIAN 

Endianness of the host machine.

VPI_BIG_ENDIAN 

Big endian, where most significant byte has lower memory address.

Definition at line 415 of file DataLayout.h.

◆ VPIMemLayout

#include <vpi/DataLayout.h>

Defines how the 2D plane pixels are laid out in memory.

This defines how a pixel are addressed, i.e., given its \((x,y)\) coordinate, what's its memory address. Block-linear formats have a proprietary memory representation and aren't supposed to be addressed by the user directly.

Enumerator
VPI_MEM_LAYOUT_INVALID 

Represents an invalid memory layout.

VPI_MEM_LAYOUT_PITCH_LINEAR 

Pixels are laid out in row-major order, i.e., \((x,y) = y \times \mathit{pitch} + x \times \mathit{pixel stride}\).

VPI_MEM_LAYOUT_BLOCK1_LINEAR 

Pixels are laid out in block-linear format with height = 1.

VPI_MEM_LAYOUT_BLOCK2_LINEAR 

Pixels are laid out in block-linear format with height = 2.

VPI_MEM_LAYOUT_BLOCK4_LINEAR 

Pixels are laid out in block-linear format with height = 4.

VPI_MEM_LAYOUT_BLOCK8_LINEAR 

Pixels are laid out in block-linear format with height = 8.

VPI_MEM_LAYOUT_BLOCK16_LINEAR 

Pixels are laid out in block-linear format with height = 16.

VPI_MEM_LAYOUT_BLOCK32_LINEAR 

Pixels are laid out in block-linear format with height = 32.

VPI_MEM_LAYOUT_BLOCK_LINEAR 

Default block-linear format.

It's guaranteed to be valid in all algorithms that support block-linear format.

VPI_MEM_LAYOUT_PL 

Useful alias.

VPI_MEM_LAYOUT_BL 

Useful alias.

Definition at line 224 of file DataLayout.h.

◆ VPIPacking

enum VPIPacking

#include <vpi/DataLayout.h>

Defines how channels are packed into an image plane element.

Packing encodes how many channels the plane element has, and how they are arranged in memory.

Up to 4 channels (denoted by X, Y, Z, W) can be packed into an image plane element, each one occupying a specified number of bits.

When two channels are specified one right after the other, they are ordered from most-significant bit to least-significant bit. Words are separated by underscores. For example:

X8Y8Z8W8 = a single 32-bit word containing 4 channels, 8 bits each.

In little-endian architectures:

     Address  0   ||  1   ||  2   ||  3
           WWWWWWWWZZZZZZZZYYYYYYYYXXXXXXXX

In big-endian architectures:

     Address  0   ||  1   ||  2   ||  3
           XXXXXXXXYYYYYYYYZZZZZZZZWWWWWWWW

X8_Y8_Z8_W8 = four consecutive 8-bit words, corresponding to 4 channels, 8 bits each.

In little-endian architectures:

     Address  0   ||  1   ||  2   ||  3
           XXXXXXXXYYYYYYYYZZZZZZZZWWWWWWWW

In big-endian architectures:

     Address  0   ||  1   ||  2   ||  3
           XXXXXXXXYYYYYYYYZZZZZZZZWWWWWWWW

In cases where a word is less than 8 bits (e.g., X1 1-bit channel), channels are ordered from LSB to MSB within a word.

Note
Also note equivalences such as the following:
In little-endian: X8_Y8_Z8_W8 = W8Z8Y8X8.
In big-endian: X8_Y8_Z8_W8 = X8Y8Z8W8.

Some formats allow different packings when pixels' horizontal coordinate is even or odd. For instance, every pixel of YUV422 packed format contains an Y channel, while only even pixels contain the U channel, and odd pixels contain V channel. Such formats use a double-underscore to separate the even pixels from the odd pixels. The packing just described might be referred to X8_Y8__X8_Z8, where X = luma, Y = U chroma, Z = V chroma.

Enumerator
VPI_PACKING_0 

No channels.

VPI_PACKING_X1 

One 1-bit channel.

VPI_PACKING_X2 

One 2-bit channel.

VPI_PACKING_X4 

One 4-bit channel.

VPI_PACKING_X8 

One 8-bit channel.

VPI_PACKING_X4Y4 

Two 4-bit channels in one word.

VPI_PACKING_X3Y3Z2 

Three 3-, 3- and 2-bit channels in one 8-bit word.

VPI_PACKING_X16 

One 16-bit channel.

VPI_PACKING_b6X10 

One LSB 10-bit channel in one 16-bit word.

VPI_PACKING_X10b6 

One MSB 10-bit channel in one 16-bit word.

VPI_PACKING_b4X12 

One LSB 12-bit channel in one 16-bit word.

VPI_PACKING_X12b4 

One MSB 12-bit channel in one 16-bit word.

VPI_PACKING_b2X14 

One LSB 14-bit channel in one 16-bit word.

VPI_PACKING_X8_Y8 

Two 8-bit channels in two 8-bit words.

VPI_PACKING_X5Y5Z6 

Three 5-, 5- and 6-bit channels in one 16-bit word.

VPI_PACKING_X5Y6Z5 

Three 5-, 6- and 5-bit channels in one 16-bit word.

VPI_PACKING_X6Y5Z5 

Three 6-, 5- and 5-bit channels in one 16-bit word.

VPI_PACKING_b4X4Y4Z4 

Three 4-bit channels in one 16-bit word.

VPI_PACKING_b1X5Y5Z5 

Three 5-bit channels in one 16-bit word.

VPI_PACKING_X5Y5b1Z5 

Three 5-bit channels in one 16-bit word.

VPI_PACKING_X1Y5Z5W5 

Four 1-, 5-, 5- and 5-bit channels in one 16-bit word.

VPI_PACKING_X4Y4Z4W4 

Four 4-bit channels in one 16-bit word.

VPI_PACKING_X5Y1Z5W5 

Four 5-, 1-, 5- and 5-bit channels in one 16-bit word.

VPI_PACKING_X5Y5Z1W5 

Four 5-, 5-, 1- and 5-bit channels in one 16-bit word.

VPI_PACKING_X5Y5Z5W1 

Four 5-, 5-, 5- and 1-bit channels in one 16-bit word.

VPI_PACKING_X8_Y8__X8_Z8 

2 pixels of 2 8-bit channels each, totalling 4 8-bit words.

VPI_PACKING_Y8_X8__Z8_X8 

2 pixels of 2 swapped 8-bit channels each, totalling 4 8-bit words.

VPI_PACKING_X24 

One 24-bit channel.

VPI_PACKING_X8_Y8_Z8 

Three 8-bit channels in three 8-bit words.

VPI_PACKING_X32 

One 32-bit channel.

VPI_PACKING_b12X20 

One LSB 20-bit channel in one 32-bit word.

VPI_PACKING_X16_Y16 

Two 16-bit channels in two 16-bit words.

VPI_PACKING_X10b6_Y10b6 

Two MSB 10-bit channels in two 16-bit words.

VPI_PACKING_X12b4_Y12b4 

Two MSB 12-bit channels in two 16-bit words.

VPI_PACKING_X10Y11Z11 

Three 10-, 11- and 11-bit channels in one 32-bit word.

VPI_PACKING_X11Y11Z10 

Three 11-, 11- and 10-bit channels in one 32-bit word.

VPI_PACKING_X8_Y8_Z8_W8 

Four 8-bit channels in one 32-bit word.

VPI_PACKING_X2Y10Z10W10 

Four 2-, 10-, 10- and 10-bit channels in one 32-bit word.

VPI_PACKING_X10Y10Z10W2 

Four 10-, 10-, 10- and 2-bit channels in one 32-bit word.

VPI_PACKING_X48 

One 48-bit channel.

VPI_PACKING_X16_Y16_Z16 

Three 16-bit channels in three 16-bit words.

VPI_PACKING_X64 

One 64-bit channel.

VPI_PACKING_X32_Y32 

Two 32-bit channels in two 32-bit words.

VPI_PACKING_X16_Y16_Z16_W16 

Four 16-bit channels in one 64-bit word.

VPI_PACKING_X96 

One 96-bit channel.

VPI_PACKING_X32_Y32_Z32 

Three 32-bit channels in three 32-bit words.

VPI_PACKING_X128 

One 128-bit channel.

VPI_PACKING_X32_Y32_Z32_W32 

Four 32-bit channels in three 32-bit words.

VPI_PACKING_X192 

One 192-bit channel.

VPI_PACKING_X64_Y64_Z64 

Three 64-bit channels in three 64-bit words.

VPI_PACKING_X256 

One 128-bit channel.

VPI_PACKING_X64_Y64_Z64_W64 

Four 64-bit channels in four 64-bit words.

VPI_PACKING_INVALID 

Denotes an invalid packing.

Definition at line 127 of file DataLayout.h.

◆ VPISwizzle

enum VPISwizzle

#include <vpi/DataLayout.h>

Defines the supported channel swizzle operations.

The operations map an input vector \((x,y,z,w)\) into an output vector \((x',y',z',w')\). Any output channel can select any of the input channels, or the constants zero or one. For example, the swizzle "X000" selects the first channel, whereas swizzle "ZYXW" swaps the X and Z channels, needed for conversion between RGBA and BGRA image formats.

Enumerator
VPI_SWIZZLE_INVALID 

Represents an invalid swizzle.

VPI_SWIZZLE_0000 

Swizzle operation.

VPI_SWIZZLE_1000 

Swizzle operation.

VPI_SWIZZLE_0001 

Swizzle operation.

VPI_SWIZZLE_XYZW 

Swizzle operation.

VPI_SWIZZLE_ZYXW 

Swizzle operation.

VPI_SWIZZLE_WXYZ 

Swizzle operation.

VPI_SWIZZLE_WZYX 

Swizzle operation.

VPI_SWIZZLE_YZWX 

Swizzle operation.

VPI_SWIZZLE_XYZ1 

Swizzle operation.

VPI_SWIZZLE_XYZ0 

Swizzle operation.

VPI_SWIZZLE_YZW1 

Swizzle operation.

VPI_SWIZZLE_XXX1 

Swizzle operation.

VPI_SWIZZLE_XZY1 

Swizzle operation.

VPI_SWIZZLE_ZYX1 

Swizzle operation.

VPI_SWIZZLE_ZYX0 

Swizzle operation.

VPI_SWIZZLE_WZY1 

Swizzle operation.

VPI_SWIZZLE_X000 

Swizzle operation.

VPI_SWIZZLE_0X00 

Swizzle operation.

VPI_SWIZZLE_00X0 

Swizzle operation.

VPI_SWIZZLE_000X 

Swizzle operation.

VPI_SWIZZLE_Y000 

Swizzle operation.

VPI_SWIZZLE_0Y00 

Swizzle operation.

VPI_SWIZZLE_00Y0 

Swizzle operation.

VPI_SWIZZLE_000Y 

Swizzle operation.

VPI_SWIZZLE_0XY0 

Swizzle operation.

VPI_SWIZZLE_XXXY 

Swizzle operation.

VPI_SWIZZLE_YYYX 

Swizzle operation.

VPI_SWIZZLE_0YX0 

Swizzle operation.

VPI_SWIZZLE_X00Y 

Swizzle operation.

VPI_SWIZZLE_Y00X 

Swizzle operation.

VPI_SWIZZLE_X001 

Swizzle operation.

VPI_SWIZZLE_XY01 

Swizzle operation.

VPI_SWIZZLE_XY00 

Swizzle operation.

VPI_SWIZZLE_0XZ0 

Swizzle operation.

VPI_SWIZZLE_0ZX0 

Swizzle operation.

VPI_SWIZZLE_XZY0 

Swizzle operation.

VPI_SWIZZLE_YZX1 

Swizzle operation.

VPI_SWIZZLE_ZYW1 

Swizzle operation.

VPI_SWIZZLE_0YX1 

Swizzle operation.

VPI_SWIZZLE_XYXZ 

Swizzle operation.

VPI_SWIZZLE_YXZX 

Swizzle operation.

VPI_SWIZZLE_XZ00 

Swizzle operation.

VPI_SWIZZLE_WYXZ 

Swizzle operation.

VPI_SWIZZLE_YX00 

Swizzle operation.

VPI_SWIZZLE_YX01 

Swizzle operation.

VPI_SWIZZLE_00YX 

Swizzle operation.

VPI_SWIZZLE_00XY 

Swizzle operation.

VPI_SWIZZLE_0XY1 

Swizzle operation.

VPI_SWIZZLE_0X01 

Swizzle operation.

VPI_SWIZZLE_YZXW 

Swizzle operation.

VPI_SWIZZLE_YW00 

Swizzle operation.

VPI_SWIZZLE_XYW0 

Swizzle operation.

VPI_SWIZZLE_YZW0 

Swizzle operation.

Definition at line 281 of file DataLayout.h.

Function Documentation

◆ vpiMakePacking()

VPIPacking vpiMakePacking ( const VPIPackingParams params)

#include <vpi/DataLayout.h>

Returns a pre-defined VPIPacking given its params.

This function calculates the VPIPacking based on the channel characteristics at run time.

Parameters
[in]paramsPacking parameters. If swizzle attribute is VPI_SWIZZLE_0000 or VPI_SWIZZLE_INVALID, it'll be inferred from the number of bits of each channel.
Returns
the corresponding VPIPacking, or VPI_PACKING_INVALID if packing isn't defined or params is NULL.

◆ vpiMakeSwizzle()

VPISwizzle vpiMakeSwizzle ( VPIChannel  x,
VPIChannel  y,
VPIChannel  z,
VPIChannel  w 
)

#include <vpi/DataLayout.h>

Creates a user-defined VPISwizzle operation.

This is similar to VPI_MAKE_SWIZZLE, but accepts the swizzle channels as runtime variables.

Parameters
[in]xChannel that will correspond to the first component.
[in]yChannel that will correspond to the second component.
[in]zChannel that will correspond to the third component.
[in]wChannel that will correspond to the component component.
Returns
the user-defined VPISwizzle operation.

◆ vpiPackingGetBitsPerComponent()

void vpiPackingGetBitsPerComponent ( VPIPacking  packing,
int32_t *  bits 
)

#include <vpi/DataLayout.h>

Returns the number of bits per packing component.

Parameters
[in]packingThe format packing to be queried.
[out]bitsPointer to an int32_t array with 4 elements where output will be stored. If it's NULL, the function is a no-op.

◆ vpiPackingGetBitsPerPixel()

int vpiPackingGetBitsPerPixel ( VPIPacking  packing)

#include <vpi/DataLayout.h>

Returns the number of bits per pixel of the given packing.

Parameters
[in]packingThe format packing to be queried.
Returns
Total number of bits per pixel of the given packing. It's the sum of number of bits occupied by all packing channels.

◆ vpiPackingGetComponentCount()

int vpiPackingGetComponentCount ( VPIPacking  packing)

#include <vpi/DataLayout.h>

Returns the number of components defined by the given packing.

Parameters
[in]packingThe format packing to be queried.
Returns
Number of components from the given format packing. It's value between 0 and 4.

◆ vpiPackingGetParams()

void vpiPackingGetParams ( VPIPacking  packing,
VPIPackingParams params 
)

#include <vpi/DataLayout.h>

Returns channels' information from a format packing.

Parameters
[in]packingThe format packing to be queried.
[out]paramsThe packing parameters.

◆ vpiSwizzleGetChannelCount()

int vpiSwizzleGetChannelCount ( VPISwizzle  swizzle)

#include <vpi/DataLayout.h>

Get the number of channels specified by the given swizzle.

Parameters
[in]swizzleSwizzle to be queried.
Returns
The channel count specified by swizzle.

◆ vpiSwizzleGetChannels()

void vpiSwizzleGetChannels ( VPISwizzle  swizzle,
VPIChannel channels 
)

#include <vpi/DataLayout.h>

Get the swizzle channels.

For example, given swizzle VPI_SWIZZLE_YZWX, it returns VPI_CHANNEL_Y, VPI_CHANNEL_Z, VPI_CHANNEL_W and VPI_CHANNEL_X.

Parameters
[in]swizzleSwizzle to be queried.
[out]channelsOutput channel array with 4 elements.