Functions

This section provides information about the functions in the NvCVImage APIs.

NvCVImage_Alloc

NvCV_Status NvCVImage_Alloc(
  NvCVImage *im
  unsigned width,
  unsigned height,
  NvCVImage_PixelFormat format,
  NvCVImage_ComponentType type,
  unsigned layout,
  unsigned memSpace,
  unsigned alignment
);

Parameters

im [in,out]

Type: NvCVImage *

The image to initialize.

width [in]

Type: unsigned

The width, in pixels, of the image.

height [in]

Type: unsigned

The height, in pixels, of the image.

format [in]

Type: NvCVImage_PixelFormat

The format of the pixels.

type [in]

Type: NvCVImage_ComponentType

The type of the components of the pixels.

layout [in]

Type: unsigned

The organization of the components of the pixels in the image. For more information, see Pixel Organizations.

memSpace [in]

Type: unsigned

The type of memory in which to store the image data buffers. For more information, see Memory Types.

alignment [in]

Type: unsigned

The row byte alignment, which specifies the alignment of the first pixel in each scan line. Set this parameter to 0 or a power of 2.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT when the pixel format is not supported.

• NVCV_ERR_MEMORY when the buffer requires more memory than is available.

Remarks

This function allocates memory for, and initializes, an image. This function assumes that the image data structure has nothing meaningful in it.

This function is called by the C++ NvCVImage constructors. You can call this function from C code to allocate memory for, and to initialize, an empty image.

NvCVImage_ComponentOffsets

void NvCVImage_ComponentOffsets(
  NvCVImage_PixelFormat format,
  int *rOff,
  int *gOff,
  int *bOff,
  int *aOff,
  int *yOff
);

Parameters

format [in]

Type: NvCVImage_PixelFormat

The pixel format whose component offsets are retrieved.

rOff [out]

Type: int *

The location in which to store the offset for the red channel. (Can be NULL.)

gOff [out]

Type: int *

The location in which to store the offset for the green channel. (Can be NULL.)

bOff [out]

Type: int *

The location in which to store the offset for the blue channel. (Can be NULL.)

aOff [out]

Type: int *

The location in which to store the offset for the alpha channel. (Can be NULL.)

yOff [out]

Type: int *

The location in which to store the offset for the luminance channel. (Can be NULL.)

Return Values

Does not return a value.

Remarks

This function gets offsets for the components of a pixel format. These offsets are component, not byte, offsets. For interleaved pixels, a component offset must be multiplied by the componentBytes member of NvCVImage to obtain the byte offset.

NvCVImage_Composite

Parameters

fg [in]

Type: const NvCVImage *

The foreground source, which is an RGB, BGR, RGBA, or BGRA image with u8 or f32 components.

bg [in]

Type: const NvCVImage *

The background source, which is an RGB, BGR, RGBA, or BGRA image with u8 or f32 components.

mat [in]

Type: const NvCVImage *

The matte Y or A image with u8 or f32 components, which indicates where the source image should come through.

This can be the same as the fg image, if it includes an alpha channel.

dst [out]

Type: NvCVImage *

The destination image, which can be the same as the fg (foreground) or bg (background) image, or a totally unrelated image.

Note

If the destination image format contains alpha, the alpha channel is not updated in this implementation.

stream [out]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT if the pixel format is not supported.

Remarks

This function uses the specified matte image to composite a foreground image over a background image. The fg, bg, mat, and dst images must be of the same component type, but the images do not need to be the same pixel format. RGBA or BGRA images might also be used, but the A channel of the destination is not updated.

This function assumes that the source is not pre-multiplied by alpha. If the value is pre-multiplied, use mode 1 of NvCVImage_CompositeRect instead.

NvCVImage_CompositeOverConstant

NvCV_Status NvCVImage_CompositeOverConstant(
  const NvCVImage *src,
  const NvCVImage *mat,
  const void *bgColor,
  NvCVImage *dst,
  CUstream stream
);

Parameters

src [in]

Type: const NvCVImage *

The source RGB, BGR, RGBA, or BGRA image with u8 or f32 components. The pixel colors should not be pre-multiplied by alpha.

mat [in]

Type: const NvCVImage *

The matte Y or A u8 or f32 image, which indicates where the source image should come through.

If this parameter includes an alpha channel, the parameter can be the same as the src image.

bgColor [in]

Type: const void *

A pointer to the background color over which to composite the source image. This color must have the same type (u8 or f32) and format (RGB or BGR) as the destination image and must remain valid until the composition completes.

dst [out]

Type: NvCVImage *

The destination RGB, BGR, RGBA, or BGRA u8 or f32 image. The destination image might be the same image as the source image.

Note

If the destination image format contains alpha, the alpha channel is not updated in this implementation.

stream [out]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT if the pixel format is not supported.

Remarks

This function uses the specified matte image to composite a BGR or RGB image on a constant color field. RGBA and BGRA images might also be used, but the A channel of the destination is not updated.

NvCVImage_CompositeRect

