Convert To

group Convert To

Functions

NVCVStatus cvcudaConvertToCreate(NVCVOperatorHandle *handle)

Constructs and an instance of the ConvertTo operator.

Parameters:

handle – [out] Where the image instance handle will be written to.

  • Must not be NULL.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Handle is null.

  • NVCV_ERROR_OUT_OF_MEMORY – Not enough memory to create the operator.

  • NVCV_SUCCESS – Operation executed successfully.

NVCVStatus cvcudaConvertToSubmit(NVCVOperatorHandle handle, cudaStream_t stream, NVCVTensorHandle in, NVCVTensorHandle out, const double alpha, const double beta, NVCVRoundMode roundMode)

Executes the ConvertTo operation on the given cuda stream. This operation does not wait for completion.

outputs(x,y) = saturate_cast<out_type>(α * inputs(x, y) + β)

When the output type is integral, roundMode selects how the floating-point result is rounded before the output is stored. The mode has no effect when the output type is floating-point.

Saturating modes (clamp to destination range):

  • NVCV_ROUND_NEAREST — round to nearest, ties to even (default and historical behavior).

  • NVCV_ROUND_TRUNCATE — truncate toward zero.

Wrapping modes (reduce modulo destination range instead of saturating):

  • NVCV_ROUND_NEAREST_WRAP — round to nearest (ties to even), then wrap.

  • NVCV_ROUND_TRUNCATE_WRAP — truncate toward zero, then wrap.

Wrapping is supported for 8- and 16-bit integer destinations only. 32-bit integer destinations are rejected with NVCV_ERROR_INVALID_ARGUMENT because the float32 working arithmetic (used for all non-F64 type pairs) cannot represent the 2^31 wrap period without quantization error — the same input perturbation that is harmless under saturation produces a full-range output error under modular reduction.

For unsigned destinations, negative intermediate values map to zero rather than wrapping (unsigned asymmetry). For 8- and 16-bit destinations, wrapping is exact when the pre-wrap intermediate magnitude is below 2^24 (the float32 integer precision limit); beyond that, results may be off by the local float32 ULP.

Limitations:

Input: Data Layout: [kNHWC, kHWC, kNCHW, kCHW] Channels: [1-4]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

No

32bit Signed

Yes

16bit Float

Yes

32bit Float

Yes

64bit Float

Yes

Output: Data Layout: [kNHWC, kHWC, kNCHW, kCHW] Channels: [1-4]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

No

32bit Signed

Yes

16bit Float

Yes

32bit Float

Yes

64bit Float

Yes

Input/Output dependency 

 Property      |  Input == Output
-------------- | -------------
 Data Layout   | Yes
 Data Type     | No
 Number        | Yes
 Channels      | Yes
 Width         | Yes
 Height        | Yes

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

  • stream – [in] Handle to a valid CUDA stream.

  • in – [in] input tensor.

  • out – [out] output tensor.

  • alpha – [in] Scalar for output data.

  • beta – [in] Offset for the data.

  • roundMode – [in] Rounding mode used for float-to-integer outputs, cf. NVCVRoundMode. Use NVCV_ROUND_NEAREST to preserve the historical behavior.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Some parameter is outside valid range.

  • NVCV_ERROR_INTERNAL – Internal error in the operator, invalid types passed in.

  • NVCV_SUCCESS – Operation executed successfully.