# QPictureBox

**Repository Path**: upcliujie/qpicturebox

## Basic Information

- **Project Name**: QPictureBox
- **Description**: 替代QLabel 的Qt图像显示控件，使用OpenGL渲染，可解决使用QLabel显示在高刷新率大画幅下渲染速度慢的问题
- **Primary Language**: C/C++
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 12
- **Forks**: 5
- **Created**: 2021-04-29
- **Last Updated**: 2025-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QPictureBox

## 介绍

QPictureBox 是一个基于 OpenGL 实现的 Qt 图片显示控件，专为高效显示大分辨率图片而设计。

在 Qt Widgets 中，通常使用 QLabel 显示图片，但当控件尺寸较大时，QLabel 采用 CPU 渲染，容易导致高 CPU 占用和界面卡顿。QPictureBox 利用 GPU 进行渲染，有效解决了这些问题。

## 主要功能

- 基于 OpenGL，使用 GPU 渲染图片，显著降低 CPU 占用。
- 支持高分辨率图片流畅显示，无卡顿。
- 多种缩放与填充模式，满足不同显示需求。
- 可自定义控件背景色与缩放滤波类型。

## 使用说明

1. **集成方式**

   - **源码集成**
     将 QPictureBox 的头文件和源文件添加到工程中，在界面中包含 `qpicturebox.h`，实例化 QPictureBox 对象并插入到你的窗口即可。

   - **动态库集成**
     也可以将 QPictureBox 编译为动态库（如 `.so` 或 `.dll`），在你的项目中链接该动态库，并包含 `qpicturebox.h` 头文件，即可直接使用 QPictureBox 控

2. **设置图片**
   使用 `setImage` 方法设置需要显示的图片，支持以下两种重载形式：
   ```c++
   setImage(QImage &image);           // 从 QImage 对象显示图片
   setImage(const QString &filename); // 从文件路径加载图片
   ```

3. **设置缩放类型**
   通过 `setScaleType(QPictureBox::ScaleType)` 设置图片的缩放/填充方式，支持三种类型：
   - `fitXY`：拉伸填充
   - `fitCenter`：等比例居中填充
   - `CenterCorp`：居中裁剪填充

4. **设置背景色**
   控件默认背景色为黑色，可通过 `setBackGround(QColor color)` 自定义背景颜色。

5. **设置缩放滤波类型**
   通过 `setFilterType(QPictureBox::FilterType)` 设置图片缩放时的滤波类型，以控制缩放时的显示效果。
   `FilterType` 枚举包括以下两种类型：
   - `Nearest`（0x2600）：最近邻插值，缩放时像素边缘较为明显，速度较快，适合对清晰度要求较高或像素风格图片。
   - `Linear`（0x2601）：线性插值，缩放时图像边缘较为平滑，适合大多数普通图片显示需求。

---

如需更多使用示例或详细 API 说明，请参考源码或相关文档。