NvCV_Status NvCVImage_CompositeRect(
  const NvCVImage *fg,  const NvCVPoint2i *fgOrg,
  const NvCVImage *bg,  const NvCVPoint2i *bgOrg,
  const NvCVImage *mat, unsigned int mode,
  NvCVImage *dst, const NvCVPoint2i *dstOrg,
  CUstream stream
);

Parameters

fg [in]

Type: const NvCVImage *

The foreground source, which is an RGB, BGR, RGBA, or BGRA image with u8 or f32 components.

fgOrg [in]

Type: const NvCVPoint2i *

Pointer to the foreground image upper-left origin from which to transfer the image:

typedef struct NvCVPoint2i { int x, y; } NvCVPoint2i;

If this value is NULL, the image is transferred from (0,0).

bg [in]

Type: const NvCVImage *

The background source, which is an RGB, BGR, RGBA, or BGRA image with u8 or f32 components.

bgOrg [in]

Type: const NvCVPoint2i *

Pointer to the background image upper-left origin from which to transfer the image:

typedef struct NvCVPoint2i { int x, y; } NvCVPoint2i;

If this value is NULL, the image is transferred from (0,0).

mat [in]

Type: const NvCVImage *

The matte Y or A image with u8 or f32 components, which indicates where the source image should come through. The dimensions of the matte determine the size of the area to be composited.

If this parameter includes an alpha channel, the parameter can be the same as the fg image.

mode [in]

Type: unsigned int

The compositional mode selection options are as follows:

• 0: normal, straight-alpha over composition.

  Over is the most common compositing operation and applies the foreground over the background, as guided by the matte. This is the compositional mode that is used in other functions that do not explicitly specify a mode.

• 1: premultiplied alpha over composition.

  Premultiplied means that the source R, G, and B are premultiplied by alpha; for example, (αR, αG, αB, α). This occurs naturally in a rendering scenario.

Other values return a parameter error.

dst [out]

Type: NvCVImage *

The destination image, which can be the same as the fg (foreground) or bg (background) image, or a totally unrelated image.

Note

If the destination image format contains alpha, the alpha channel is not updated in this implementation.

dstOrg [in]

Type: const NvCVPoint2i *

Pointer to the destination image upper-left origin to which to transfer the image:

typedef struct NvCVPoint2i { int x, y; } NvCVPoint2i;

If this value is NULL, the image is transferred to (0,0).

stream [out]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT if the pixel format is not supported.

• NVCV_ERR_PARAMETER if a mode other than 0 is selected.

Remarks

This function uses the specified matte image to composite a foreground image over a background image. The fg, bg, mat, and dst images must be of the same component type, but the images do not need to be the same pixel format. RGBA or BGRA images might also be used, but the A channel of the destination is not updated.

NvCVImage_Composite(fg, bg, mat, dst, str);

is equal to

NvCVImage_CompositeRect(fg, 0, bg, 0, mat, 0, dst, 0, str);

NvCVImage_Create

NvCV_Status NvCVImage_Create(
  unsigned width,
  unsigned height,
  NvCVImage_PixelFormat format,
  NvCVImage_ComponentType type,
  unsigned layout,
  unsigned memSpace,
  unsigned alignment,
  NvCVImage **out
);

Parameters

width [in]

Type: unsigned

The width, in pixels, of the image.

height [in]

Type: unsigned

The height, in pixels, of the image.

format [in]

Type: NvCVImage_PixelFormat

The format of the pixels.

type [in]

Type: NvCVImage_ComponentType

The type of the components of the pixels.

layout [in]

Type: unsigned

The organization of the components of the pixels in the image. For more information, see Pixel Organizations.

memSpace [in]

Type: unsigned

The type of memory in which to store the image data buffers. For more information, see Memory Types.

alignment [in]

Type: unsigned

The row byte alignment, which specifies the alignment of the first pixel in each scan line.

• 0: Specifies the default alignment, which depends on the type of memory in which the image data buffers are stored:

  • CPU memory: Specifies an alignment of 4 bytes.

  • GPU memory: Specifies the alignment set by cudaMallocPitch.

• 1: Specifies no gap between scan lines. A byte alignment of 1 is required by all GPU buffers that are used by the video effect filters.

• 2 or greater: Specifies any other alignment, such as a cache line size of 16 or 32 bytes. Must be a power of 2.

Note

If the product of width and the pixelBytes member of NvCVImage is a whole-number multiple of alignment, the gap between scan lines is 0 bytes, regardless of the value of alignment.

out [out]

Type: NvCVImage **

Pointer to the location of the newly allocated image. The image descriptor and the pixel buffer are stored so that they are deallocated when NvCVImage_Destroy() is called.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT when the pixel format is not supported.

• NVCV_ERR_MEMORY when the buffer requires more memory than is available.

Remarks

This function creates an image and allocates an image buffer to be provided as input to an effect filter and allocates storage for the new image. This function is a C-style constructor for an instance of the NvCVImage structure (equivalent to new NvCVImage in C++).

NvCVImage_Dealloc

