avcodec_find_decoder_by_name("h264_cuvid")或"hevc_cuvid"可找到CUVID解码器，但必须手动创建AV_HWDEVICE_TYPE_CUDA类型的hw_device_ctx并赋值给avctx->hw_device_ctx，否则avcodec_open2()必败；CUVID解码器与软解器完全独立，不响应AV_CODEC_ID_H264的通用查找。
直接上结论：avcodec_find_decoder_by_name("h264_cuvid") 或 avcodec_find_decoder_by_name("hevc_cuvid") 能找到解码器，但后续必须手动创建 AVBufferRef* 类型的 CUDA 设备上下文，并正确设置 AVCodecContext::hw_device_ctx，否则 avcodec_open2() 必然失败或 segfault——这不是代码写错了，是硬件解码路径根本没打通。
为什么 avcodec_find_decoder(AV_CODEC_ID_H264) 找不到 cuvid 解码器
FFmpeg 把软硬解码器视为完全独立的编解码器实现。AV_CODEC_ID_H264 对应的是纯软件解码器（如 h264），而 h264_cuvid 是另一个独立注册的解码器，ID 是 AV_CODEC_ID_H264 但名字不同、内部实现完全不同。所以：
-
avcodec_find_decoder(AV_CODEC_ID_H264)返回的是软解器，不是 CUVID - 必须用
avcodec_find_decoder_by_name("h264_cuvid")或"hevc_cuvid" - 调用前建议先
ffmpeg -decoders | grep cuvid确认本地 build 确实含 CUVID 支持
avcodec_open2() 失败的真正原因：hw_device_ctx 为空或无效
CUVID 解码器在初始化时强制检查 avctx->hw_device_ctx 是否为合法的 CUDA 设备引用。它不接受 NULL，也不接受其他类型（如 VDPAU、QSV）的设备上下文。常见错误包括：
- 忘记调用
av_hwdevice_ctx_create()，或传入了错误的AVHWDeviceType（必须是AV_HWDEVICE_TYPE_CUDA） - 调用
av_hwdevice_ctx_create()时未指定device_idx，导致默认选 0 号 GPU，但该卡不支持 HEVC 或驱动版本过低 - 成功创建后，未将返回的
AVBufferRef*赋值给avctx->hw_device_ctx，而是只赋给了局部变量 - 在多线程场景下，多个
AVCodecContext共享同一个hw_device_ctx是安全的，但不能跨进程或跨AVFormatContext混用
CUVID 解码器特有的 AVOption 设置要点
h264_cuvid 和 hevc_cuvid 支持少量关键选项，通过 av_opt_set() 设置，必须在 avcodec_open2() 之前完成：
通过 NVIDIA NIM API 调用 Kimi K2.5 视觉模型分析图像，非常适合为 MiniMax M2.5、GLM-5 等非视觉模型赋予视觉能力。
-
"deint"：去隔行模式，可设为"weave"（默认）、"bob"或"adaptive"；对非隔行源设成"weave"最稳妥 -
"gpu"：显式指定 GPU 编号（字符串形式），例如av_opt_set(avctx, "gpu", "1", 0)，比依赖av_hwdevice_ctx_create()的device_idx更直观 -
"surfaces"：预分配 CUDA 表面数量，默认 25，若解高帧率 4K 视频频繁卡在avcodec_receive_frame()，可尝试提高到 32 或 48 - 注意：这些选项仅对
_cuvid解码器有效，_nvdec（新接口）用法不同，且不兼容旧版驱动
解码输出像素格式只能是 cuda/nv12，别指望直接拿到 CPU 内存
CUVID 解码结果始终在 GPU 显存中，AVFrame::buf[0]->data[0] 指向的是 CUDA device pointer，不是普通内存地址。常见误操作：
- 直接 memcpy 到 CPU 缓冲区 → crash 或脏数据
- 用
sws_scale()转换前没做av_hwframe_transfer_data()→ 输出全黑或随机噪声 - 调用
av_hwframe_transfer_data()前没确保目标AVFrame已通过av_hwframe_get_buffer()分配（或至少av_frame_alloc()+av_frame_get_buffer()配合 CPU 格式） - 最简流程：创建 CPU frame → 调用
av_hwframe_transfer_data(cpu_frame, gpu_frame, 0)→ 再送入 sws 或 OpenGL
最容易被忽略的一点：CUVID 解码器在 Linux 下对 NVIDIA 驱动版本极其敏感——470.x 驱动能跑通 hevc_cuvid，但 450.x 很可能静默失败；Windows 上则要注意 Studio Driver 比 Game Ready Driver 更稳定。别在驱动没验证前花半天调代码。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
