Data Layout

group NVCV_C_CORE_DATALAYOUT

Defines

NVCV_MAX_CHANNEL_COUNT

Maximum channel count

NVCV_MAX_EXTRA_CHANNEL_COUNT
NVCV_MAX_SWIZZLE_COUNT

Enums

enum NVCVPacking

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:

In big-endian architectures:

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

In little-endian architectures:

In big-endian architectures:

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.

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.

Note

Also note equivalences such as the following:

Note

In little-endian: X8_Y8_Z8_W8 = W8Z8Y8X8.

Note

In big-endian: X8_Y8_Z8_W8 = X8Y8Z8W8.

Values:

enumerator NVCV_PACKING_0

No channels.

enumerator NVCV_PACKING_X1

One 1-bit channel.

enumerator NVCV_PACKING_X2

One 2-bit channel.

enumerator NVCV_PACKING_X4

One 4-bit channel.

enumerator NVCV_PACKING_X8

One 8-bit channel.

enumerator NVCV_PACKING_b4X4

One LSB 4-bit channel in a 8-bit word

enumerator NVCV_PACKING_X4b4

One MSB 4-bit channel in a 8-bit word

enumerator NVCV_PACKING_X4Y4

Two 4-bit channels in one 8-bit word.

enumerator NVCV_PACKING_X3Y3Z2

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

enumerator NVCV_PACKING_X16

One 16-bit channel.

enumerator NVCV_PACKING_b6X10

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

enumerator NVCV_PACKING_X10b6

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

enumerator NVCV_PACKING_b4X12

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

enumerator NVCV_PACKING_X12b4

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

enumerator NVCV_PACKING_b2X14

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

enumerator NVCV_PACKING_X14b2

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

enumerator NVCV_PACKING_X8_Y8

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

enumerator NVCV_PACKING_X5Y5Z6

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

enumerator NVCV_PACKING_X5Y6Z5

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

enumerator NVCV_PACKING_X6Y5Z5

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

enumerator NVCV_PACKING_b4X4Y4Z4

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

enumerator NVCV_PACKING_b1X5Y5Z5

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

enumerator NVCV_PACKING_X5Y5b1Z5

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

enumerator NVCV_PACKING_X1Y5Z5W5

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

enumerator NVCV_PACKING_X4Y4Z4W4

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

enumerator NVCV_PACKING_X5Y1Z5W5

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

enumerator NVCV_PACKING_X5Y5Z1W5

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

enumerator NVCV_PACKING_X5Y5Z5W1

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

enumerator NVCV_PACKING_X8_Y8__X8_Z8

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

enumerator NVCV_PACKING_Y8_X8__Z8_X8

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

enumerator NVCV_PACKING_X24

One 24-bit channel.

enumerator NVCV_PACKING_X8_Y8_Z8

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

enumerator NVCV_PACKING_X32

One 32-bit channel.

enumerator NVCV_PACKING_b12X20

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

enumerator NVCV_PACKING_X20b12

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

enumerator NVCV_PACKING_X24b8

One MSB 24-bit channel in one 32-bit word.

enumerator NVCV_PACKING_b8X24

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

enumerator NVCV_PACKING_X16_Y16

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

enumerator NVCV_PACKING_X10b6_Y10b6

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

enumerator NVCV_PACKING_X12b4_Y12b4

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

enumerator NVCV_PACKING_X10Y11Z11

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

enumerator NVCV_PACKING_X11Y11Z10

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

enumerator NVCV_PACKING_b2X10Y10Z10

Three LSB 10-bit channels in one 32-bit word.

enumerator NVCV_PACKING_X10Y10Z10b2

Three MSB 10-bit channels in one 32-bit word.

enumerator NVCV_PACKING_X8_Y8_Z8_W8

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

enumerator NVCV_PACKING_X2Y10Z10W10

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

enumerator NVCV_PACKING_X10Y10Z10W2

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

enumerator NVCV_PACKING_X48

One 48-bit channel.

enumerator NVCV_PACKING_X16_Y16_Z16

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