void NvCVImage_Dealloc(
  NvCVImage *im
);

Parameters

im [in,out]

Type: NvCVImage *

Pointer to the image whose image buffer is to be freed.

Return Value

Does not return a value.

Remarks

This function frees the image buffer from the specified NvCVImage structure and sets the contents of the NvCVImage structure to 0.

NvCVImage_DeallocAsync

void NvCVImage_DeallocAsync(
  NvCVImage *im,
  CUstream stream
);

Parameters

im [in,out]

Type: NvCVImage *

Pointer to the image whose image buffer is to be freed.

stream [out]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of the source and destination images is CPU, this parameter is ignored.

Return Value

Does not return a value.

Remarks

This function asynchronously frees the image buffer on the specified CUDA stream and sets the contents of the NvCVImage structure to 0. If there is no buffer, or it is located on the CPU, it is freed immediately.

NvCVImage_Destroy

void NvCVImage_Destroy(
  NvCVImage *im
);

Parameters

im [in,out]

Type: NvCVImage *

Pointer to the image to destroy.

Return Value

Does not return a value.

Remarks

This function destroys an image that was created with the NvCVImage_Create() function and frees resources and memory that were allocated for this image. This function is a C-style destructor for an instance of the NvCVImage structure (equivalent to delete im in C++).

NvCVImage_Init

NvCV_Status NvCVImage_Init(
  NvCVImage *im,
  unsigned width,
  unsigned height,
  unsigned pitch,
  void *pixels,
  NvCVImage_PixelFormat format,
  NvCVImage_ComponentType type,
  unsigned layout,
  unsigned memSpace
);

Parameters

im [in,out]

Type: NvCVImage *

Pointer to the image to initialize.

width [in]

Type: unsigned

The width, in pixels, of the image.

height [in]

Type: unsigned

The height, in pixels, of the image.

pitch [in]

Type: unsigned

The vertical byte stride between pixels.

pixels [in]

Type: void *

Pointer to the pixel buffer to attach to the NvCVImage object.

format [in]

Type: NvCVImage_PixelFormat

The format of the pixels in the image.

type [in]

Type: NvCVImage_ComponentType

The data type used to represent each component of the image.

layout [in]

Type: unsigned

The organization of the components of the pixels in the image. For more information, see Pixel Organizations.

memSpace [in]

Type: unsigned

The type of memory in which to store the image data buffers. For more information, see Memory Types.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT when the pixel format is not supported.

Remarks

This function initializes an NvCVImage structure from a raw buffer pointer. This technique is useful when you wrap an existing pixel buffer in an NvCVImage image descriptor.

This function is called by functions that initialize the data structure of an NvCVImage object, such as the following:

• C++ constructors

• NvCVImage_Alloc()

• NvCVImage_Realloc()

• NvCVImage_InitView()

Call this function to initialize an NvCVImage object instead of directly setting the fields.

NvCVImage_InitFromD3DTexture

NvCV_Status NvCVImage_InitFromD3DTexture(
  NvCVImage *im,
  struct ID3D11Texture2D *tx
);

Parameters

im [in,out]

Type: NvCVImage *

The image to be initialized.

tx [in]

Type: struct ID3D11Texture2D *

The texture to be used for initialization.

Return Value

NVCV_SUCCESS on success.

Remarks

You can initialize an NvCVImage object from a D3D11 texture. The pixelFormat and component types are transferred, and a cudaGraphicsResource is registered. The NvCVImage destructor unregisters the resource.

Note

This is designed to work with NvCVImage_Transfer().

Before you allow the D3D texture to render into the NvCVImage object, you need to call NvCVImage_MapResource() and then NvCVImage_UnmapResource().

NvCVImage_InitView

void NvCVImage_InitView(
  NvCVImage *subImg,
  NvCVImage *fullImg,
  int x,
  int y,
  unsigned width,
  unsigned height
);

Parameters

subImg [in]

Type: NvCVImage *

Pointer to the existing image to initialize with the view.

fullImg [in]

Type: NvCVImage *

Pointer to the existing image from which to take the view of a specified rectangle in the image.

x [in]

Type: int

The x-coordinate of the left edge of the view.

y [in]

Type: int

The y-coordinate of the top edge of the view.

width [in]

Type: unsigned

The width, in pixels, of the view.

height [in]

Type: unsigned

The height, in pixels, of the view.

Return Value

Does not return a value.

Remarks

This function takes a view of the specified rectangle in an image and initializes another existing image descriptor with the view. No memory is allocated because the buffer of the image that is being initialized with the view (specified by the parameter fullImg) is used instead.

Note

This function works only for NVCV_CHUNKY (NVCV_INTERLEAVED) images, not for NVCV_PLANAR or any of the YUV planar or semi-planar image formats. However, if you want this view to select a portion of an image to pass to NvCVImage_Transfer() or NvCVImage_Composite(), you can use the rectangle versions NvCVImage_TransferRect() and NvCVImage_CompositeRect() instead. These versions work for all formats, including planar or YUV formats.

NvCVImage_MapResource

