文章目录Qt Quick 图片加载与 GPU 纹理机制详解QImage、QQuickTextureFactory、QSGTexture 与异步加载一、前言二、先理解 Qt Quick 的图片渲染机制2.1 Qt Widgets 和 Qt Quick 的区别2.2 Qt Quick 图片渲染流程三、QImageQt 图片数据处理类3.1 QImage 是什么3.2 QImage 的内存特点3.3 QImage 和 GPU 的关系四、QQuickTextureFactoryQt Quick 纹理工厂4.1 QQuickTextureFactory 是什么4.2 为什么需要 QQuickTextureFactory4.3 QQuickTextureFactory 常用函数① textureFactoryForImage()② createTexture()③ textureSize()④ textureByteCount()⑤ image()五、QSGTextureQt Quick 场景图纹理5.1 QSGTexture 是什么5.2 QSGTexture 的作用5.3 QSGTexture 与 QSGSimpleTextureNode六、QQuickImageProvider自定义图片提供器6.1 QQuickImageProvider 是什么6.2 自定义图片提供器6.3 QQuickImageProvider 的局限性七、QQuickAsyncImageProvider异步图片加载7.1 什么是异步图片提供器7.2 异步加载流程7.3 QQuickImageResponse 是什么八、QQuickAsyncImageProvider 完整代码示例8.1 定义异步图片响应类8.2 定义异步图片提供器8.3 注册 Provider8.4 QML 使用九、重点分析QQuickTextureFactory::textureFactoryForImage()十、图片异步加载与缩略图预加载优化10.1 为什么需要缩略图预加载10.2 推荐的图片加载架构10.3 缓存策略10.4 控制并发加载数量10.5 优先级管理十一、常见问题及注意事项11.1 QImage 和 QSGTexture 可以直接互相替代吗11.2 QQuickTextureFactory 是不是 GPU 纹理11.3 可以在工作线程直接创建 QSGTexture 吗11.4 QQuickImageProvider 和 QQuickAsyncImageProvider 有什么区别11.5 textureFactoryForImage() 会立即创建 GPU 纹理吗11.6 图片加载完成后为什么还需要 finished()十二、总结十三、官方参考资料Qt Quick 图片加载与 GPU 纹理机制详解QImage、QQuickTextureFactory、QSGTexture 与异步加载一、前言在使用 Qt QuickQML开发图片浏览器、图像处理软件、工业视觉软件时经常需要加载大量图片并将图片显示在 QML 界面中。例如图片浏览器需要批量加载缩略图。工业视觉软件需要显示相机采集的图像。PCB 检测软件需要显示大量检测图片。图像分析软件需要实现图片预览、缩放、平移。大型图片管理软件需要实现异步加载和预加载。如果只是使用 Qt Widgets通常可以通过QPixmap、QLabel等组件完成图片显示。但是 Qt Quick 使用的是另一套渲染体系。Qt Quick 通过 Scene Graph场景图组织界面元素最终通过图形渲染后端将内容绘制到屏幕上。因此图片从磁盘读取到最终显示在 QML 界面上中间涉及多个重要类类主要作用QImage图片数据读取和处理QQuickImageProvider向 QML 提供自定义图片QQuickAsyncImageProvider提供异步图片加载能力QQuickImageResponse管理异步图片请求结果QQuickTextureFactory创建 Qt Quick 可使用的纹理QSGTexture场景图使用的纹理资源QSGNode场景图节点组织渲染内容本文重点介绍这些类的职责、工作流程以及实际使用方法。二、先理解 Qt Quick 的图片渲染机制2.1 Qt Widgets 和 Qt Quick 的区别Qt Widgets 和 Qt Quick 都可以显示图片但底层渲染机制存在区别。Qt Widgets 图片显示QPixmappixmap(test.jpg);ui-label-setPixmap(pixmap);这里主要通过QPixmap和 Widgets 绘制系统完成图片显示。Qt Quick 图片显示Image { source: file:///D:/images/test.jpg width: 400 height: 300 fillMode: Image.PreserveAspectFit }Qt Quick 会将图片加载和界面渲染分开处理。大致过程读取图片文件。将图片解码为图像数据。准备纹理数据。在场景图渲染阶段创建纹理资源。通过 GPU 完成图片绘制。这里需要理解一个关键问题负责读取图片的线程不一定具备创建 GPU 纹理所需要的图形上下文。如果在图片加载线程中直接创建图形纹理就可能出现线程和图形上下文不匹配的问题。Qt Quick 使用QQuickTextureFactory来解决图片加载阶段与纹理创建阶段之间的衔接问题。2.2 Qt Quick 图片渲染流程图片文件 | v QImage 图片解码 | v 准备图片像素数据 | v QQuickTextureFactory | v Qt Quick 场景图渲染线程 | v createTexture() | v QSGTexture | v GPU 图形渲染 | v QML 界面显示这里有三个非常重要的概念QImage保存图片数据。QQuickTextureFactory提供创建纹理的能力。QSGTexture供 Qt Quick 场景图使用的纹理对象。这三个类不是同一个东西也不能相互替代。三、QImageQt 图片数据处理类3.1 QImage 是什么QImage是 Qt 提供的图片数据处理类主要用于图片的读取、存储和像素操作。头文件#includeQImage常见功能加载 PNG、JPG、BMP 等图片。获取图片宽度和高度。获取图片像素数据。修改图片像素。图片缩放和裁剪。图片格式转换。图片保存。例如QImageimage(D:/images/test.jpg);if(image.isNull()){qDebug()图片加载失败;return;}qDebug()宽度image.width();qDebug()高度image.height();qDebug()格式image.format();3.2 QImage 的内存特点QImage 主要管理 CPU 侧的图片数据。例如一张 1920×1080 的 RGBA 图片宽度1920 高度1080 每个像素4 字节理论像素数据大小1920 × 1080 × 4 8,294,400 字节 ≈ 7.91 MiB注意这只是未考虑行对齐、额外元数据和内部存储开销时的理论像素数据大小。QImage 采用隐式共享机制Implicit Sharing多个 QImage 对象可以共享同一份底层数据发生修改时才可能触发数据分离。这有利于降低图片复制的内存开销。3.3 QImage 和 GPU 的关系QImage 本身不是 GPU 纹理。它保存的是图片像素数据通常位于 CPU 可访问的内存中。如果要在 Qt Quick 中显示 QImage需要将图片数据交给 Qt Quick 的纹理创建流程。这就引出了下一个类QQuickTextureFactory。四、QQuickTextureFactoryQt Quick 纹理工厂4.1 QQuickTextureFactory 是什么QQuickTextureFactory是 Qt Quick 模块提供的一个抽象类。主要作用为 QML 图片加载提供纹理创建接口将图片数据与 Qt Quick 的场景图渲染过程连接起来。头文件#includeQQuickTextureFactoryCMakefind_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(MyApp PRIVATE Qt6::Quick)qmakeQT quick这个类继承自 QObject。它本身是一个抽象类不能直接实例化因为其中包含纯虚函数。4.2 为什么需要 QQuickTextureFactory假设图片加载过程如下QImageimage(test.jpg);此时图片已经加载到内存。如果立即创建 GPU 纹理就需要合适的图形渲染上下文。但是图片解码通常可以在普通工作线程中进行而 GPU 纹理创建需要遵循 Qt Quick 渲染后端的线程和资源管理规则。因此Qt 将这两个过程分开图片加载阶段读取图片 | v 解码为 QImage | v 创建纹理工厂渲染阶段Qt Quick 渲染线程 | v 调用 createTexture() | v 创建 QSGTexture | v GPU 渲染QQuickTextureFactory 就是两个阶段之间的桥梁。需要注意Qt 官方文档中的部分描述使用 OpenGL 纹理作为历史背景。现代 Qt 6 的 Qt Quick 还支持基于 QRhi 的不同图形后端例如 Vulkan、Metal、Direct3D 和 OpenGL。实际项目中不应将 QSGTexture 简单等同于某一种图形 API 的纹理对象。4.3 QQuickTextureFactory 常用函数Qt 6 中主要有以下函数函数类型作用textureFactoryForImage()静态函数根据 QImage 创建纹理工厂createTexture()纯虚函数创建 QSGTexturetextureSize()纯虚函数获取纹理尺寸textureByteCount()纯虚函数获取纹理占用的字节数image()虚函数返回纹理对应的 QImage下面分别介绍。① textureFactoryForImage()函数staticQQuickTextureFactory*textureFactoryForImage(constQImageimage);作用将 QImage 包装成 QQuickTextureFactory 对象。示例QImageimage(test.jpg);QQuickTextureFactory*factoryQQuickTextureFactory::textureFactoryForImage(image);如果图片无效函数会返回 nullptr。例如QImage image;QQuickTextureFactory*factoryQQuickTextureFactory::textureFactoryForImage(image);if(!factory){qDebug()纹理工厂创建失败;}这里需要注意textureFactoryForImage()并不是直接返回 QSGTexture而是返回一个纹理工厂。真正创建 QSGTexture 的操作发生在后续渲染阶段。② createTexture()函数virtualQSGTexture*createTexture(QQuickWindow*window)const0;这是 QQuickTextureFactory 最核心的函数之一。作用根据纹理工厂中的图片数据创建 QSGTexture 对象。参数window当前 Qt Quick 窗口提供对应的图形渲染环境。返回值QSGTexture*Qt Quick 场景图使用的纹理对象。这个函数由场景图渲染线程调用。注意不要在普通图片加载线程中随意调用。不要在没有对应渲染环境的情况下直接创建底层图形资源。每次调用都应该返回一个新的、独立的纹理实例。纹理资源的释放也需要遵循 Qt Quick 的渲染资源生命周期规则。③ textureSize()函数virtualQSizetextureSize()const0;作用获取纹理尺寸。示例QSize sizefactory-textureSize();qDebug()纹理宽度size.width();qDebug()纹理高度size.height();例如图片尺寸是 1920×1080width 1920 height 1080该函数可能在任意线程被调用因此不能依赖已经绑定的 OpenGL 上下文。④ textureByteCount()函数virtualinttextureByteCount()const0;作用返回纹理占用的内存字节数。例如intbytesfactory-textureByteCount();qDebug()纹理占用字节数bytes;它可以帮助 Qt Quick 了解纹理的内存开销。注意实际纹理内存大小可能受到像素格式、GPU 对齐、内部存储方式等因素影响不能简单地认为一定等于 width × height × 4。⑤ image()函数virtualQImageimage()const;作用返回这个纹理对应的 QImage。不过这个函数并不常用而且官方文档明确指出它可能比较慢。如果需要返回图片应该确保返回的是自包含的 QImage避免依赖生命周期不确定的外部像素内存。五、QSGTextureQt Quick 场景图纹理5.1 QSGTexture 是什么QSGTexture是 Qt Quick Scene Graph 中的纹理抽象类。它表示可以被场景图渲染节点使用的纹理资源。头文件#includeQSGTexture它与 QQuickTextureFactory 的区别QQuickTextureFactory负责提供创建纹理的能力。QSGTexture表示创建完成后供场景图使用的纹理资源。可以这样理解QImage | v QQuickTextureFactory | v QSGTexture | v Scene Graph | v GPU 渲染5.2 QSGTexture 的作用主要包括保存和管理纹理资源。提供纹理尺寸等信息。供场景图节点引用。支持纹理坐标和纹理采样。配合图形渲染后端完成图片绘制。需要注意QSGTexture 是 Qt Quick 的纹理抽象不建议在普通业务逻辑中直接操作其底层图形资源。5.3 QSGTexture 与 QSGSimpleTextureNode如果需要自定义场景图节点显示图片可以使用QSGSimpleTextureNode。例如QSGSimpleTextureNode*nodenewQSGSimpleTextureNode();node-setTexture(texture);node-setRect(QRectF(0,0,400,300));这里texture是 QSGTexture 对象。setTexture()设置节点使用的纹理。setRect()设置纹理显示区域。最终 Qt Quick 会将这个节点纳入场景图渲染流程。注意QSGNode 及其子类通常需要在场景图渲染线程中创建和操作不能随意跨线程访问。六、QQuickImageProvider自定义图片提供器6.1 QQuickImageProvider 是什么QQuickImageProvider是 Qt Quick 提供的自定义图片提供接口。当 QML 需要加载图片时可以通过自定义 Provider 从数据库、网络、内存缓存或者其他数据源获取图片。头文件#includeQQuickImageProvider常见使用场景从数据库加载图片。从内存缓存加载缩略图。从网络服务器获取图片。根据图片 ID 动态生成图片。加载工业检测系统中的图像数据。6.2 自定义图片提供器例如我们希望通过图片 ID 加载图片。首先定义 ProviderclassMyImageProvider:publicQQuickImageProvider{public:MyImageProvider():QQuickImageProvider(QQuickImageProvider::Image){}QImagerequestImage(constQStringid,QSize*size,constQSizerequestedSize)override{Q_UNUSED(size);Q_UNUSED(requestedSize);QImageimage(QString(D:/images/%1.jpg).arg(id));returnimage;}};然后注册engine.addImageProvider(myimage,newMyImageProvider());QML 中使用Image { source: image://myimage/10001 }当 QML 加载图片时会调用 Provider 的requestImage()。这里的10001就是传入的图片 ID。6.3 QQuickImageProvider 的局限性普通QQuickImageProvider可以实现自定义图片加载但同步请求可能导致调用方等待图片加载完成。如果图片较大或者需要同时加载大量图片就可能影响界面响应。例如用户打开图片列表 | v 同时加载 100 张图片 | v 大量图片解码 | v 界面响应受到影响这种情况下可以考虑异步图片提供器。七、QQuickAsyncImageProvider异步图片加载7.1 什么是异步图片提供器QQuickAsyncImageProvider继承自QQuickImageProvider提供异步图片加载接口。主要作用将耗时的图片读取、解码等工作放到后台执行减少对界面线程的影响。头文件#includeQQuickAsyncImageProvider它的核心接口是virtualQQuickImageResponse*requestImageResponse(constQStringid,constQSizerequestedSize)0;当 QML 发起图片请求时Qt Quick 会调用这个接口。返回一个QQuickImageResponse对象用来管理异步加载过程。7.2 异步加载流程QML Image | v QQuickAsyncImageProvider | v requestImageResponse() | v QQuickImageResponse | v 后台加载图片 | v QImage | v 发出 finished() 信号 | v Qt Quick 获取纹理工厂 | v QQuickTextureFactory | v QSGTexture | v GPU这里有两个重要的类QQuickAsyncImageProvider负责创建异步图片请求。QQuickImageResponse负责保存请求结果并通知 Qt Quick 图片加载已经完成。7.3 QQuickImageResponse 是什么它是异步图片请求的响应类。主要接口virtualQQuickTextureFactory*textureFactory()const0;返回图片对应的纹理工厂。另外还有voidfinished();表示图片加载任务已经完成。以及virtualvoidcancel();用于通知图片请求不再需要。注意即使请求被取消响应对象仍然需要在任务真正结束后发出finished()以便 Qt Quick 正确清理响应对象。不能在后台任务还在运行时提前发出完成信号。八、QQuickAsyncImageProvider 完整代码示例下面通过一个简单的示例演示如何实现异步图片加载。8.1 定义异步图片响应类#includeQQuickImageResponse#includeQQuickTextureFactory#includeQImage#includeQThreadPool#includeQRunnable#includeQMutex#includeQMutexLocker#includeQAtomicIntegerclassMyImageResponse:publicQQuickImageResponse{public:explicitMyImageResponse(constQStringpath):m_path(path){QThreadPool::globalInstance()-start(QRunnable::create([this](){QImageimage(m_path);{QMutexLockerlocker(m_mutex);m_imagestd::move(image);}emitfinished();}));}QQuickTextureFactory*textureFactory()constoverride{QMutexLockerlocker(m_mutex);if(m_image.isNull())returnnullptr;returnQQuickTextureFactory::textureFactoryForImage(m_image);}private:QString m_path;mutableQMutex m_mutex;QImage m_image;};代码核心创建响应对象。在线程池中执行图片读取。将读取结果保存到m_image。发出finished()信号。Qt Quick 在需要时调用textureFactory()。通过 QQuickTextureFactory 返回纹理工厂。说明这是用于理解调用关系的简化示例。生产项目还需要处理响应对象与后台任务之间的生命周期、取消请求、错误信息以及任务完成后的安全清理。不能简单地让后台任务持有裸this指针并假设响应对象在任务结束前一定存在。8.2 定义异步图片提供器classMyAsyncImageProvider:publicQQuickAsyncImageProvider{public:QQuickImageResponse*requestImageResponse(constQStringid,constQSizerequestedSize)override{Q_UNUSED(requestedSize);QString pathQString(D:/images/%1.jpg).arg(id);returnnewMyImageResponse(path);}};这里根据图片 ID 生成图片路径然后创建异步响应对象。8.3 注册 Providerengine.addImageProvider(asyncimage,newMyAsyncImageProvider());8.4 QML 使用Image { source: image://asyncimage/10001 width: 400 height: 300 fillMode: Image.PreserveAspectFit asynchronous: true }这里的图片请求由自定义 Provider 处理。注意QQuickAsyncImageProvider本身已经提供异步响应机制Image.asynchronous不能替代 Provider 内部正确的线程和任务管理。九、重点分析QQuickTextureFactory::textureFactoryForImage()现在回到最初遇到的代码returnQQuickTextureFactory::textureFactoryForImage(m_image);这行代码经常出现在QQuickTextureFactory*MyImageResponse::textureFactory()const{returnQQuickTextureFactory::textureFactoryForImage(m_image);}它的作用就是将已经加载完成的 QImage 包装成 Qt Quick 能够使用的纹理工厂。从源码实现的角度看Qt 会尝试创建适合当前场景图后端的纹理工厂如果没有可用的特定实现则使用默认实现。另外如果传入的 QImage 为空函数会返回 nullptr。因此这行代码并不是直接将 QImage 上传到 GPU而是提供后续纹理创建所需要的对象。可以将它理解为QImage | | 图片像素数据 v textureFactoryForImage() | | 创建纹理工厂 v QQuickTextureFactory | | Qt Quick 在渲染阶段调用 v createTexture() | v QSGTexture | v GPU 渲染这也是 Qt Quick 能够将图片加载与 GPU 纹理创建分离的重要机制。十、图片异步加载与缩略图预加载优化如果开发的是图片浏览器或者工业视觉软件仅仅实现异步加载还不够。因为当图片数量达到几万甚至几十万张时还需要考虑缓存、预加载和内存管理。10.1 为什么需要缩略图预加载假设一个图片列表有 10000 张图片。如果每次用户滚动到某个位置时才开始读取图片用户滚动 | v 读取图片 | v 解码图片 | v 创建纹理 | v 显示缩略图就可能出现图片显示延迟、滚动卡顿等问题。因此可以提前加载当前页面后面的图片。例如m_thumbnailPrefetchPagesqBound(0,config.value(thumbnail_prefetch_pages).toInt(5),20);这行代码表示默认预加载 5 页。最少预加载 0 页。最多预加载 20 页。10.2 推荐的图片加载架构可以将整个图片系统划分为几个模块QML 图片列表 | v 图片加载请求管理器 | -------------- | | v v 缩略图缓存 预加载管理器 | | -------------- | v 任务调度器 | v 线程池解码 | v QImage | v QQuickTextureFactory | v QSGTexture | v GPU各模块的职责模块职责图片列表展示图片和接收用户操作请求管理器管理图片加载请求缩略图缓存避免重复读取和解码预加载管理器提前加载后续图片任务调度器控制并发数量和优先级线程池执行图片读取和解码QImage保存解码后的图片数据QQuickTextureFactory提供纹理创建接口QSGTexture为场景图提供纹理资源10.3 缓存策略建议至少设计两级缓存第一级CPU 图片缓存保存 QImage 数据。优点不需要重复读取磁盘。不需要重复解码图片。可以快速生成纹理工厂。缺点大量图片会占用较多内存。第二级GPU 纹理缓存由 Qt Quick 场景图及其内部机制管理纹理资源。优点避免不必要的重复纹理创建。提高图片重复显示时的效率。缺点受 GPU 显存限制。纹理资源需要遵循场景图生命周期。场景图重建、窗口变化等情况可能影响纹理资源。需要注意Qt Quick 自身已经有图片和纹理缓存机制业务层不应在不了解其行为的情况下重复建立大量 GPU 纹理缓存。10.4 控制并发加载数量如果同时加载大量图片可能导致磁盘 IO 过高。CPU 解码占用过高。内存快速增长。图片请求排队。GPU 纹理上传压力增大。建议使用任务队列控制并发。例如QThreadPool*poolQThreadPool::globalInstance();pool-setMaxThreadCount(4);这里将线程池最大线程数设置为 4。实际项目中应根据 CPU 核数、图片大小、磁盘性能以及其他任务负载进行调整。10.5 优先级管理对于图片浏览器可以设置三种任务优先级优先级任务说明高当前可见区域图片优先保证用户看到的图片中即将进入可见区域的图片提前准备低后续页面预加载空闲时执行这样可以避免后台预加载任务占用所有资源导致当前界面图片无法及时显示。十一、常见问题及注意事项11.1 QImage 和 QSGTexture 可以直接互相替代吗不能。QImage 主要负责图片像素数据处理。QSGTexture 是 Qt Quick 场景图使用的纹理资源。两者处于不同的处理阶段。11.2 QQuickTextureFactory 是不是 GPU 纹理不是。它是纹理工厂负责提供创建纹理的能力。实际创建出来的对象是 QSGTexture。11.3 可以在工作线程直接创建 QSGTexture 吗通常不应该。QSGTexture 属于场景图渲染资源其创建和使用需要遵循 Qt Quick 的渲染线程及图形资源规则。应当让 Qt Quick 在合适的渲染阶段创建纹理。11.4 QQuickImageProvider 和 QQuickAsyncImageProvider 有什么区别对比项QQuickImageProviderQQuickAsyncImageProvider加载方式通过 requestImage 等接口提供图片通过异步响应提供图片主要接口requestImage()requestImageResponse()适用场景简单自定义图片加载大量图片或耗时图片加载响应对象直接返回图片数据QQuickImageResponse纹理工厂可由 Qt Quick 处理图片转换通过 textureFactory() 返回11.5 textureFactoryForImage() 会立即创建 GPU 纹理吗不能这样理解。它创建的是纹理工厂对象。真正创建 QSGTexture 的工作由后续场景图渲染阶段完成。11.6 图片加载完成后为什么还需要 finished()因为 Qt Quick 需要知道异步请求什么时候结束。finished()用于通知引擎响应任务已经完成。随后引擎才可以根据需要获取纹理工厂并继续处理图片显示。十二、总结本文介绍了 Qt Quick 图片加载和 GPU 纹理创建过程中涉及的核心类。可以用下面这张表进行总结类核心职责关键词QImage保存和处理图片CPU 图片数据QQuickImageProvider自定义图片来源图片提供QQuickAsyncImageProvider异步图片请求后台加载QQuickImageResponse管理异步加载结果请求响应QQuickTextureFactory创建纹理的工厂纹理创建QSGTexture场景图纹理资源GPU 渲染QSGNode组织场景图内容渲染节点最重要的是理解下面这条链路图片读取 | v QImage | v QQuickTextureFactory | v QSGTexture | v Qt Quick Scene Graph | v GPU | v QML 图片显示如果开发的是图片浏览器、工业视觉软件或者大规模图片管理系统建议重点掌握QImage 的内存管理和隐式共享机制。QQuickAsyncImageProvider 的异步加载机制。QQuickImageResponse 的任务生命周期管理。QQuickTextureFactory 的纹理创建机制。QSGTexture 的渲染资源管理。缩略图缓存、预加载、并发控制和优先级调度。理解这些内容之后就能够更好地分析 Qt Quick 图片显示延迟、缩略图加载卡顿、CPU 占用过高以及 GPU 纹理资源管理等问题。十三、官方参考资料QQuickTextureFactory 官方文档QQuickImageResponse 官方文档QQuickAsyncImageProvider 官方文档QQuickImageProvider 官方文档QSGTexture 官方文档Qt Quick Scene Graph 官方文档关键词Qt、Qt Quick、QML、QImage、QQuickTextureFactory、QQuickImageProvider、QQuickAsyncImageProvider、QQuickImageResponse、QSGTexture、GPU 渲染、异步图片加载、缩略图预加载。
)