enumerator NVCV_PACKING_X64

One 64-bit channel.

enumerator NVCV_PACKING_X32_Y32

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

enumerator NVCV_PACKING_X32_Y24b8

Two channels: 32-bit in a 32-bit word, 24-bit MSB in a 32-bit word

enumerator NVCV_PACKING_X16_Y16_Z16_W16

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

enumerator NVCV_PACKING_X96

One 96-bit channel.

enumerator NVCV_PACKING_X32_Y32_Z32

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

enumerator NVCV_PACKING_X128

One 128-bit channel.

enumerator NVCV_PACKING_X64_Y64

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

enumerator NVCV_PACKING_X32_Y32_Z32_W32

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

enumerator NVCV_PACKING_X192

One 192-bit channel.

enumerator NVCV_PACKING_X64_Y64_Z64

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

enumerator NVCV_PACKING_X256

One 256-bit channel.

enumerator NVCV_PACKING_X128_Y128

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

enumerator NVCV_PACKING_X64_Y64_Z64_W64

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

enum NVCVDataKind

Defines the channel data type.

Values:

enumerator NVCV_DATA_KIND_UNSPECIFIED

Unspecified data kind.

enumerator NVCV_DATA_KIND_UNSIGNED

Channels are unsigned integer values.

enumerator NVCV_DATA_KIND_SIGNED

Channels are signed integer values.

enumerator NVCV_DATA_KIND_FLOAT

Channels are floating point values.

enumerator NVCV_DATA_KIND_COMPLEX

Channels are complex values.

enum NVCVMemLayout

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.

Values:

enumerator NVCV_MEM_LAYOUT_PITCH_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK1_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK2_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK4_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK8_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK16_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK32_LINEAR

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

enumerator NVCV_MEM_LAYOUT_BLOCK_LINEAR

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

enumerator NVCV_MEM_LAYOUT_PL

Useful aliases.

enumerator NVCV_MEM_LAYOUT_BL
enum NVCVChannel

Defines the format channel names. The channels are color model-agnostic.

Values:

enumerator NVCV_CHANNEL_0

Don’t select a channel.

enumerator NVCV_CHANNEL_X

Selects the first channel of the color model.

enumerator NVCV_CHANNEL_Y

Selects the second channel of the color model.

enumerator NVCV_CHANNEL_Z

Selects the third channel of the color model.

enumerator NVCV_CHANNEL_W

Selects the fourth channel of the color model.

enumerator NVCV_CHANNEL_1

Sets the corresponding channel to have its maximum value.

enum NVCVAlphaType

Defines the kind of alpha channel data present.

Values:

enumerator NVCV_ALPHA_ASSOCIATED

Associated alpha type

enumerator NVCV_ALPHA_UNASSOCIATED

Unassociated alpha type

enum NVCVExtraChannel

Defines the different kinds of extra channels supported.

Values:

enumerator NVCV_EXTRA_CHANNEL_U

Unspecified Channel.

enumerator NVCV_EXTRA_CHANNEL_D

Depth data.

enumerator NVCV_EXTRA_CHANNEL_POS3D

3D Position data.

enum NVCVSwizzle

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.

Values:

enumerator NVCV_SWIZZLE_0000

Swizzle operation.