NvCV_Status NvCVImage_MapResource(
  NvCVImage *im,
  struct CUstream_st *stream
);

Parameters

im [in,out]

Type: NvCVImage *

The image to be mapped.

stream [out]

Type: struct CUStream_st *

The stream on which the mapping is to be performed.

Return Value

NVCV_SUCCESS on success.

Remarks

Between rendering by a graphics system and transfer by CUDA, you also need to map the texture resource. This process involves quite a bit of overhead, so its use should be minimized. Every call to NvCVImage_MapResource() should be matched by a subsequent call to NvCVImage_UnmapResource().

One way to create an image-wrapped resource on Windows is to call NvCVImage_InitFromD3DTexture().

NvCVImage_Realloc

NvCV_Status NvCVImage_Realloc(
  NvCVImage *im,
  unsigned width,
  unsigned height,
  NvCVImage_PixelFormat format,
  NvCVImage_ComponentType type,
  unsigned layout,
  unsigned memSpace,
  unsigned alignment
);

Parameters

im [in,out]

Type: NvCVImage *

The image to initialize.

width [in]

Type: unsigned

The width, in pixels, of the image.

height [in]

Type: unsigned

The height, in pixels, of the image.

format [in]

Type: NvCVImage_PixelFormat

The format of the pixels.

type [in]

Type: NvCVImage_ComponentType

The type of the components of the pixels.

layout [in]

Type: unsigned

The organization of the components of the pixels in the image. For more information, see Pixel Organizations.

memSpace [in]

Type: unsigned

The type of memory in which to store the image data buffers. For more information, see Memory Types.

alignment [in]

Type: unsigned

The row byte alignment, which specifies the alignment of the first pixel in each scan line.

• 0: Specifies the default alignment, which depends on the type of memory in which the image data buffers are stored:

  • CPU memory: Specifies an alignment of 4 bytes.

  • GPU memory: Specifies the alignment set by cudaMallocPitch.

• 1: Specifies no gap between scan lines. A byte alignment of 1 is required by all GPU buffers that are used by the video effect filters.

• 2 or greater: Specifies any other alignment, such as a cache line size of 16 or 32 bytes. Must be a power of 2.

Note

If the product of width and the pixelBytes member of NvCVImage is a whole-number multiple of alignment, the gap between scan lines is 0 bytes, regardless of the value of alignment.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT when the pixel format is not supported.

• NVCV_ERR_MEMORY when the buffer requires more memory than is available.

Remarks

This function reallocates memory for, and initializes, an image.

Note

This function assumes that the image is valid.

The function checks the bufferBytes member of NvCVImage to determine whether enough memory is available:

• If enough memory is available, the function reshapes, instead of reallocating, the memory.

• If enough memory is not available, the function frees the memory for the existing buffer and allocates the memory for a new buffer.

NvCVImage_Transfer

NvCV_Status NvCVImage_Transfer(
  const NvCVImage *src,
  NvCVImage *dst,
  float scale,
  CUstream stream,
  NvCVImage *tmp
);

Parameters

src [in]

Type: const NvCVImage *

Pointer to the source image to transfer.

dst [out]

Type: NvCVImage *

Pointer to the destination image to which to transfer the source image.

scale [in]

Type: float

A scale factor to apply when the component type of the source or destination image is floating point. The scale factor scales the value of each component (not the size of the image) and has an effect only when the component type of the source or destination image is floating point.

The following are typical values:

• 1.0f

• 255.0f

• 1.0f/255.0f

This parameter is ignored if neither image has a floating-point component type.

stream [in]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

tmp [in,out]

Type: NvCVImage *

Pointer to a temporary buffer in GPU memory that is required only if the source image is being converted and the memory types of the source and destination images are different. The buffer has the same characteristics as the CPU image but resides on the GPU.

If necessary, the temporary GPU buffer is reshaped to suit the needs of the transfer, such as matching the characteristics of the CPU image. Therefore, for best performance, you can supply an empty image as the temporary GPU buffer. If necessary, NvCVImage_Transfer() allocates an appropriately sized buffer. The same temporary GPU buffer can be used in subsequent calls to NvCVImage_Transfer(), regardless of the shape, format, or component type, because the buffer grows as needed to accommodate the largest memory requirement.

If a temporary GPU buffer is not needed, no buffer is allocated. If a temporary GPU buffer is not required, tmp can be NULL. However, if tmp is NULL and a temporary GPU buffer is required, an ephemeral buffer is allocated with a resultant degradation in performance for image sequences.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_CUDA when a CUDA error occurs.

• NVCV_ERR_PIXELFORMAT when the pixel format of the source or destination image is not supported.

• NVCV_ERR_GENERAL when an unspecified error occurs.

Remarks

This function transfers one image to another image and can perform some conversions on the image. The function uses the GPU to perform the conversions when an image resides on the GPU.

The following table provides details about the supported conversions between pixel formats.

Note

In each conversion type, the RGB can be in any order.

	U8 → U8	U8 → F32	F32 → U8	F32 → F32
