Codec options#

When creating a decoder or encoder (C API: nvimgcodecDecoderCreate / nvimgcodecEncoderCreate; Python: nvimgcodec.Decoder(options=...) / nvimgcodec.Encoder(options=...)), you can pass an optional options string to tune behavior. The format is the same for both decoders and encoders; details are below.

Decoder options format#

The options string is a space-separated list of entries. Each entry typically has the form :<option>=<value>. Entries can also be prefixed with a decoder identifier for per-decoder options (e.g., nvjpeg_cuda_decoder:hybrid_huffman_threshold=0).

  • Global options (apply to the generic decoder / framework): use a leading colon with no decoder name:

    :<option>=<value>

    Example: :num_cuda_streams=4 limits the number of CUDA streams used (must be between 1 and the number of worker threads). Unknown global options are ignored.

  • Per-decoder options (passed to specific decoder plugins when they are created):

    • For a specific decoder: <decoder_id>:<parameter_name>=<parameter_value>

      Example: nvjpeg_cuda_decoder:hybrid_huffman_threshold=0. Only the decoder whose id matches will apply the option.

    • For any decoder that understands the option: :<parameter_name>=<parameter_value>

      Example: :fancy_upsampling=1. The full options string is passed to every decoder; each plugin may ignore or honor the parameter (e.g. multiple JPEG decoders can all honor fancy_upsampling).

You can combine multiple options in one string. Examples:

  • :fancy_upsampling=0

  • :fancy_upsampling=0 nvjpeg_cuda_decoder:hybrid_huffman_threshold=0

  • :num_cuda_streams=2 nvjpeg_cuda_decoder:device_memory_padding=0

Decoder IDs are defined by each extension. Pass nullptr or an empty string if you do not need any options.

In the Python API, the default constructor uses options="" which keeps each extension defaults.

Options per decoder#

Global (use prefix :; applied by the generic decoder):

  • num_cuda_streams (integer): Number of CUDA streams to use (1 to number of worker threads). Example: :num_cuda_streams=4.

nvjpeg_cuda_decoder (JPEG, CPU/GPU hybrid):

  • fancy_upsampling (0/1): Use “fancy” chroma upsampling. It reduces color bleeding and blockiness around sharp edges by using interpolation instead of simple pixel replication for chroma components. It can also hurt performance, especially for hardware backend. Default: 1 (enabled). Can be switched off with :fancy_upsampling=0. When set to 0, a faster but lower-quality nearest-neighbor upsampling is used instead.

  • enable_roi_fancy_upsampling (0/1): Allow ROI decoding with fancy upsampling enabled. nvJPEG < 13.2 (available in CTK 13.3) may produce wrong pixel values on image edge (1 pixel wide) when fancy upsampling and a non-4:4:4 chroma subsampling are combined with ROI decoding. When this option is 0, the decoder rejects such requests (falls back to another decoder). Default: 1 if nvJPEG ≥ 13.2, 0 otherwise.

  • hybrid_huffman_threshold (integer): Pixel count above which GPU hybrid Huffman decoding is used. Default: 1000000.

  • device_memory_padding (integer): Device memory padding in bytes.

  • host_memory_padding (integer): Pinned/host memory padding in bytes.

  • preallocate_buffers (0/1): Preallocate internal buffers.

  • extra_flags (integer): Experimental: Extra nvJPEG creation flags.

nvjpeg_hw_decoder (JPEG, hardware-accelerated):

  • fancy_upsampling (0/1): Same as above.

  • enable_roi_fancy_upsampling (0/1): Same as above.

  • preallocate_width_hint (integer): Hint for preallocated buffer width.

  • preallocate_height_hint (integer): Hint for preallocated buffer height.

  • preallocate_batch_size (integer): Batch size for preallocated buffers.

  • extra_flags (integer): Experimental: Extra nvJPEG creation flags.

nvjpeg_lossless_decoder (Lossless JPEG):

  • fancy_upsampling (0/1): Same as above.

  • extra_flags (integer): Experimental: Extra nvJPEG creation flags.

nvjpeg2k_cuda_decoder (JPEG 2000):

  • num_parallel_tiles (integer): Number of tiles decoded in parallel (shared across all threads). Default: 16.

  • device_memory_padding (integer): Device memory padding in bytes.

  • host_memory_padding (integer): Pinned/host memory padding in bytes.

libjpeg_turbo_decoder (JPEG, CPU):

  • fancy_upsampling (0/1): Use fancy upsampling. Default: 1.

  • fast_idct (0/1): libjpeg-turbo-specific option. If set to 1, enables a faster but slightly less accurate integer IDCT (Inverse Discrete Cosine Transform) algorithm provided by libjpeg-turbo. This can offer higher performance for JPEG decoding, with a possible minor reduction in image fidelity compared to the default (more accurate) algorithm. Default value: 0 (higher accuracy).

Currently, other decoders (e.g. nvtiff, libtiff) do not define custom options; they accept the options string but ignore it.

Encoder options format#

The options string uses the same format as decoder options: a space-separated list of entries. Each entry has the form <option>=<value>, optionally prefixed with an encoder identifier.

  • Global options (apply to the generic encoder / framework): use a leading colon with no encoder name:

    :<option>=<value>

    Example: :num_cuda_streams=4 limits the number of CUDA streams (same as for decoders; must be between 1 and the number of worker threads).

  • Per-encoder options: <encoder_id>:<parameter_name>=<parameter_value>

    Only the encoder whose id matches will apply the option. Example: nvjpeg_cuda_encoder:quality=90. You can combine multiple options, e.g. :num_cuda_streams=2 nvjpeg_cuda_encoder:quality=85. Pass nullptr or an empty string if you do not need any options.

Options per encoder#

Global (use prefix :; applied by the generic encoder):

  • num_cuda_streams (integer): Number of CUDA streams to use (1 to number of worker threads). Example: :num_cuda_streams=4.

Encoder IDs (for per-encoder options, <encoder_id>:<option>=<value>). Built-in extensions register the following encoder IDs:

  • nvjpeg_cuda_encoder — JPEG (CPU/GPU hybrid).

  • nvjpeg_hw_encoder — JPEG (hardware-accelerated, when available).

  • nvjpeg2k_encoder — JPEG 2000.

  • nvtiff_cuda_encoder — TIFF.

  • nvpnm_encoder — PNM (PBM/PGM/PPM).

  • nvbmp_encoder — BMP.

  • opencv_jpeg_encoder, opencv_jpeg2k_encoder, opencv_bmp_encoder, opencv_pnm_encoder — OpenCV-based encoders (CPU fallback).

The built-in encoder extensions currently do not define encoder-specific options in the options string; they accept the options string but only global options (e.g. :num_cuda_streams=4) are applied. Quality and similar settings are set per encode via encode parameters (e.g. nvimgcodecEncodeParams_t with quality_type / quality_value). The per-encoder options format in the string is reserved for future use or custom extensions.