enumerator NVCV_SWIZZLE_X000
enumerator NVCV_SWIZZLE_XY00
enumerator NVCV_SWIZZLE_XYZ0
enumerator NVCV_SWIZZLE_XYZW
enumerator NVCV_SWIZZLE_1000
enumerator NVCV_SWIZZLE_0001
enumerator NVCV_SWIZZLE_ZYXW
enumerator NVCV_SWIZZLE_WXYZ
enumerator NVCV_SWIZZLE_WZYX
enumerator NVCV_SWIZZLE_YZWX
enumerator NVCV_SWIZZLE_XYZ1
enumerator NVCV_SWIZZLE_YZW1
enumerator NVCV_SWIZZLE_XXX1
enumerator NVCV_SWIZZLE_XZY1
enumerator NVCV_SWIZZLE_ZYX1
enumerator NVCV_SWIZZLE_ZYX0
enumerator NVCV_SWIZZLE_WZY1
enumerator NVCV_SWIZZLE_0X00
enumerator NVCV_SWIZZLE_00X0
enumerator NVCV_SWIZZLE_000X
enumerator NVCV_SWIZZLE_Y000
enumerator NVCV_SWIZZLE_0Y00
enumerator NVCV_SWIZZLE_00Y0
enumerator NVCV_SWIZZLE_000Y
enumerator NVCV_SWIZZLE_0XY0
enumerator NVCV_SWIZZLE_XXXY
enumerator NVCV_SWIZZLE_YYYX
enumerator NVCV_SWIZZLE_0YX0
enumerator NVCV_SWIZZLE_X00Y
enumerator NVCV_SWIZZLE_Y00X
enumerator NVCV_SWIZZLE_X001
enumerator NVCV_SWIZZLE_XY01
enumerator NVCV_SWIZZLE_0XZ0
enumerator NVCV_SWIZZLE_0ZX0
enumerator NVCV_SWIZZLE_XZY0
enumerator NVCV_SWIZZLE_YZX1
enumerator NVCV_SWIZZLE_ZYW1
enumerator NVCV_SWIZZLE_0YX1
enumerator NVCV_SWIZZLE_XYXZ
enumerator NVCV_SWIZZLE_YXZX
enumerator NVCV_SWIZZLE_XZ00
enumerator NVCV_SWIZZLE_WYXZ
enumerator NVCV_SWIZZLE_YX00
enumerator NVCV_SWIZZLE_YX01
enumerator NVCV_SWIZZLE_00YX
enumerator NVCV_SWIZZLE_00XY
enumerator NVCV_SWIZZLE_0XY1
enumerator NVCV_SWIZZLE_0X01
enumerator NVCV_SWIZZLE_YZXW
enumerator NVCV_SWIZZLE_YW00
enumerator NVCV_SWIZZLE_XYW0
enumerator NVCV_SWIZZLE_YZW0
enumerator NVCV_SWIZZLE_YZ00
enumerator NVCV_SWIZZLE_00X1
enumerator NVCV_SWIZZLE_0ZXY
enumerator NVCV_SWIZZLE_UNSUPPORTED
enum NVCVByteOrder

Byte/bit order of a NVCVPacking value in a word.

Values:

enumerator NVCV_ORDER_LSB

Least significant byte/bit has higher memory address.

enumerator NVCV_ORDER_MSB

Most significant byte/bit has lower memory address.

Functions

NVCV_PUBLIC NVCVStatus nvcvMakeSwizzle (NVCVSwizzle *outSwizzle, NVCVChannel x, NVCVChannel y, NVCVChannel z, NVCVChannel w)

Creates a user-defined NVCVSwizzle operation. This is similar to NVCV_MAKE_SWIZZLE, but accepts the swizzle channels as runtime variables.

Parameters:
  • outSwizzle[out] Swizzle operation as defined by the given channel order.

  • x[in] Channel that will correspond to the first component.

  • y[in] Channel that will correspond to the second component.

  • z[in] Channel that will correspond to the third component.

  • w[in] Channel that will correspond to the fourth component.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvSwizzleGetChannels (NVCVSwizzle swizzle, NVCVChannel *channels)

Get the swizzle channels.

For example, given swizzle NVCV_SWIZZLE_YZWX, it returns NVCV_CHANNEL_Y, NVCV_CHANNEL_Z, NVCV_CHANNEL_W and NVCV_CHANNEL_X.

Parameters:
  • swizzle[in] Swizzle to be queried.

  • channels[out] Output channel array with 4 elements.

    • It cannot be NULL.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvSwizzleGetNumChannels (NVCVSwizzle swizzle, int32_t *outNumChannels)

Get the number of channels specified by the given swizzle.

Only the following count as channels:

Parameters:
  • swizzle[in] Swizzle to be queried.

  • outNumChannels[out] The channel count specified by swizzle.

    • It cannot be NULL.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvMakePacking (NVCVPacking *outPacking, const NVCVPackingParams *params)