Y → Y	✔	✔	✔	✔
Y → A	✔	✔	✔	✔
Y → RGB	✔	✔	✔	✔
Y → RGBA	✔	✔	✔	✔
A → Y	✔	✔	✔	✔
A → A	✔	✔	✔	✔
A → RGB	✔	✔	✔	✔
A → RGBA	✔
RGB → Y	✔	✔
RGB → A	✔	✔
RGB → RGB	✔	✔	✔	✔
RGB → RGBA	✔	✔	✔	✔
RGBA → Y	✔	✔
RGBA → A	✔
RGBA → RGB	✔	✔	✔	✔
RGBA → RGBA	✔	✔	✔	✔
YUV420 → RGB	✔	✔
YUV420 → RGBA	✔	✔
YUV422 → RGB	✔	✔
YUV422 → RGBA	✔	✔
YUV444 → RGB	✔	✔
YUV444 → RGBA	✔	✔
RGB → YUV420	✔		✔
RGBA → YUV420	✔		✔
RGB → YUV422	✔		✔
RGBA → YUV422	✔		✔
RGB → YUV444	✔		✔
RGBA → YUV444	✔		✔

The following kinds of conversions can occur in either direction:

• Conversions between chunky and planar pixel organizations.

• Conversions between CPU and GPU memory types.

• Conversions between different orderings of components, such as BGR → RGB.

Conversions from RGB (or BGR) to RGBA (or BGRA) set the alpha channel to opaque (255 for u8 or 1.0 for f32).

At initialization, for chunky and planar u8 images, we recommend that you set the alpha channel with one of the following:

[cuda]memset(im.pixels, -1, im.pitch * im.height)
[cuda]memset(im.pixels, -1, im.pitch * im.height*im.numComponents)

Other than pitch, if no conversion is necessary, all pixel format transfers are implemented with cudaMemcpy2DAsync().

Another restriction in YUV → YUV transfers is that the formats, layouts, and colorspaces must be the same in src and dst.

YUV420, YUV422, and YUV444 sources have several variants. You must set the colorspace manually before the transfer. For more information, see YUV Color Spaces.

There are also RGBf16 → RGBf32 and RGBf32 → RGBf16 transfers.

CPU → CPU transfers are synchronous. When the src and dst formats are the same, all formats are accommodated on CPU and GPU, and you can use this function as a replacement for cudaMemcpy2DAsync() (which it uses). If src and dst have different sizes, the transfer still occurs but is clipped to the smaller size.

If both images reside on the CPU, the transfer occurs synchronously. However, if either image resides on the GPU, the transfer might occur asynchronously. A chain of asynchronous calls on the same CUDA stream is automatically sequenced as expected; to synchronize, you can call cudaStreamSynchronize().

Transfers to and from CUDA arrays have limited support. These transfers are typically accessed by mapping DirectX (and eventually OpenGL and Vulkan) textures to CUDA. (See NvCVImage_MapResource(), NvCVImage_UnmapResource(), and NvCVImage_InitFromD3DTexture().) We provide NvCVImage wrappers to map and unmap these textures. There is full capability to copy to and from textures for all basic texture types: chunky ({RGBA, YA, Y}{u8, u16, s16, f16, u32, s32, f32}), Au8, and Windows BGRAu8. We also implemented several conversions from RGBAu8 textures to {RGBA, BGRA, RGB, BGR}{u8, f32} CUDA buffers.

NvCVImage_TransferFromYUV

NvCV_Status NvCVImage_TransferFromYUV(
  const void *y,                int yPixBytes,  int yPitch,
  const void *u, const void *v, int uvPixBytes, int uvPitch,
  NvCVImage_PixelFormat yuvFormat, NvCVImage_ComponentType yuvType,
  unsigned yuvColorSpace, unsigned yuvMemSpace,
  NvCVImage *dst, const NvCVRect2i *dstRect,
  float scale, struct CUstream_st *stream, NvCVImage *tmp
);

Parameters

y [in]

Type: const void *

Pointer to pixel(0,0) of the luminance channel.

yPixBytes [in]

Type: int

The byte stride between y pixels horizontally.

yPitch [in]

Type: int

The byte stride between y pixels vertically.

u [in]

Type: const void *

Pointer to pixel(0,0) of the u (Cb) chrominance channel.

v [in]

Type: const void *

Pointer to pixel(0,0) of the v (Cr) chrominance channel.

uvPixBytes [in]

Type: int

The byte stride between u or v pixels horizontally.

uvPitch [in]

Type: int

The byte stride between u or v pixels vertically.

yuvColorSpace [in]

Type: unsigned int

The YUV colorspace, which specifies range, chromaticities, and chrominance phase.

yuvMemSpace [in]

Type: unsigned int

The memory space in which the YUV buffer resides (CPU, CUDA, and so on).

dst [out]

Type: NvCVImage *

Pointer to the destination image to which to transfer the source image.

dstRect [in]

Type: const NvCVRect2i *

Pointer to the destination image rectangle to which to transfer the image.

