nodegui 中 QImageFormat 枚举详解：Node.js Qt 图像像素格式的取值、转换与缓冲区导入

桌面应用跨平台【免费下载链接】nodeguiA library for building cross-platform native desktop applications with Node.js and CSS . React NodeGui : https://react.nodegui.org and Vue NodeGui: https://vue.nodegui.org项目地址https://gitcode.com/gh_mirrors/no/nodegui点击查看免费下载在 nodegui基于 Node.js 与 Qt 构建跨平台原生桌面应用中QImageFormat是操作位图数据的基础枚举它决定了QImage内部每个像素在内存中的位深、通道顺序与是否有 Alpha 通道直接影响图像的创建、格式转换convertTo/convertToFormat、无拷贝重解释reinterpretAsFormat以及从外部Buffer快速导入像素QImage.fromBuffer。读完本文你将掌握QImageFormat全部 30 个枚举成员的语义与位深分类、它在 JS 与 C 原生层之间的数值传递方式以及围绕该枚举的常用 API 组合写法。QImageFormat 的定义位置与导出方式QImageFormat在 nodegui 源码中定义于 QImage.ts并随QImage一起从包入口顶层导出见 src/index.ts 中的export { QImage, QImageFormat } from ./lib/QtGui/QImage;。这与 API 文档中的枚举页面 QImageFormat 一一对应。其定义为 TS 数字枚举成员按声明顺序自增赋值Invalid 0之后依次为1、2……该顺序刻意对齐 Qt 原生QImage::Format枚举的取值顺序因此在 JS 层可以直接以数字形式与原生层互转export enum QImageFormat { Invalid, // 0 Mono, // 1 MonoLSB, // 2 Indexed8, // 3 RGB32, // 4 ARGB32, // 5 ARGB32_Premultiplied, // 6 RGB16, // 7 ARGB8565_Premultiplied, // 8 RGB666, // 9 ARGB6666_Premultiplied, // 10 RGB555, // 11 ARGB8555_Premultiplied, // 12 RGB888, // 13 RGB444, // 14 ARGB4444_Premultiplied, // 15 RGBX8888, // 16 RGBA8888, // 17 RGBA8888_Premultiplied, // 18 BGR30, // 19 A2BGR30_Premultiplied, // 20 RGB30, // 21 A2RGB30_Premultiplied, // 22 Alpha8, // 23 Grayscale8, // 24 Grayscale16, // 25 RGBX64, // 26 RGBA64, // 27 RGBA64_Premultiplied, // 28 BGR888, // 29 }30 个枚举成员的位深分类API 文档页面 QImageFormat 列出了全部枚举成员。按位深与用途可归为五类下表汇总了完整取值类别枚举成员说明无效/未初始化Invalid(0)空图像或格式未设置时的默认值1 位单色Mono(1)、MonoLSB(2)黑白位图后者低位在前LSB字节序8 位索引/灰度/透明Indexed8(3)、Alpha8(23)、Grayscale8(24)索引色板图纯 Alpha 通道常作掩膜8 位灰度16 位RGB16(7)每通道约 5 位的低色彩深度24/32 位RGB32(4)、ARGB32(5)、ARGB32_Premultiplied(6)、ARGB8565_Premultiplied(8)、RGB666(9)、ARGB6666_Premultiplied(10)、RGB555(11)、ARGB8555_Premultiplied(12)、RGB888(13)、RGB444(14)、ARGB4444_Premultiplied(15)、RGBX8888(16)、RGBA8888(17)、RGBA8888_Premultiplied(18)、BGR888(29)常规 RGB/ARGB 组合命名中的数字表示各通道位宽30/32 位扩展色深BGR30(19)、A2BGR30_Premultiplied(20)、RGB30(21)、A2RGB30_Premultiplied(22)每通道 10 位的扩展动态范围格式64 位浮点Grayscale16(25)、RGBX64(26)、RGBA64(27)、RGBA64_Premultiplied(28)双精度浮点分量用于 HDR/科学计算场景命名约定值得注意带_Premultiplied后缀的格式表示 RGB 分量已被 Alpha 通道预乘存储R*A、G*A、B*A常见于合成与 GPU 贴图场景RGBX*中的 X 为占位字节不含 Alpha 语义RGBA8888与ARGB32的差异在于通道字节序而非位深。枚举值如何跨越 JS 与 C 边界从 QImage.ts 的构造函数重载看QImageFormat支持四种创建方式空图像、按文件路径加载、按width/height/format创建、按QSize format创建const { QImage, QImageFormat } require(nodegui/nodegui); // 32 位不带 Alpha 的 RGB 图像 const image new QImage(640, 480, QImageFormat.RGB32);在原生层qimage_wrap.cpp 的构造函数直接把 JS 数字Int32Value()强制转换为QImage::Format再交给 Qt 构造真实图像对象} else if (info.Length() 3) { int32_t width info[0].AsNapi::Number(); int32_t height info[1].AsNapi::Number(); QImage::Format format static_castQImage::Format(info[2].AsNapi::Number().Int32Value()); this-instance std::make_uniqueQImage(width, height, format); }反向读取同样以数字回传format()方法qimage_wrap.cpp返回Napi::Number::New(env, this-instance-format())因此 JS 端拿到的正是QImageFormat枚举值本身可以直接用于等值比较const format image.format(); // 例如 QImageFormat.RGB32 if (format QImageFormat.RGB32) { // 无需 Alpha 通道可安全执行 createAlphaMask 之外的位图操作 }这条“数字即枚举”的约定也体现在其他接受格式的 API 上见 QImage 类文档 中convertTo、convertToFormat、reinterpretAsFormat、fromBuffer的参数声明均标注为QImageFormat类型。围绕 QImageFormat 的四个核心用法1. 格式转换convertTo 与 convertToFormatQImage.ts 提供两种转换方式convertTo就地转换会 detach 出独立像素数据convertToFormat返回新图像。二者第二个参数均为ImageConversionFlag默认AutoColorimport { QImage, QImageFormat, ImageConversionFlag } from nodegui/nodegui; // 就地转换为 RGBA8888 image.convertTo(QImageFormat.RGBA8888, ImageConversionFlag.AutoColor); // 或者得到一份 RGBA64 浮点副本 const floatCopy image.convertToFormat(QImageFormat.RGBA64);ImageConversionFlag 定义了转换策略位颜色偏好AutoColor 0x00000000、ColorOnly 0x00000003、MonoOnly 0x00000002、抖动模式DiffuseDither 0、OrderedDither 0x00000010、ThresholdDither 0x00000020、1 位 Alpha 掩膜抖动OrderedAlphaDither 0x00000004、DiffuseAlphaDither 0x00000008以及PreferDither/AvoidDither/AutoDither、NoOpaqueDetection 0x00000100、NoFormatConversion 0x00000200等。当目标格式是Mono、Grayscale8、Indexed8这类低色深格式时抖动标志位会决定降采样质量。原生实现见 qimage_wrap.cpp两个参数都以Int32Value()还原为QImage::Format与Qt::ImageConversionFlag后调用 Qt 对应方法。2. 无拷贝重解释reinterpretAsFormatreinterpretAsFormat(format)QImage.ts改变格式标识但不改写像素数据仅在同位深格式之间有效失败时返回false。典型场景是同一块 32 位内存按不同通道序解读// RGBX8888 与 RGBA8888 同为 32 位可无拷贝切换 const ok image.reinterpretAsFormat(QImageFormat.RGBA8888); if (!ok) { // 位深不同如 32 位转 64 位时必须走 convertTo image.convertTo(QImageFormat.RGBA64); }3. 从外部 Buffer 导入像素QImage.fromBuffer静态方法fromBuffer(buffer, width, height, format)QImage.ts是解码网络数据、视频帧、传感器数据进入 Qt 渲染管线的入口。原生实现见 qimage_wrap.cppNapi::Value StaticQImageWrapMethods::fromBuffer(const Napi::CallbackInfo info) { Napi::Bufferuchar buffer info[0].AsNapi::Bufferuchar(); int32_t width info[1].AsNapi::Number(); int32_t height info[2].AsNapi::Number(); QImage::Format format static_castQImage::Format(info[3].AsNapi::Number().Uint32Value()); auto instance QImageWrap::constructor.New({ Napi::ExternalQImage::New(env, new QImage(QImage(buffer.Data(), width, height, format).copy()))}); return instance; }注意构造后紧接着调用了.copy()Qt 要求外部指针构造的QImage在源缓冲区存活期间有效这里的拷贝保证了即使 Node.js 侧的Buffer被垃圾回收图像数据依然独立避免悬垂内存。使用时需保证buffer.length不小于width * height * 每像素字节数且字节序与所选格式一致const { QImage, QImageFormat } require(nodegui/nodegui); const pixelData Buffer.alloc(320 * 240 * 4); // RGBA88884 字节/像素 const image QImage.fromBuffer(pixelData, 320, 240, QImageFormat.RGBA8888);4. 掩膜与 Alpha 相关格式Alpha8与Mono系列主要服务于位图掩膜场景。createAlphaMask(flags)QImage.ts从带 Alpha 的图像生成 1-bpp 蒙版注释明确指出当图像格式为QImageFormat.Format_RGB32即本枚举的RGB32无 Alpha 通道时返回空图像——这正是hasAlphaChannel()判断与格式选择需要配合使用的原因const hasAlpha image.hasAlphaChannel(); // 由 format() 的结果决定 if (hasAlpha) { const mask image.createAlphaMask(ImageConversionFlag.AutoColor); }选择格式的实用建议常规 UI 显示RGB32不透明、内存 4 字节/像素或ARGB32_Premultiplied需要合成透明效果时。单通道数据灰度图选Grayscale8/Grayscale16纯透明通道选Alpha8黑白图标选Mono。索引色板Indexed8配合colorCount()/color(i)/setColor()管理色表适合颜色数远少于 256 的图形。扩展色深与 HDRRGB30/RGBA64系列注意它们参与reinterpretAsFormat时受同位深限制。从网络/解码器导入始终确认解码器输出的字节序RGBA 还是 BGRA后再传QImageFormat给fromBuffer格式选错会导致通道错位而非报错。相关源码与文档索引内容路径枚举定义与 QImage 包装类src/lib/QtGui/QImage.tsC 原生包装构造、format、fromBuffersrc/cpp/lib/QtGui/QImage/qimage_wrap.cpp顶层导出src/index.ts转换标志位src/lib/QtEnums/ImageConversionFlag/index.ts枚举 API 参考页website/docs/api/generated/enums/qimageformat.mdQImage 类 API 参考页website/docs/api/generated/classes/qimage.md以上用法均基于当前仓库中的 TS 包装层与 NAPI 原生层实现适用前提是使用本仓库构建/发布的nodegui/nodegui原生插件QImageFormat的数值与 Qt 版本中的QImage::Format保持一致跨 Qt 大版本升级时建议以仓库中该枚举定义的实际顺序为准复核。赞分享桌面应用跨平台【免费下载链接】nodeguiA library for building cross-platform native desktop applications with Node.js and CSS . React NodeGui : https://react.nodegui.org and Vue NodeGui: https://vue.nodegui.org项目地址https://gitcode.com/gh_mirrors/no/nodegui点击查看免费下载相关推荐nodegui 中 QIconMode 枚举详解QIcon 图标模式的四个取值、默认值与底层绑定nodegui 中 QIconMode 枚举详解QIcon 图标模式的四个取值、默认值与底层绑定 本文围绕 nodegui 生成的 API 文档页 QIcon桌面应用跨平台Flet Camera 图像格式详解ImageFormatGroup 枚举的成员取值与底层编码原理Flet Camera 图像格式详解ImageFormatGroup 枚举的成员取值与底层编码原理 ImageFormatGroup 是 Flet 官方 fl前端跨平台桌面应用移动开发NodeGui QUrl ParsingMode 枚举详解URL 解析模式的取值、默认值与原生桥接实现NodeGui QUrl ParsingMode 枚举详解URL 解析模式的取值、默认值与原生桥接实现 NodeGui 对 Qt 的 QUrl 类提供了完整的桌面应用跨平台上一篇一键搜索23个磁力站magnetW聚合搜索工具完整指南下一篇磁力链接聚合搜索终极指南如何用magnetW一键搜索23个资源站点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考