Returns a pre-defined NVCVPacking given its params.

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

Parameters:
  • outPacking[out] The packing enum corresponding to params.

    • It cannot be NULL.

  • params[in] Packing parameters. If NVCVPackingParams::swizzle is set to NVCV_SWIZZLE_0000 the swizzle will be inferred from NVCVPackingParams::bits. It’ll return the packing with the largest alignment that is smaller or equal the requested alignment. If requested alignment is 0, it’ll return the packing with smallest alignment.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvPackingGetParams (NVCVPacking packing, NVCVPackingParams *outParams)

Returns channels’ information from a format packing.

Parameters:
  • packing[in] The format packing to be queried.

  • outParams[out] The packing parameters.

    • It cannot be NULL.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvPackingGetNumComponents (NVCVPacking packing, int32_t *outNumComponents)

Returns the number of components defined by the given packing.

Parameters:
  • packing[in] The format packing to be queried.

  • outNumComponents[out] Number of components from the given format packing. It’s value between 0 and 4.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvPackingGetBitsPerComponent (NVCVPacking packing, int32_t *outBits)

Returns the number of bits per packing component.

Parameters:
  • packing[in] The format packing to be queried.

  • bits[out] Pointer to an int32_t array with 4 elements where output will be stored. Passing NULL is allowed, to which the function simply does nothing.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvPackingGetBitsPerPixel (NVCVPacking packing, int32_t *outBPP)

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

Parameters:
  • packing[in] The format packing to be queried.

  • outBPP[out] Total number of bits per pixel of the given packing. It’s the sum of number of bits occupied by all packing channels.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvPackingGetAlignment (NVCVPacking packing, int32_t *outAlignment)

Get the required address alignment for the packing.

The returned alignment is guaranteed to be a power-of-two.

Parameters:
  • type[in] Packing to be queried.

  • outAlignment[out] Pointer to an int32_t where the required alignment is to be stored.

    • Cannot be NULL.

Return values:
  • NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.

  • NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC const char * nvcvPackingGetName (NVCVPacking fmt)

Returns a string representation of a packing.

Parameters:

packing[in] Packing whose name is to be returned.

Returns:

The string representation of the packing. Returned pointer must not be freed.

NVCV_PUBLIC const char * nvcvDataKindGetName (NVCVDataKind dtype)

Returns a string representation of a data type.

Parameters:

dtype[in] Data type whose name is to be returned.

Returns:

The string representation of the data type. Returned pointer must not be freed.

NVCV_PUBLIC const char * nvcvMemLayoutGetName (NVCVMemLayout memlayout)

Returns a string representation of a memory layout.

Parameters:

memlayout[in] Memory layout whose name is to be returned.

Returns:

The string representation of the memory layout. Returned pointer must not be freed.

NVCV_PUBLIC const char * nvcvChannelGetName (NVCVChannel channel)

Returns a string representation of a channel.

Parameters:

channel[in] Channel whose name is to be returned.

Returns:

The string representation of the channel. Returned pointer must not be freed.

NVCV_PUBLIC const char * nvcvSwizzleGetName (NVCVSwizzle swizzle)

Returns a string representation of a swizzle.

Parameters:

swizzle[in] Swizzle whose name is to be returned.

Returns:

The string representation of the swizzle. Returned string is valid until next call of this function from the same calling thread. Returned pointer must not be freed.

NVCV_PUBLIC const char * nvcvByteOrderGetName (NVCVByteOrder byteOrder)

Returns a string representation of a byte order.

Parameters:

byteOrder[in] Byte order whose name is to be returned.

Returns:

The string representation of the byte order. Returned string is valid until next call of this function from the same calling thread. Returned pointer must not be freed.

struct NVCVExtraChannelInfo
#include <DataLayout.h>

Data structure for passing additional channel information.

struct NVCVPackingParams
#include <DataLayout.h>

Defines the parameters encoded in a NVCVPacking.