typedef struct NvCVRect2i { int x, y, width, height; } NvCVRect2i;

If this value is NULL, the entire destination image is transferred.

scale [in]

Type: float

A scale factor to apply when the component type of the source or destination image is floating point. The scale has an effect only when the component type of the source or destination image is floating point.

The following are typical values:

• 1.0f

• 255.0f

• 1.0f/255.0f

This parameter is ignored if neither image has a floating-point component type.

stream [in]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

tmp [in,out]

Type: NvCVImage *

Pointer to a temporary buffer in GPU memory that is required only if the source image is being converted and the memory types of the source and destination images are different. The buffer has the same characteristics as the CPU image but resides on the GPU.

If necessary, the temporary GPU buffer is reshaped to suit the needs of the transfer, such as matching the characteristics of the CPU image. Therefore, for best performance, you can supply an empty image as the temporary GPU buffer. If necessary, NvCVImage_Transfer() allocates an appropriately sized buffer. The same temporary GPU buffer can be used in subsequent calls to NvCVImage_Transfer(), regardless of the shape, format, or component type, because the buffer grows as needed to accommodate the largest memory requirement.

If a temporary GPU buffer is not needed, no buffer is allocated. If a temporary GPU buffer is not required, tmp can be NULL. However, if tmp is NULL and a temporary GPU buffer is required, an ephemeral buffer is allocated with a resultant degradation in performance for image sequences.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_CUDA when a CUDA error occurs.

• NVCV_ERR_PIXELFORMAT when the pixel format of the source or destination image is not supported.

• NVCV_ERR_GENERAL when an unspecified error occurs.

Remarks

This function is like NvCVImage_TransferRect(), which can also copy from YUV images. The difference is that NvCVImage_TransferRect() works with images that have a structure, as described in the layout (or planar) parameter, and NvCVImage_TransferFromYUV() works with images that have no structure that is represented in the taxonomy of the layout parameter. Because the structure is not known, NvCVImage_TransferFromYUV() is also slower than NvCVImage_TransferRect() when transferring from CPU to GPU.

NvCVImage_TransferRect

NvCV_Status NvCVImage_TransferRect(
  const NvCVImage *src,
  const NvCVRect2i *srcRect,
  NvCVImage *dst,
  const NvCVPoint2i *dstPt,
  float scale,
  CUstream stream,
  NvCVImage *tmp
);

Parameters

src [in]

Type: const NvCVImage *

Pointer to the source image to transfer.

srcRect [in]

Type: const NvCVRect2i *

Pointer to the source image rectangle to transfer.

typedef struct NvCVRect2i { int x, y, width, height; } NvCVRect2i;

If this value is NULL, the entire source image rectangle is transferred.

dst [out]

Type: NvCVImage *

Pointer to the destination image to which to transfer the source image.

dstPt [in]

Type: const NvCVPoint2i *

Pointer to the destination image location to which to transfer the image.

typedef struct NvCVPoint2i { int x, y; } NvCVPoint2i;

If this value is NULL, the image is transferred to (0,0).

scale [in]

Type: float

A scale factor to apply when the component type of the source or destination image is floating point. The scale has an effect only when the component type of the source or destination image is floating point.

The following are typical values:

• 1.0f

• 255.0f

• 1.0f/255.0f

This parameter is ignored if neither image has a floating-point component type.

stream [in]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

tmp [in,out]

Type: NvCVImage *

Pointer to a temporary buffer in GPU memory that is required only if the source image is being converted and the memory types of the source and destination images are different. The buffer has the same characteristics as the CPU image but resides on the GPU.

If necessary, the temporary GPU buffer is reshaped to suit the needs of the transfer, such as matching the characteristics of the CPU image. Therefore, for best performance, you can supply an empty image as the temporary GPU buffer. If necessary, NvCVImage_Transfer() allocates an appropriately sized buffer. The same temporary GPU buffer can be used in subsequent calls to NvCVImage_Transfer(), regardless of the shape, format, or component type, because the buffer grows as needed to accommodate the largest memory requirement.

If a temporary GPU buffer is not needed, no buffer is allocated. If a temporary GPU buffer is not required, tmp can be NULL. However, if tmp is NULL and a temporary GPU buffer is required, an ephemeral buffer is allocated with a resultant degradation in performance for image sequences.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_CUDA when a CUDA error occurs.

• NVCV_ERR_PIXELFORMAT when the pixel format of the source or destination image is not supported.

• NVCV_ERR_GENERAL when an unspecified error occurs.

Remarks

This function is like NvCVImage_Transfer() because they share the same code. A rectangle can be copied by combining NvCVImage_InitView() with NvCVImage_Transfer(), but this works only for chunky images.

NvCVImage_TransferRect() works on chunky, planar, and semi-planar image layouts with no difference in performance.

NvCVImage_Transfer(src, dst, scale, stream, tmp) is equivalent to NvCVImage_TransferRect(src, 0, dst, 0, scale, stream, tmp).

If you are not careful when you copy YUV rectangles, unexpected clipping occurs:

