nvJPEG2000 文档¶
简介¶
nvJPEG2000 库加速了 NVIDIA GPU 上 JPEG2000 图像的解码和编码。该库构建于 CUDA 平台之上，并支持 Pascal+ GPU 架构。
注意
在本文档中，“CPU”和“主机”这两个术语可以互换使用。同样，“GPU”和“设备”这两个术语也可以互换使用。
nvJPEG2000 解码器¶
该库同时利用 CPU 和 GPU 进行解码。二级解码阶段（解码的第一阶段；详情请参阅 JPEG2000 规范）在 CPU 上运行。解码过程的所有其他阶段都卸载到 GPU 上。
nvJPEG2000 解码器支持以下功能
JPEG2000 选项
每个组件最多 16 位
组件数量：4
可逆 (5-3) 和不可逆 (9-7) 小波变换
每个图像多个瓦片
每个图像最多 32 层
色度子采样类型 - 444、422 和 420
所有渐进顺序
图像和瓦片起始坐标应为 0
基于瓦片/分辨率的解码
瓦片和图像的部分解码
jp2 文件格式和 jpeg2000 码流
高吞吐量 jpeg2000（所有代码块都必须是 HT 代码块，具有一个 HT 集且没有细化）
功能特性
在流水线模式下解码多个图像。有关详细信息，请参阅 nvJPEG2000-Decoder-Pipelined 示例。
颜色转换为 RGB。
支持平面和交错输出。
nvJPEG2000 编码器¶
该库同时利用 GPU 和 CPU 来创建 JPEG2000 比特流。编码 API 要求输入图像位于设备内存中，压缩后的比特流将写入主机内存。
nvJPEG2000 编码器支持以下功能
JPEG2000 选项
每个组件最多 16 位
组件数量：4
可逆 (5-3) 和不可逆 (9-7) 小波变换
每个图像多个瓦片
每个图像单层
所有渐进顺序
色度子采样类型 - 444、422 和 420
jp2 文件格式和 jpeg2000 码流
基于 PSNR 的速率控制
功能特性
支持平面和交错输入。
前提条件¶
CUDA 工具包版本 11.0 及以上
CUDA 驱动程序版本 r450 及以上
支持的平台¶
Linux 版本
架构 |
发行版信息 |
||||
|---|---|---|---|---|---|
名称 |
版本 |
内核 |
GCC |
GLIBC |
|
x86_64 |
RHEL/CentOS |
9.1 |
5.14 |
11.3.1 |
2.34 |
8.3 |
4.18 |
8.5.0 |
2.28 |
||
7.9 |
3.10.0 |
7.3 |
2.17 |
||
Ubuntu |
22.04 |
5.15.0 |
11.4.0 |
2.34 |
|
20.04 |
5.13.0 |
9.4.0 |
2.31 |
||
18.04 |
5.4.0 |
7.5.0 |
2.27 |
||
OpenSUSE Leap |
15.5 |
5.14.21 |
7.5.0 |
2.31 |
|
SUSE SLES |
15.5 |
5.14.21 |
7.5.0 |
2.31 |
|
Debian |
11.6 |
5.10.0 |
10.2.1 |
2.31 |
|
10.13 |
4.19.0 |
8.3.0 |
2.28 |
||
Fedora |
37 |
6.07 |
12.2.1 |
2.36 |
|
arm64-sbsa |
RHEL |
9.2 |
5.14 |
11.3.1 |
2.34 |
8.3 |
4.18 |
8.5.0 |
2.28 |
||
Ubuntu |
22.04 |
5.15.0 |
11.4.0 |
2.35 |
|
20.04 |
5.4.0 |
9.4.0 |
2.31 |
||
SUSE SLES |
15.5 |
5.14.21 |
7.5.0 |
2.31 |
|
Windows 版本
Windows 10/11。
Tegra
Jetpack v5.1.3 及以上版本支持。
线程安全¶
并非所有 nvJPEG2000 类型都是线程安全的。以下类型应为每个线程单独实例化：nvjpeg2kDecodeState_t、nvjpeg2kStream_t 和 nvjpeg2kEncodeState_t。
安装 nvJPEG2000¶
NVIDIA DevZone¶
nvJPEG2000 二进制文件和下载说明可在此处获取 - https://developer.nvidia.com/nvjpeg2000-downloads。
对于 Linux，二进制文件以存档 (.tar.xz) 和软件包管理器格式 (.deb, .rpm) 提供
对于 Windows，二进制文件以存档 (.zip) 和 Windows 安装程序格式提供。
PyPi¶
nvJPEG2000 二进制文件在 PyPi 上提供，可以通过 pip 使用以下命令安装。这使得该库可以轻松地在 python 环境中使用。
安装 CUDA 12.x 版本的 nvJPEG2000
python3 -m pip install nvidia-nvjpeg2k-cu12
在 Tegra 平台上安装 CUDA 12.x 版本的 nvJPEG2000
python3 -m pip install nvidia-nvjpeg2k-tegra-cu12
安装 CUDA 11.x 版本的 nvJPEG2000
python3 -m pip install nvidia-nvjpeg2k-cu11
在 Tegra 平台上安装 CUDA 11.x 版本的 nvJPEG2000
python3 -m pip install nvidia-nvjpeg2k-tegra-cu11
快速入门指南¶
本节将介绍如何在几个快速步骤中使用解码器和编码器 API。API 详细信息将在下一节中介绍。
注意
nvJPEG2000 示例链接：https://github.com/NVIDIA/CUDALibrarySamples/tree/master/nvJPEG2000
JPEG2000 解码¶
该库期望比特流位于主机内存中，解码后的输出将写入设备内存。
初始化下面列出的库句柄
nvjpeg2kStream_t- 用于解析比特流并存储比特流元数据nvjpeg2kHandle_t- 是 nvjpeg2k 库句柄nvjpeg2kDecodeState_t- 用于存储解码所需的工作缓冲区
nvjpeg2kHandle_t nvjpeg2k_handle;
nvjpeg2kStream_t nvjpeg2k_stream;
nvjpeg2kDecodeState_t decode_state;
nvjpeg2kCreateSimple(&nvjpeg2k_handle);
nvjpeg2kDecodeStateCreate(&decode_state);
nvjpeg2kStreamCreate(&nvjpeg2k_stream);
从磁盘读取 JPEG2000 比特流文件并将其存储在主机缓冲区中。该库支持 .jp2 文件和 JPEG2000 码流。
使用 nvjpeg2kStreamParse API 解析比特流。
size_t length;
unsigned char *bitstream_buffer; // host or pinned memory
// read the bitstream from and store it in bitstream_buffer;
// content of bitstream buffer should not be overwritten until the decoding is complete
nvjpeg2kStatus_t status = nvjpeg2kStreamParse(nvjpeg2k_handle, bitstream_buffer, length, 0, 0, nvjpeg2k_stream);
// make sure that nvjpeg2kStreamParse returns NVJPEG2K_STATUS_SUCCESS before proceeding to the next step
4. 提取每个组件的图像尺寸，并在设备上分配输出内存，如下面的代码片段所示。解码后的输出存储在 nvjpeg2kImage_t 中。此数据结构能够处理 8 位和 16 位精度的输出。下面的代码片段演示了 8 位 3 通道图像的 nvjpeg2kImage_t 初始化。
#define NUM_COMPONENTS 3
// extract image info
nvjpeg2kImageInfo_t image_info;
nvjpeg2kStreamGetImageInfo(nvjpeg2k_stream, &image_info);
// assuming the decoding of images with 8 bit precision, and 3 components
nvjpeg2kImageComponentInfo_t image_comp_info[NUM_COMPONENTS];
for (int c = 0; c < image_info.num_components; c++)
{
nvjpeg2kStreamGetImageComponentInfo(nvjpeg2k_stream, &image_comp_info[c], c);
}
unsigned char *decode_output[NUM_COMPONENTS];
size_t pitch_in_bytes[NUM_COMPONENTS];
nvjpeg2kImage_t output_image;
for (int c = 0; c < NUM_COMPONENTS; c++)
{
cudaMallocPitch(&decode_output[c], &pitch_in_bytes[c], image_comp_info[c].comp_width, image_comp_info[c].comp_height );
}
output_image.pixel_data = decode_output;
output_image.pixel_type = NVJPEG2K_UINT8;
output_image.pitch_in_bytes = pitch_in_bytes;
调用 nvjpeg2kDecode()。cudaStream_t 是此函数的参数之一。如果传递了流标识符，则 API 将使用它来发出异步 cuda 调用。
cudaDeviceSynchronize()是完成解码过程所必需的，因为nvjpeg2kDecode相对于主机是异步的。
nvjpeg2kStatus_t status = nvjpeg2kDecode(nvjpeg2k_handle, decode_state, nvjpeg2k_stream, &output_image, 0); // 0 corresponds to cudaStream_t
cudaDeviceSynchronize()
转到步骤 2 解码另一张图像。解码完所有图像后，通过调用相应的销毁 API 释放 nvJPEG2000 库资源。
JPEG2000 编码¶
该库期望输入图像以平面格式位于设备内存中，压缩后的输出将写入主机内存。
初始化下面列出的库句柄
nvjpeg2kEncoder_t- 是 nvJPEG2000 编码器句柄nvjpeg2kEncodeState_t- 用于存储编码器工作缓冲区和中间结果nvjpeg2kEncodeParams_t- 存储控制压缩输出的各种参数
nvjpeg2kEncoder_t enc_handle;
nvjpeg2kEncodeState_t enc_state;
nvjpeg2kEncodeParams_t enc_params;
nvjpeg2kEncoderCreateSimple(&enc_handle);
nvjpeg2kEncodeStateCreate(&enc_state);
nvjpeg2kEncodeParamsCreate(&enc_params);
2. 以平面格式将输入图像复制到设备内存。将图像缓冲区指针存储在 nvjpeg2kImage_t 中。下面的代码片段演示了 8 位 3 通道 RGB 图像的 nvjpeg2kImage_t 和 nvjpeg2kImageComponentInfo_t 初始化。
#define NUM_COMPONENTS 3
unsigned char *pixel_data[NUM_COMPONENTS];
size_t pitch_in_bytes[NUM_COMPONENTS];
nvjpeg2kImageComponentInfo_t image_comp_info[NUM_COMPONENTS];
uint32_t image_width = // assign image width
uint32_t image_height = // assign image height
for (int c = 0; c < image_info.num_components; c++)
{
image_comp_info[c].component_width = image_width;
image_comp_info[c].component_height = image_height;
image_comp_info[c].precision = 8;
image_comp_info[c].sgn = 0;
}
nvjpeg2kImage_t input_image;
for (int c = 0; c < NUM_COMPONENTS; c++)
{
cudaMallocPitch(&pixel_data[c], &pitch_in_bytes[c], image_comp_info[c].comp_width, image_comp_info[c].comp_height);
// cudaMallocPitch is used to let cuda deterimine the pitch. cudaMalloc can be used if required.
}
// Copy the image to the device buffers.
input_image.pixel_data = pixel_data;
input_image.pixel_type = NVJPEG2K_UINT8;
input_image.pitch_in_bytes = pitch_in_bytes;
3. 填充 nvjpeg2kEncodeConfig_t 结构并调用 nvjpeg2kEncodeParamsSetEncodeConfig。下面的代码片段记录了使用可逆小波变换和 64x64 代码块大小生成 JPEG2000 比特流的设置。
注意
nvjpeg2kEncodeConfig_t 中每个字段的有效值记录在此处。
nvjpeg2kEncodeConfig_t enc_config;
memset(&enc_config, 0, sizeof(enc_config));
enc_config.stream_type = NVJPEG2K_STREAM_JP2; // the bitstream will be in JP2 container format
enc_config.color_space = NVJPEG2K_COLORSPACE_SRGB; // input image is in RGB format
enc_config.image_width = image_width;
enc_config.image_height = image_height;
enc_config.num_components = NUM_COMPONENTS;
enc_config.image_comp_info = &image_comp_info;
enc_config.code_block_w = 64;
enc_config.code_block_h = 64;
enc_config.irreversible = 0
enc_config.mct_mode = 1;
enc_config.prog_order = NVJPEG2K_LRCP;
enc_config.num_resolutions = 6;
nvjpeg2kStatus_t status = nvjpeg2kEncodeParamsSetEncodeConfig(enc_params, &enc_config);
注意
所有 nvJPEG2000 API 都应返回 NVJPEG2K_STATUS_SUCCESS。否则，结果可能无效。
对于有损编码，请设置以分贝 (dB) 为单位的目标 PSNR，如下所示。对于无损编码，无需调用此 API。
double target_psnr = 50;
status = nvjpeg2kEncodeParamsSetQuality(enc_params, target_psnr));
调用
nvjpeg2kEncode。cudaStream_t 是此函数的参数之一。如果传递了流标识符，则 API 将使用它来发出异步 cuda 调用。
status = nvjpeg2kEncode(enc_handle, enc_state, enc_params, &input_image, NULL));
6. 将压缩后的 JPEG2000 比特流检索到主机内存，如下面的代码片段所示。如果传递了流标识符，则 API 将使用它来发出异步 cuda 调用。cudaDeviceSynchronize() 是完成编码过程所必需的，因为 API 相对于主机是异步的。
// set the compressed_data buffer to NULL to retrieve the bitstream size
size_t compressed_size;
status = nvjpeg2kEncodeRetrieveBitstream(enc_handle, enc_state, NULL, &compressed_size);
// allocate output buffer
unsigned char *compressed_data = new unsigned char [compressed_size]
status = nvjpeg2kEncodeRetrieveBitstream(enc_handle, enc_state, compressed_data, &compressed_size,
params.stream));
cudaDeviceSynchronize();
7 转到步骤 2 编码另一张图像。编码完所有图像后，通过调用相应的销毁 API 释放 nvJPEG2000 库资源。
类型声明¶
API 返回状态码¶
下面列出了 nvJPEG2000 API 的返回码
typedef enum
{
NVJPEG2K_STATUS_SUCCESS = 0,
NVJPEG2K_STATUS_NOT_INITIALIZED = 1,
NVJPEG2K_STATUS_INVALID_PARAMETER = 2,
NVJPEG2K_STATUS_BAD_JPEG = 3,
NVJPEG2K_STATUS_JPEG_NOT_SUPPORTED = 4,
NVJPEG2K_STATUS_ALLOCATOR_FAILURE = 5,
NVJPEG2K_STATUS_EXECUTION_FAILED = 6,
NVJPEG2K_STATUS_ARCH_MISMATCH = 7,
NVJPEG2K_STATUS_INTERNAL_ERROR = 8,
NVJPEG2K_STATUS_IMPLEMENTATION_NOT_SUPPORTED = 9,
} nvjpeg2kStatus_t;
返回码的描述
返回码 |
描述 |
|---|---|
NVJPEG2K_STATUS_SUCCESS (0) |
API 调用已成功完成。请注意，许多调用是异步的，某些错误可能仅在同步后才会看到。 |
NVJPEG2K_STATUS_NOT_INITIALIZED (1) |
库句柄未初始化。 |
NVJPEG2K_STATUS_INVALID_PARAMETER (2) |
传递了错误的参数。例如，空指针作为输入数据，或无效的枚举值 |
NVJPEG2K_STATUS_BAD_JPEG (3) |
无法解析 JPEG2000 流。可能是由于无法处理的损坏 |
NVJPEG2K_STATUS_JPEG_NOT_SUPPORTED (4) |
尝试解码 nvJPEG2000 库不支持的 JPEG2000 流。 |
NVJPEG2K_STATUS_ALLOCATOR_FAILURE (5) |
用户提供的分配器函数（用于内存分配或释放内存）返回了非零代码。 |
NVJPEG2K_STATUS_EXECUTION_FAILED (6) |
设备任务执行期间出错。 |
NVJPEG2K_STATUS_ARCH_MISMATCH (7) |
设备功能不足以满足提供的输入参数集。 |
NVJPEG2K_STATUS_INTERNAL_ERROR (8) |
库中发生未知错误。 |
NVJPEG2K_STATUS_IMPLEMENTATION_NOT_SUPPORTED (9) |
后端不支持 API。 |
设备分配器接口¶
typedef int (*nvjpeg2kDeviceMalloc)(void**, size_t);
typedef int (*nvjpeg2kDeviceFree)(void*);
typedef struct
{
nvjpeg2kDeviceMalloc device_malloc;
nvjpeg2kDeviceFree device_free;
} nvjpeg2kDeviceAllocator_t;
当 nvjpeg2kCreate() 函数中的 nvjpeg2kDeviceAllocator_t *allocator 参数设置为指向上述 nvjpeg2kDeviceAllocator_t 结构的指针时，此结构用于分配和释放设备内存。内存分配和内存释放函数的函数原型类似于 cudaMalloc() 和 cudaFree() 函数。成功时应返回 0，否则返回非零值。
但是，如果 nvjpeg2kCreate() 函数中的 nvjpeg2kDeviceAllocator_t *allocator 参数设置为 NULL，则将使用默认内存分配函数 cudaMalloc() 和 cudaFree()。当使用 nvjpeg2kCreateSimple() 函数创建库句柄时，将使用默认的设备内存分配器。
固定分配器接口¶
typedef int (*nvjpeg2kPinnedMalloc)(void**, size_t, unsigned int flags);
typedef int (*nvjpeg2kPinnedFree)(void*)
typedef struct
{
nvjpeg2kPinnedMalloc pinned_malloc;
nvjpeg2kPinnedFree pinned_free;
} nvjpeg2kPinnedAllocator_t;
当 nvjpegPinnedAllocator_t *allocator 参数在 nvjpeg2kCreate() 函数中设置为指向上述 nvjpegPinnedAllocator_t 结构的指针时，此结构将用于分配和释放主机固定内存，以便将数据复制到/从设备。内存分配和内存释放函数的函数原型类似于 cudaHostAlloc() 和 cudaFreeHost() 函数。成功时将返回 0，否则返回非零值。
但是，如果 nvjpeg2kPinnedAllocator_t *allocator 参数在 nvjpeg2kCreate() 函数中设置为 NULL，则将使用默认内存分配函数 cudaHostAlloc() 和 cudaFreeHost()。当使用 nvjpegCreateSimple() 函数创建库句柄时，将使用默认的主机固定内存分配器。
扩展设备分配器接口¶
typedef int (*nvjpeg2kDeviceMallocV2)(void* ctx, void **ptr, size_t size, cudaStream_t stream);
typedef int (*nvjpeg2kDeviceFreeV2)(void* ctx, void *ptr, size_t size, cudaStream_t stream);
typedef struct nvjpeg2kDeviceAllocatorV2
{
nvjpeg2kDeviceMallocV2 device_malloc;
nvjpeg2kDeviceFreeV2 device_free;
void *device_ctx;
} nvjpeg2kDeviceAllocatorV2_t;
允许用户提供接受 cuda 流和用户上下文的设备分配器。成功时它们将返回 0，否则返回非零值。可以使用 nvjpeg2kCreateV2() 将扩展设备分配器作为输入传递到库中。
扩展固定分配器接口¶
typedef int (*nvjpeg2kPinnedMallocV2)(void* ctx, void **ptr, size_t size, cudaStream_t stream);
typedef int (*nvjpeg2kPinnedFreeV2)(void* ctx, void *ptr, size_t size, cudaStream_t stream)
typedef struct nvjpeg2kPinnedAllocatorV2
{
nvjpeg2kPinnedMallocV2 pinned_malloc;
nvjpeg2kPinnedFreeV2 pinned_free;
void *pinned_ctx;
} nvjpeg2kPinnedAllocatorV2_t;
允许用户提供接受 cuda 流和用户上下文的固定分配器。成功时它们将返回 0，否则返回非零值。可以使用 nvjpeg2kCreateV2() 将扩展固定分配器作为输入传递到库中。
色彩空间¶
typedef enum
{
NVJPEG2K_COLORSPACE_NOT_SUPPORTED = -1,
NVJPEG2K_COLORSPACE_UNKNOWN = 0,
NVJPEG2K_COLORSPACE_SRGB = 1,
NVJPEG2K_COLORSPACE_GRAY = 2,
NVJPEG2K_COLORSPACE_SYCC = 3
} nvjpeg2kColorSpace_t;
nvjpeg2kColorSpace_t 枚举对应于 JP2 文件格式规范中包含的色彩空间值。
库后端¶
typedef enum
{
NVJPEG2K_BACKEND_DEFAULT = 0
} nvjpeg2kBackend_t;
nvjpeg2kBackend_t 枚举允许用户选择不同的内部实现。当前仅支持单个实现。未来可能会添加其他实现。
组件信息¶
typedef struct
{
uint32_t component_width;
uint32_t component_height;
uint8_t precision;
uint8_t sgn;
} nvjpeg2kImageComponentInfo_t;
nvjpeg2kImageComponentInfo_t 用于检索组件级别的信息。此信息可用于分配输出缓冲区。
图像信息¶
typedef struct
{
uint32_t image_width;
uint32_t image_height;
uint32_t tile_width;
uint32_t tile_height;
uint32_t num_tiles_x;
uint32_t num_tiles_y;
uint32_t num_components;
} nvjpeg2kImageInfo_t;
nvjpeg2kImageInfo_t 用于检索图像信息，该信息可用于分配输出缓冲区。
图像类型¶
typedef enum
{
NVJPEG2K_UINT8 = 0,
NVJPEG2K_UINT16 = 1,
NVJPEG2K_INT16 = 2
} nvjpeg2kImageType_t;
nvjpeg2kImageType_t 描述了 nvJPEG2000 支持的像素数据类型。
图像数据¶
typedef struct
{
void **pixel_data;
size_t *pitch_in_bytes;
nvjpeg2kImageType_t pixel_type;
uint32_t num_components;
} nvjpeg2kImage_t;
nvjpeg2kImage_t 用作图像容器。它包含一个 void 指针数组。每个指针对应于 nvjpeg2k 比特流中的一个组件。还有另一个对应的数组，用于定义每个组件的步幅。pixel_type 确定 pixel_data 的数据类型。有关支持的类型，请参阅图像类型。
图像格式¶
typedef enum
{
NVJPEG2K_FORMAT_PLANAR = 0,
NVJPEG2K_FORMAT_INTERLEAVED = 1
} nvjpeg2kImageFormat_t;
nvjpeg2kImageFormat_t 描述了图像在内存中的存储方式。
NVJPEG2K_FORMAT_PLANAR表示图像的所有组件都存储在单独的平面中。NVJPEG2K_FORMAT_INTERLEAVED表示图像的所有组件都以交错顺序存储。当图像的组件尺寸不同时，不支持此格式。
解码器¶
解码器句柄¶
struct nvjpeg2kHandle;
typedef struct nvjpeg2kHandle* nvjpeg2kHandle_t;
应在使用任何解码 API 之前实例化此句柄。它是线程安全的，可以由多个线程同时使用。
解码器状态¶
struct nvjpeg2kDecodeState;
typedef struct nvjpeg2kDecodeState* nvjpeg2kDecodeState_t;
nvjpeg2kDecodeState_t 句柄存储中间解码信息。解码多个图像时，可以重复使用此句柄。用户必须确保在两个图像的解码之间进行流或设备同步 CUDA 调用。
比特流句柄¶
struct nvjpeg2kStream;
typedef struct nvjpeg2kStream* nvjpeg2kStream_t;
此句柄用于解析比特流。比特流元数据可以使用 解析器 API 参考 中定义的 API 提取。
解码参数句柄¶
struct nvjpeg2kDecodeParams;
typedef struct nvjpeg2kDecodeParams* nvjpeg2kDecodeParams_t;
此句柄用于存储解码输出参数，例如感兴趣区域坐标的解码区域。
编码器¶
编码器句柄¶
struct nvjpeg2kEncoder;
typedef struct nvjpeg2kEncoder* nvjpeg2kEncoder_t;
应在使用任何编码 API 之前实例化此句柄。它是线程安全的，可以在主机线程之间使用。
编码状态¶
struct nvjpeg2kEncodeState;
typedef struct nvjpeg2kEncodeState* nvjpeg2kEncodeState_t;
nvjpeg2kEncodeState_t 句柄包含编码过程所需的中间缓冲区。
编码参数句柄¶
struct nvjpeg2kEncodeParams;
typedef struct nvjpeg2kEncodeParams* nvjpeg2kEncodeParams_t;
此句柄存储用户提供的控制编码过程的参数。
最大分辨率¶
#define NVJPEG2K_MAXRES 33
JPEG2000 标准支持的最大分辨率数。
渐进顺序¶
typedef enum
{
NVJPEG2K_LRCP = 0,
NVJPEG2K_RLCP = 1,
NVJPEG2K_RPCL = 2,
NVJPEG2K_PCRL = 3,
NVJPEG2K_CPRL = 4
} nvjpeg2kProgOrder;
JPEG2000 标准中定义的渐进顺序。
比特流类型¶
typedef enum
{
NVJPEG2K_STREAM_J2K = 0,
NVJPEG2K_STREAM_JP2 = 1
} nvjpeg2kBitstreamType;
NVJPEG2K_STREAM_J2K 对应于 JPEG2000 码流。NVJPEG2K_STREAM_JP2 对应于 .jp2 容器。
编码配置¶
typedef struct
{
nvjpeg2kBitstreamType stream_type;
nvjpeg2kColorSpace_t color_space;
uint16_t rsiz;
uint32_t image_width;
uint32_t image_height;
uint32_t enable_tiling;
uint32_t tile_width;
uint32_t tile_height;
uint32_t num_components;
nvjpeg2kImageComponentInfo_t *image_comp_info;
uint32_t enable_SOP_marker;
uint32_t enable_EPH_marker;
nvjpeg2kProgOrder prog_order;
uint32_t num_layers;
uint32_t mct_mode;
uint32_t num_resolutions;
uint32_t code_block_w;
uint32_t code_block_h;
uint32_t encode_modes;
uint32_t irreversible;
uint32_t enable_custom_precincts;
uint32_t precint_width[NVJPEG2K_MAXRES];
uint32_t precint_height[NVJPEG2K_MAXRES];
} nvjpeg2kEncodeConfig_t;
nvjpeg2kEncodeConfig_t 主要包含 SIZ 和 COD JPEG2000 标头中定义的参数。并非所有参数都受支持，必须设置为 0。下表捕获了 nvjpeg2kEncodeConfig_t 中每个参数的有效值。
数据类型 |
名称 |
有效值 (v0.8.0) |
|
nvjpeg2kBitstreamType |
stream_type |
所有枚举值 |
|
nvjpeg2kColorSpace_t |
color_space |
所有枚举值 |
|
uint16_t |
rsiz |
0 |
|
uint32_t |
image_width |
最小值 1 |
|
uint32_t |
image_height |
最小值 1 |
|
uint32_t |
enable_tiling |
0,1 |
|
uint32_t |
tile_width |
enable_tiling 应为 1，应小于 image_width |
|
uint32_t |
tile_height |
enable_tiling 应为 1，应小于 image_height |
|
uint32_t |
num_components |
1 - 4 |
|
nvjpeg2kImageComponentInfo_t |
*image_comp_info |
有效指针 |
|
uint32_t |
enable_SOP_marker |
0 |
|
uint32_t |
enable_EPH_marker |
0 |
|
nvjpeg2kProgOrder |
prog_order |
此处定义的所有值 |
|
uint32_t |
num_layers |
1 |
|
uint32_t |
mct_mode |
0 (YCC 和灰度), 1 (RGB) |
|
uint32_t |
num_resolutions |
不能大于图像/瓦片尺寸 |
|
uint32_t |
code_block_w |
32, 64 |
|
uint32_t |
code_block_h |
32, 64 |
|
uint32_t |
encode_modes |
0 |
|
uint32_t |
不可逆 |
0, 1 |
|
uint32_t |
num_precincts_init |
0, 有效区域的数量 |
|
uint32_t |
precint_width[NVJPEG2K_MAXRES] |
应为 2 的幂，仅当 num_precincts_init 为非零时有效。 |
|
uint32_t |
precint_height[NVJPEG2K_MAXRES] |
应为 2 的幂，仅当 num_precincts_init 为非零时有效。 |
|
API 参考¶
辅助 API 参考¶
nvjpeg2kGetCudartProperty()¶
获取用于构建 nvJPEG2000 库的 CUDA 工具包的主版本号、次版本号或补丁级别的数值
签名
nvjpeg2kStatus_t nvjpeg2kGetCudartProperty(libraryPropertyType type, int *value);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
libraryPropertyType type |
输入 |
主机 |
支持的 libraryPropertyType 值之一，即 MAJOR_VERSION、MINOR_VERSION 或 PATCH_LEVEL |
int *value |
输出 |
主机 |
与请求的特定 libraryPropertyType 对应的数值。 |
nvjpeg2kGetProperty()¶
获取 nvJPEG2000 库的主版本号、次版本号或补丁级别的数值。
签名
nvjpeg2kStatus_t nvjpeg2kGetProperty(libraryPropertyType type, int *value);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
libraryPropertyType type |
输入 |
主机 |
支持的 libraryPropertyType 值之一，即 MAJOR_VERSION、MINOR_VERSION 或 PATCH_LEVEL |
int *value |
输出 |
主机 |
与请求的特定 libraryPropertyType 对应的数值。 |
nvjpeg2kCreateSimple()¶
使用默认后端和内存分配器创建库句柄实例。
签名
nvjpeg2kStatus_t nvjpeg2kCreateSimple(nvjpeg2kHandle_t *handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kCreate()¶
使用输入参数创建库实例。用户可以灵活选择后端实现并提供分配器。
签名
nvjpeg2kStatus_t nvjpeg2kCreate(
nvjpeg2kBackend_t backend,
nvjpeg2kDeviceAllocator_t *device_allocator,
nvjpeg2kPinnedAllocator_t *pinned_allocator,
nvjpeg2kHandle_t *handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kBackend_t backend |
输入 |
主机 |
后端参数 |
nvjpeg2kDeviceAllocator_t *device_allocator |
输入 |
主机 |
设备分配器。如果设置为 NULL，则使用 cudaMalloc 和 cudaFree。请参阅设备分配器接口 |
nvjpeg2kPinnedAllocator_t *pinned_allocator |
输入 |
主机 |
固定分配器。如果设置为 NULL，则使用 cudaHostAlloc 和 cudaHost。请参阅固定分配器接口 |
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kCreateV2()¶
使用扩展分配器创建库实例。
签名
nvjpeg2kStatus_t nvjpeg2kCreateV2(
nvjpeg2kBackend_t backend,
nvjpeg2kDeviceAllocatorV2_t*device_allocator,
nvjpeg2kPinnedAllocatorV2_t*pinned_allocator,
nvjpeg2kHandle_t *handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kBackend_t backend |
输入 |
主机 |
后端参数 |
nvjpeg2kDeviceAllocatorV2_t *device_allocator |
输入 |
主机 |
扩展设备分配器。不能为 NULL。请参阅扩展设备分配器接口 |
nvjpeg2kPinnedAllocatorV2_t *pinned_allocator |
输入 |
主机 |
扩展固定分配器。不能为 NULL。请参阅扩展固定分配器接口 |
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDestroy()¶
释放 nvjpeg2k 库句柄。
签名
nvjpeg2kStatus_t nvjpeg2kDestroy(nvjpeg2kHandle_t handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kSetDeviceMemoryPadding()¶
设置设备内存分配的填充。成功调用此函数后，任何设备内存分配都将填充到指定字节数的倍数。这有助于最大限度地减少设备内存重新分配的次数
签名
nvjpeg2kStatus_t nvjpeg2kSetDeviceMemoryPadding(size_t padding,
nvjpeg2kHandle_t decode_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
size_t padding |
输入 |
主机 |
用于所有进一步设备内存分配的设备内存填充 |
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kGetDeviceMemoryPadding()¶
检索设备内存分配的填充
签名
nvjpeg2kStatus_t nvjpeg2kGetDeviceMemoryPadding(size_t *padding,
nvjpeg2kHandle_t handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
size_t *padding |
输入 |
主机 |
当前使用的设备内存填充 |
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kSetPinnedMemoryPadding()¶
设置固定内存分配的填充。成功调用此函数后，任何固定内存分配都将填充到指定字节数的倍数。这有助于最大限度地减少固定内存重新分配的次数
签名
nvjpeg2kStatus_t nvjpeg2kSetPinnedMemoryPadding(size_t padding,
nvjpeg2kHandle_t decode_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
size_t padding |
输入 |
主机 |
用于所有进一步设备内存分配的固定内存填充 |
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kGetPinnedMemoryPadding()¶
检索固定内存分配的填充
签名
nvjpeg2kStatus_t nvjpeg2kGetPinnedMemoryPadding(size_t *padding,
nvjpeg2kHandle_t handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
size_t *padding |
输入 |
主机 |
当前使用的固定内存填充 |
nvjpeg2kHandle_t *handle |
输入/输出 |
主机 |
nvjpeg2k 库句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeStateCreate()¶
创建解码状态的实例。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeStateCreate(
nvjpeg2kHandle_t handle,
nvjpeg2kDecodeState_t *decode_state);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
nvjpeg2k 库句柄 |
nvjpeg2kDecodeState_t *decode_state |
输入/输出 |
主机 |
解码状态句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeStateDestroy()¶
释放解码状态句柄。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeStateDestroy(nvjpeg2kDecodeState_t decode_state);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kDecodeState_t decode_state |
输入 |
主机 |
解码状态句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamCreate()¶
创建比特流句柄的实例。
签名
nvjpeg2kStatus_t nvjpeg2kStreamCreate(nvjpeg2kStream_t *stream_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kStream_t *stream_handle |
输入/输出 |
主机 |
nvjpeg2k 比特流句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamDestroy()¶
释放比特流句柄。
签名
nvjpeg2kStatus_t nvjpeg2kStreamDestroy(nvjpeg2kStream_t stream_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kStream_t stream_handle |
输入 |
主机 |
nvjpeg2k 比特流句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeParamsCreate()¶
创建解码输出参数句柄的实例。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeParamsCreate(nvjpeg2kDecodeParams_t *decode_params);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kDecodeParams_t *decode_params |
输入/输出 |
主机 |
解码输出参数句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeParamsDestroy()¶
释放解码输出参数句柄。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeParamsDestroy(nvjpeg2kDecodeParams_t decode_params);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kDecodeParams_t decode_params |
输入 |
主机 |
解码输出参数句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncoderCreateSimple()¶
创建 nvJPEG2000 编码器句柄的实例。
签名
nvjpeg2kStatus_t nvjpeg2kEncoderCreateSimple(nvjpeg2kEncoder_t *enc_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncoder_t *enc_handle |
输入/输出 |
主机 |
nvJPEG2000 编码器句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncoderDestroy()¶
释放 nvJPEG2000 编码器句柄。
签名
nvjpeg2kStatus_t nvjpeg2kEncoderDestroy(nvjpeg2kEncoder_t enc_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncoder_t enc_handle |
输入 |
主机 |
nvJPEG2000 编码器句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeStateCreate()¶
创建编码状态的实例。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeStateCreate(
nvjpeg2kEncoder_t enc_handle,
nvjpeg2kEncodeState_t *encode_state);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncoder_t enc_handle |
输入 |
主机 |
nvJPEG2000 编码器句柄 |
nvjpeg2kEncodeState_t *encode_state |
输入/输出 |
主机 |
nvJPEG2000 编码状态 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeStateDestroy()¶
释放编码状态句柄。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeStateDestroy(nvjpeg2kEncodeState_t encode_state);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncodeState_t encode_state |
输入 |
主机 |
nvJPEG2000 编码状态 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeParamsCreate()¶
创建编码参数句柄的实例。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeParamsCreate(nvjpeg2kEncodeParams_t *encode_params);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncodeParams_t *encode_params |
输入 |
主机 |
编码参数句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeParamsDestroy()¶
释放编码参数句柄。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeParamsDestroy(nvjpeg2kEncodeParams_t encode_params);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncodeParams_t encode_params |
输入 |
主机 |
编码参数句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
解析器 API 参考¶
nvjpeg2kStreamParse()¶
此函数是解码 JPEG2000 比特流的第一步。它接受主机内存上的比特流缓冲区作为输入，并解析 JPEG2000 标头信息。解析后的信息存储在 nvjpeg2kStream_t 句柄中，可以通过本节中记录的 API 检索。
签名:
nvjpeg2kStatus_t nvjpeg2kStreamParse(nvjpeg2kHandle_t handle,
const unsigned char *data,
size_t length,
int save_metadata,
int save_stream,
nvjpeg2kStream_t stream_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
库句柄 |
const unsigned char *data |
输入 |
主机 |
比特流缓冲区 |
size_t length |
输入 |
主机 |
比特流大小（字节） |
int save_metadata |
输入 |
主机 |
设置为 0。为将来使用而添加 |
int save_stream |
输入 |
主机 |
设置为 0。为将来使用而添加 |
nvjpeg2kStream_t *stream_handle |
输入 |
主机 |
比特流句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamParseFile()¶
接受磁盘上的 JPEG2000 文件作为输入，并解析 JPEG2000 标头信息。解析后的信息存储在 nvjpeg2kStream_t 句柄中，可以通过本节中记录的 API 检索。
签名:
nvjpeg2kStatus_t nvjpeg2kStreamParseFile(nvjpeg2kHandle_t handle,
const char *filename,
nvjpeg2kStream_t stream_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
库句柄 |
const char *filename |
输入 |
主机 |
磁盘上 JPEG2000 压缩文件名的位置 |
nvjpeg2kStream_t stream_handle |
输入 |
主机 |
比特流句柄 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamGetImageInfo()¶
检索 nvjpeg2kImageInfo_t 中定义的图像信息。此信息对于在设备内存上分配输出缓冲区很有用。
签名:
nvjpeg2kStatus_t nvjpeg2kStreamGetImageInfo(nvjpeg2kStream_t stream_handle,
nvjpeg2kImageInfo_t* image_info);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kStream_t *stream_handle |
输入 |
主机 |
比特流句柄 |
nvjpeg2kImageInfo_t* image_info |
输入/输出 |
主机 |
指向 nvjpeg2kImageInfo_t 的指针 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamGetImageComponentInfo()¶
检索在 nvjpeg2kImageComponentInfo_t 中定义的组件级别信息。此信息可用于在设备内存上分配输出缓冲区。当维度在组件之间变化时，组件级别信息非常有用。
签名
nvjpeg2kStatus_t nvjpeg2kStreamGetImageComponentInfo(nvjpeg2kStream_t stream_handle,
nvjpeg2kImageComponentInfo_t* component_info,
uint32_t component_id);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kStream_t stream_handle |
输入 |
主机 |
比特流句柄 |
nvjpeg2kImageComponentInfo_t* component_info |
输入/输出 |
主机 |
指向 nvjpeg2kImageInfo_t 的指针 |
uint32_t component_id |
输入 |
主机 |
组件索引 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamGetResolutionsInTile()¶
检索瓦片中存在的分辨率数量。分辨率数量定义为：numResolutions = numWaveletDecompositionLevels + 1。jpeg2000 中的瓦片以光栅扫描顺序索引。nvjpeg2kStreamGetImageInfo 检索沿 x 和 y 方向存在的瓦片数量。对于瓦片坐标 tile_x, tile_y：tile_id = tile_y * num_tiles_x + tile_x，其中 tile_x 和 tile_y 以瓦片为单位。
签名
nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionsInTile(
nvjpeg2kStream_t stream_handle,
uint32_t tile_id,
uint32_t* num_res);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kStream_t stream_handle |
输入 |
主机 |
比特流句柄 |
uint32_t tile_id |
输入 |
主机 |
基于光栅扫描的瓦片索引 |
uint32_t* num_res |
输出 |
主机 |
瓦片中存在的分辨率数量 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamGetTileComponentDim()¶
检索瓦片组件的瓦片宽度和瓦片高度。当 图像信息 中的瓦片尺寸不是图像尺寸的倍数时，此函数非常有用。
签名
nvjpeg2kStatus_t nvjpeg2kStreamGetTileComponentDim(
nvjpeg2kStream_t stream_handle,
uint32_t component_id,
uint32_t tile_id,
uint32_t* tile_width,
uint32_t* tile_height);
参数
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamGetResolutionComponentDim()¶
检索瓦片组件在分辨率级别的维度。公式如下
res_scale = 1 << (num_resolutions - res_level - 1)
res_width = (tile_width + res_scale - 1) >> res_scale
res_height = (tile_height + res_scale - 1) >> res_scale
签名
nvjpeg2kStatus_t nvjpeg2kStreamGetResolutionComponentDim(
nvjpeg2kStream_t stream_handle,
uint32_t component_id,
uint32_t tile_id,
uint32_t res_level,
uint32_t* res_width,
uint32_t* res_height);
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kStreamGetColorSpace()¶
从解析的 JP2 文件中检索色彩空间信息。对于 jpeg2000 码流（.j2k 文件），此函数将检索 NVJPEG2K_COLORSPACE_UNKNOWN，因为色彩空间信息不可用。
签名
nvjpeg2kStatus_t nvjpeg2kStreamGetColorSpace(nvjpeg2kStream_t stream_handle,
nvjpeg2kColorSpace_t* color_space);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kStream_t stream_handle |
输入 |
主机 |
比特流句柄 |
nvjpeg2kColorSpace_t* color_space |
输入/输出 |
主机 |
已解析图像的色彩空间 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
解码 API 参考¶
nvjpeg2kDecode()¶
解码单个图像，并将其写入输出设备缓冲区。该函数相对于主机是异步的。所有 GPU 任务都将提交到提供的 stream。在调用此函数之前，用户必须使用 nvjpeg2kStreamParse() 解析码流，以便码流信息存储在 jpeg2k_stream 中。
签名
nvjpeg2kStatus_t nvjpeg2kDecode(nvjpeg2kHandle_t handle,
nvjpeg2kDecodeState_t decode_state,
nvjpeg2kStream_t jpeg2k_stream,
nvjpeg2kImage_t* decode_output,
cudaStream_t stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
库句柄 |
nvjpeg2kDecodeState_t decode_state |
输入 |
主机 |
解码状态句柄 |
nvjpeg2kStream_t jpeg2k_stream |
输入 |
主机 |
nvjpeg2k 比特流句柄 |
nvjpeg2kImage_t* decode_output |
输入/输出 |
主机 |
解码输出结构体。该结构体应位于主机内存中。图像组件指针应指向设备内存。请参阅 图像数据 |
cudaStream_t stream |
输入 |
主机 |
cudaStream_t 的实例。可以设置为 0。 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeImage()¶
解码单个图像，并将其写入输出设备缓冲区。该函数相对于主机是异步的。所有 GPU 任务都将提交到提供的 stream。在调用此函数之前，用户必须使用 nvjpeg2kStreamParse() 解析码流，以便码流信息存储在 jpeg2k_stream 中。可以使用 nvjpeg2kDecodeParams_t 的实例来控制此函数的解码输出。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeImage(nvjpeg2kHandle_t handle,
nvjpeg2kDecodeState_t decode_state,
nvjpeg2kStream_t jpeg2k_stream,
nvjpeg2kDecodeParams_t decode_params,
nvjpeg2kImage_t* decode_output,
cudaStream_t stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
库句柄 |
nvjpeg2kDecodeState_t decode_state |
输入 |
主机 |
解码状态句柄 |
nvjpeg2kStream_t jpeg2k_stream |
输入 |
主机 |
nvjpeg2k 比特流句柄 |
nvjpeg2kDecodeParams_t decode_params |
输入 |
主机 |
用于控制解码输出（例如指定感兴趣区域或启用 RGB 输出）。可以设置为 NULL |
nvjpeg2kImage_t* decode_output |
输入/输出 |
主机 |
解码输出结构体。该结构体应位于主机内存中。图像组件指针应指向设备内存。请参阅 图像数据 |
cudaStream_t stream |
输入 |
主机 |
cudaStream_t 的实例。可以设置为 0。 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeTile()¶
解码图像中的一个瓦片，并将其写入输出设备缓冲区。该函数相对于主机是异步的。所有 GPU 任务都将提交到提供的 stream。在调用此函数之前，用户必须使用 nvjpeg2kStreamParse() 解析码流，以便码流信息存储在 jpeg2k_stream 中。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeTile(nvjpeg2kHandle_t handle,
nvjpeg2kDecodeState_t decode_state,
nvjpeg2kStream_t jpeg2k_stream,
nvjpeg2kDecodeParams_t decode_params,
uint32_t tile_id,
uint32_t num_res_levels,
nvjpeg2kImage_t* decode_output,
cudaStream_t stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kHandle_t handle |
输入 |
主机 |
库句柄 |
nvjpeg2kDecodeState_t decode_state |
输入 |
主机 |
解码状态句柄 |
nvjpeg2kStream_t jpeg2k_stream |
输入 |
主机 |
nvjpeg2k 比特流句柄 |
nvjpeg2kDecodeParams_t decode_params |
输入 |
主机 |
用于控制解码输出（例如指定感兴趣区域）。可以设置为 NULL。 |
uint32_t tile_id |
输入 |
主机 |
基于光栅扫描的瓦片索引 |
uint32_t num_res_levels |
输入 |
主机 |
要在瓦片中解码的分辨率级别数。设置为 0 时，图像以全分辨率解码。瓦片中允许的最大分辨率可以使用 nvjpeg2kStreamGetResolutionsInTile() 确定 |
nvjpeg2kImage_t* decode_output |
输入/输出 |
主机 |
解码输出结构体。该结构体应位于主机内存中。图像组件指针应指向设备内存。请参阅 图像数据 |
cudaStream_t stream |
输入 |
主机 |
cudaStream_t 的实例。可以设置为 0。 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
解码参数 API 参考¶
此类别下的 API 用于初始化作为 nvjpeg2kDecodeParams_t 句柄一部分的解码参数。初始化后，可以将句柄作为输入传递给 nvjpeg2kDecodeTile()
nvjpeg2kDecodeParamsSetDecodeArea()¶
此函数用于设置感兴趣的解码区域。坐标相对于图像原点，并且应在感兴趣的瓦片内。如果坐标设置为 0，则将解码整个瓦片。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetDecodeArea(nvjpeg2kDecodeParams_t decode_params,
uint32_t start_x,
uint32_t end_x,
uint32_t start_y,
uint32_t end_y);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kDecodeParams_t decode_params |
输入/输出 |
主机 |
解码输出参数句柄 |
uint32_t start_x |
输入 |
主机 |
解码区域的左侧坐标 |
uint32_t end_x |
输入 |
主机 |
解码区域的右侧坐标 |
uint32_t start_y |
输入 |
主机 |
解码区域的顶部坐标 |
uint32_t end_y |
输入 |
主机 |
解码区域的底部坐标 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeParamsSetRGBOutput()¶
此函数为具有 422/420 色度子采样的图像启用 RGB 解码输出。对于其他色度子采样值，此函数将被忽略。YCC 到 RGB 的转换基于 sYCC，IEC 61966-2-1 修订版 1。颜色转换应用于瓦片粒度，因此对于具有奇数尺寸的瓦片，色度重建可能不准确。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetRGBOutput(nvjpeg2kDecodeParams_t decode_params,
int32_t enable_RGB);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kDecodeParams_t decode_params |
输入/输出 |
主机 |
解码输出参数句柄 |
int32_t enable_RGB |
输入 |
主机 |
设置为 1 以启用 RGB 输出 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kDecodeParamsSetOutputFormat()¶
此函数可用于设置解码输出格式。应以下列方式分配解码输出缓冲区以支持 NVJPEG2K_FORMAT_INTERLEAVED。
nvjpeg2kImage_t decode_output;
当 decode_output.pixel_type 设置为 NVJPEG2K_UINT8 时， |
当 decode_output.pixel_type 设置为 NVJPEG2K_UINT16 或 NVJPEG2K_INT16 时， |
decode_output.pitch_in_bytes[0] = image_width * num_components * bytes_per_sample;
decode_output.pixel_data[0] = decode_output.decode_out.pitch_in_bytes[0] * info.image_height;
decode_output.num_components = num_components;
对于 NVJPEG2K_FORMAT_INTERLEAVED，当码流使用 420/422 子采样压缩时，解码器要支持该格式，还必须启用 RGB 输出 (nvjpeg2kDecodeParamsSetRGBOutput())。
签名
nvjpeg2kStatus_t nvjpeg2kDecodeParamsSetOutputFormat(nvjpeg2kDecodeParams_t decode_params,
nvjpeg2kImageFormat_t format);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kDecodeParams_t decode_params |
输入/输出 |
主机 |
解码输出参数句柄 |
nvjpeg2kImageFormat_t format |
输入 |
主机 |
默认为 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
编码 API 参考¶
nvjpeg2kEncode()¶
以 JPEG2000 格式压缩输入图像，并将其存储在 encode_state 中。所有 GPU 任务都将提交到提供的 stream。该函数相对于主机是异步的。
签名
nvjpeg2kStatus_t nvjpeg2kEncode(nvjpeg2kEncoder_t enc_handle,
nvjpeg2kEncodeState_t encode_state,
const nvjpeg2kEncodeParams_t encode_params,
const nvjpeg2kImage_t *input_image,
cudaStream_t stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncoder_t enc_handle |
输入 |
主机 |
编码器句柄 |
nvjpeg2kEncodeState_t encode_state |
输入 |
主机 |
编码状态，包含用于编码的中间缓冲区 |
const nvjpeg2kEncodeParams_t encode_params |
输入 |
主机 |
存储控制编码过程的参数 |
const nvjpeg2kImage_t *input_image |
输入 |
主机/设备 |
输入图像。该结构体应位于主机内存中。图像组件指针应指向设备内存。请参阅 图像数据 |
cudaStream_t stream |
输入 |
主机 |
CUDA stream - 用于所有设备操作 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeRetrieveBitstream()¶
从先前由编码器函数使用的编码器状态中检索压缩流。
如果 compressed_data 参数为 NULL，则编码器将在 length 参数中返回压缩的 jpeg2000 码流大小。
如果 compressed_data 不为 NULL，则 length 参数应包含数据缓冲区大小。
如果 length 小于压缩流大小，则将返回错误。否则，压缩流将存储在数据缓冲区中，实际压缩缓冲区大小将存储在 length 参数中。
异步行为
当 compressed_data 参数为 NULL 时，可以认为 API 与主机是同步的
当 compressed_data 参数不为 NULL 时，应用程序应调用 cudaStreamSynchronize() 以确保码流复制成功。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeRetrieveBitstream(
nvjpeg2kEncoder_t enc_handle,
nvjpeg2kEncodeState_t encode_state,
unsigned char *compressed_data,
size_t *length,
cudaStream_t stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncoder_t enc_handle |
输入 |
主机 |
编码器句柄 |
nvjpeg2kEncodeState_t encode_state |
输入 |
主机 |
编码状态，包含用于编码的中间缓冲区 |
unsigned char *data |
输出 |
主机 |
指向主机内存中将存储压缩流的缓冲区的指针。可以为 NULL（请参阅描述）。 |
size_t *length, |
输入/输出 |
主机 |
指向输入缓冲区大小的指针。库将在此参数中更新实际的压缩流大小。 |
cudaStream_t stream |
输入 |
主机 |
CUDA stream - 用于所有设备操作。 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
编码参数 API 参考¶
nvjpeg2kEncodeParamsSetEncodeConfig()¶
设置在 nvjpeg2kEncodeConfig_t 中定义的 JPEG2000 标头参数。应始终在编码过程中调用此函数。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeParamsSetEncodeConfig(
nvjpeg2kEncodeParams_t encode_params,
nvjpeg2kEncodeConfig_t* encode_config);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncodeParams_t encode_params |
输入/输出 |
主机 |
编码参数句柄 |
nvjpeg2kEncodeConfig_t* encode_config |
输入 |
主机 |
指向 nvjpeg2kEncodeConfig_t 的指针 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeParamsSetQuality()¶
当需要有损编码时，此函数允许应用程序设置目标 PSNR 值。
签名
nvjpeg2kStatus_t nvjpeg2kEncodeParamsSetQuality(
nvjpeg2kEncodeParams_t encode_params,
double target_psnr);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncodeParams_t encode_params |
输入/输出 |
主机 |
编码参数句柄 |
double target_psnr |
输入 |
主机 |
目标 PSNR 值，单位为 db |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码
nvjpeg2kEncodeParamsSetInputFormat()¶
此函数可用于设置编码输入格式。应以下列方式分配编码输入缓冲区以支持 NVJPEG2K_FORMAT_INTERLEAVED。
nvjpeg2kImage_t encode_input;
当 encode_input.pixel_type 设置为 NVJPEG2K_UINT8 时， |
当 encode_input.pixel_type 设置为 NVJPEG2K_UINT16 或 NVJPEG2K_INT16 时， |
encode_input.pitch_in_bytes[0] = image_width * num_components * bytes_per_sample;
encode_input.pixel_data[0] = encode_input.pitch_in_bytes[0] * info.image_height;
encode_input.num_components = num_components;
仅当所有组件尺寸相同时，编码器才支持 NVJPEG2K_FORMAT_INTERLEAVED。
签名
nvjpeg2kStatus_t nvjpeg2kEncodearamsSetInputFormat(nvjpeg2kEncodeParams_t encode_params,
nvjpeg2kImageFormat_t format);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvjpeg2kEncodeParams_t encode_params |
输入/输出 |
主机 |
编码参数句柄 |
nvjpeg2kImageFormat_t format |
输入 |
主机 |
默认为 |
返回值
nvjpeg2kStatus_t - API 返回状态码 中指定的错误代码