• YUV420 must have even x, y, width, and height.

• YUV422 must have even x and width.

NvCVImage_TransferToYUV

NvCV_Status NvCVImage_TransferToYUV(
  const NvCVImage *src,            const NvCVRect2i *srcRect,
  const void *y,                   int yPixBytes,  int yPitch,
  const void *u, const void *v,    int uvPixBytes, int uvPitch,
  NvCVImage_PixelFormat yuvFormat, NvCVImage_ComponentType yuvType,
  unsigned yuvColorSpace,          unsigned yuvMemSpace,
  float scale,
  CUstream stream,
  NvCVImage *tmp
);

Parameters

src [in]

Type: const NvCVImage *

Pointer to the source image to transfer.

srcRect [in]

Type: const NvCVRect2i *

Pointer to the source image rectangle to transfer.

typedef struct NvCVRect2i { int x, y, width, height; } NvCVRect2i;

If this value is NULL, the entire source image rectangle is transferred.

y [out]

Type: NvCVImage *

Pointer to pixel(0,0) of the luminance channel.

yPixBytes [in]

Type: int

The byte stride between y pixels horizontally.

yPitch [in]

Type: int

The byte stride between y pixels vertically.

u [out]

Type: NvCVImage *

Pointer to pixel(0,0) of the u (Cb) chrominance channel.

v [out]

Type: NvCVImage *

Pointer to pixel(0,0) of the v (Cr) chrominance channel.

uvPixBytes [in]

Type: int

The byte stride between u or v pixels horizontally.

uvPitch [in]

Type: int

The byte stride between u or v pixels vertically.

yuvColorSpace [in]

Type: unsigned int

The YUV colorspace, which specifies range, chromaticities, and chrominance phase.

yuvMemSpace [in]

Type: unsigned int

The memory space where the pixel buffers reside.

scale [in]

Type: float

A scale factor to apply when the component type of the source or destination image is floating point. The scale has an effect only when the component type of the source or destination image is floating point.

The following are typical values:

• 1.0f

• 255.0f

• 1.0f/255.0f

This parameter is ignored if neither image has a floating-point component type.

stream [in]

Type: CUstream

The CUDA stream on which to transfer the image. If the memory type of both the source and destination images is CPU, this parameter is ignored.

tmp [in,out]

Type: NvCVImage *

Pointer to a temporary buffer in GPU memory that is required only if the source image is being converted and the memory types of the source and destination images are different. The buffer has the same characteristics as the CPU image but resides on the GPU.

If necessary, the temporary GPU buffer is reshaped to suit the needs of the transfer, such as matching the characteristics of the CPU image. Therefore, for best performance, you can supply an empty image as the temporary GPU buffer. If necessary, NvCVImage_Transfer() allocates an appropriately sized buffer. The same temporary GPU buffer can be used in subsequent calls to NvCVImage_Transfer(), regardless of the shape, format, or component type, because the buffer grows as needed to accommodate the largest memory requirement.

If a temporary GPU buffer is not needed, no buffer is allocated. If a temporary GPU buffer is not required, tmp can be NULL. However, if tmp is NULL and a temporary GPU buffer is required, an ephemeral buffer is allocated with a resultant degradation in performance for image sequences.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_CUDA when a CUDA error occurs.

• NVCV_ERR_PIXELFORMAT when the pixel format of the source or destination image is not supported.

• NVCV_ERR_GENERAL when an unspecified error occurs.

Remarks

This function is like NvCVImage_TransferRect(), which can also copy to YUV images. The difference is that NvCVImage_TransferRect() works with images that have a structure, as described in the layout (or planar) parameter, and NvCVImage_TransferToYUV() works with images that have no structure that is represented in the taxonomy of the layout parameter.

NvCVImage_UnmapResource

NvCV_Status NvCVImage_UnmapResource(
  NvCVImage *im,
  struct CUstream_st *stream
);

Parameters

im [in,out]

Type: NvCVImage *

The image to be unmapped.

stream [out]

Type: struct CUStream_st *

The stream on which the unmapping is to be performed.

Return Value

NVCV_SUCCESS on success.

Remarks

Between rendering by a graphics system and transfer by CUDA, you also need to map the texture resource. This process involves quite a bit of overhead, so its use should be minimized. Every call to NvCVImage_MapResource() should be matched by a subsequent call to NvCVImage_UnmapResource().

One way to create an image-wrapped resource on Windows is to call NvCVImage_InitFromD3DTexture().

C++ Helper Functions for Sample Applications

The helper functions in this section are provided in the nvCVOpenCV.h file to help NvCVImage interface with the OpenCV image representation, such as cv::Mat.

CVWrapperForNvCVImage

void CVWrapperForNvCVImage(
  const NvCVImage *vfxIm,
  cv::Mat *cvIm
);

Parameters

vfxIm [in]

Type: const NvCVImage *

Pointer to an allocated NvCVImage object.

cvIm [out]

Type: cv::Mat *

Pointer to an empty OpenCV image, appropriately initialized to access the buffer of the NvCVImage object. An empty OpenCV image is created by the default cv::Mat constructor.

Return Value

Does not return a value.

Remarks

This function creates an OpenCV image wrapper for an NvCVImage object.

NVWrapperForCVMat

void NVWrapperForCVMat(
  const cv::Mat *cvIm,
  NvCVImage *vfxIm
);

Parameters

cvIm [in]

Type: const cv::Mat *

Pointer to an allocated OpenCV image.

vfxIm [out]

Type: NvCVImage *

Pointer to an empty NvCVImage object, appropriately initialized by this function to access the buffer of the OpenCV image. An empty NvCVImage object is created by the default (no-argument) NvCVImage() constructor.

Return Value

Does not return a value.

Remarks

This function creates an NvCVImage object wrapper for an OpenCV image.

Image Functions for C++ Only

The image functions are defined in the nvCVImage.h header file. The image API provides constructors, a destructor for C++, and some additional functions that are accessible only to C++.

NvCVImage Default Constructor

The default constructor creates an empty image with no buffer.

NvCVImage();

NvCVImage Allocation Constructor

The allocation constructor creates an image to which memory has been allocated and that has been initialized.

NvCVImage(
  unsigned width,
  unsigned height,
  NvCVImage_PixelFormat format,
  NvCVImage_ComponentType type,
  unsigned layout,
  unsigned memSpace,
  unsigned alignment
);

width [in]

Type: unsigned

The width, in pixels, of the image.

height [in]

Type: unsigned

The height, in pixels, of the image.

format [in]

Type: NvCVImage_PixelFormat

The format of the pixels.

type [in]

Type: NvCVImage_ComponentType

The type of the components of the pixels.

layout [in]

Type: unsigned

The organization of the components of the pixels in the image. For more information, see Pixel Organizations.

memSpace [in]

Type: unsigned

The type of memory in which the image data buffers are to be stored. For more information, see Memory Types.

alignment [in]

Type: unsigned

The row byte alignment, which specifies the alignment of the first pixel in each scan line.

• 0: Specifies the default alignment, which depends on the type of memory in which the image data buffers are stored:

  • CPU memory: Specifies an alignment of 4 bytes.

  • GPU memory: Specifies the alignment set by cudaMallocPitch.

• 1: Specifies no gap between scan lines. A byte alignment of 1 is required by all GPU buffers that are used by the video effect filters.

• 2 or greater: Specifies any other alignment, such as a cache line size of 16 or 32 bytes. Must be a power of 2.

Note

If the product of width and the pixelBytes member of NvCVImage is a whole-number multiple of alignment, the gap between scan lines is 0 bytes, regardless of the value of alignment.

NvCVImage Subimage Constructor

The subimage constructor creates an image that is initialized with a view of the specified rectangle in another image. No additional memory is allocated.

NvCVImage(
  NvCVImage *fullImg,
  int x,
  int y,
  unsigned width,
  unsigned height
);

fullImg [in]

Type: NvCVImage *

Pointer to the existing image from which to take the view of a specified rectangle in the image.

x [in]

Type: int

The x coordinate of the left edge of the view.

y [in]

Type: int

The y coordinate of the top edge of the view.

width [in]

Type: unsigned

The width, in pixels, of the view.

height [in]

Type: unsigned

The height, in pixels, of the view.

NvCVImage Destructor

~NvCVImage();

copyFrom Function

The following version copies an entire image to another image and is functionally identical to NvCVImage_Transfer(src, this, 1.0f, 0, NULL):

NvCV_Status copyFrom(
  const NvCVImage *src
);

The following version copies the specified rectangle in the source image to the destination image:

NvCV_Status copyFrom(
  const NvCVImage *src,
  int srcX,
  int srcY,
  int dstX,
  int dstY,
  unsigned width,
  unsigned height
);

Parameters

src [in]

Type: const NvCVImage *

Pointer to the existing source image from which to copy the specified rectangle.

srcX [in]

Type: int

The x coordinate in the source image of the left edge of the rectangle.

srcY [in]

Type: int

The y coordinate in the source image of the top edge of the rectangle.

dstX [in]

Type: int

The x coordinate in the destination image of the left edge of the copied rectangle.

dstY [in]

Type: int

The y coordinate in the destination image of the top edge of the copied rectangle.

width [in]

Type: unsigned

The width, in pixels, of the rectangle to copy.

height [in]

Type: unsigned

The height, in pixels, of the rectangle to copy.

Return Values

• NVCV_SUCCESS on success.

• NVCV_ERR_PIXELFORMAT when the pixel format is not supported.

• NVCV_ERR_MISMATCH when the formats of the source and destination images are different.

• NVCV_ERR_CUDA if a CUDA error occurs.

Remarks

This overloaded function copies an entire image to another image or copies the specified rectangle in an image to another image.

This function can copy image data buffers that are stored in various memory types as follows:

• From CPU to CPU

• From CPU to GPU

• From GPU to GPU

• From GPU to CPU

Note

For additional use cases, use the NvCVImage_Transfer() function.