在Qt嵌入式开发中，环境变量QT_QPA_EGLFS_INTEGRATION用于控制 EGLFS（Embedded GL Framework for Systems）平台插件 与底层显示子系统的集成方式。
它主要适用于基于OpenGL ES的无头（Headless）或嵌入式设备场景（如无X11/Wayland的嵌入式Linux系统），尤其在ZynqMP这类SoC方案中，常用于配置Qt应用的图形渲染与显示输出。
一、核心作用
EGLFS是Qt提供的轻量级平台插件，直接通过EGL和KMS/DRM（内核模式设置/直接渲染管理器）与显示硬件交互，避免了X11/Wayland的开销。而 QT_QPA_EGLFS_INTEGRATION的作用是指定EGLFS插件如何与底层的EGL实现、显示控制器（如GPU或显示引擎）以及窗口系统集成，确保Qt应用能正确渲染并输出到目标显示设备。
二、常见取值
QT_QPA_EGLFS_INTEGRATION的取值决定了EGLFS的具体集成策略，常见选项由Qt源码中的 QEglFSIntegration类及其子类实现。
以下是典型值及其适用场景：
1. eglfs_kms（默认值）
-
含义：基于标准的KMS/DRM驱动集成，通过Linux内核的DRM子系统直接管理显示平面（Plane）、CRTC（显示控制器）和编码器（Encoder）。
-
特点：
-
支持多显示器（若硬件允许）；
-
自动检测显示模式（分辨率、刷新率）；
-
支持硬件光标（通过DRM的Cursor Plane）。
-
-
适用场景：大多数通用嵌入式Linux设备（如基于ARM Mali、Adreno或Imagination GPU的设备）。
2. eglfs_kms_atomic
-
含义 ：基于DRM的原子模式设置（Atomic Mode Setting） 集成，通过
drmModeAtomicCommit()接口原子化更新显示配置（而非传统的非原子操作）。 -
特点：
-
支持更复杂的显示配置（如同时修改多个显示参数）；
-
避免部分硬件不支持的中间状态；
-
性能更优（尤其在高帧率或多屏场景）。
-
-
适用场景：支持DRM Atomic的新硬件（如较新的GPU或显示控制器），或需要原子操作的功能（如动态分辨率切换）。
3. eglfs_kms_egldevice
-
含义 ：针对特定EGL设备（EGL Device） 的集成，通常用于GPU厂商提供的专有EGL实现（如Vivante GPU的
gcilib或ARM的Mali EGL）。 -
特点：
-
绕过标准KMS/DRM路径，直接通过厂商提供的EGL扩展（如
EGL_EXT_platform_device）访问GPU； -
可能需要自定义
eglfs_kms_egldevice.json配置文件指定设备节点（如/dev/mali0）。
-
-
适用场景：使用厂商专用GPU（如Vivante GC系列）的嵌入式设备，需厂商提供EGL驱动支持。
4. eglfs_kms_no_hwcursor
-
含义：禁用硬件光标（Hardware Cursor），强制使用软件光标（通过OpenGL ES渲染）。
-
特点：
-
解决部分硬件光标不兼容问题（如光标闪烁、偏移）；
-
软件光标可能增加GPU负载（尤其小尺寸、高频移动场景）。
-
-
适用场景：硬件光标驱动异常时，临时禁用硬件光标以保证显示正常。
5. eglfs_kms_eglm
-
含义 ：针对嵌入式GL模块（EGL Module） 的集成，通常与Qt的
eglfs_kms配合使用，优化EGL上下文的创建与管理。 -
适用场景：较少直接使用，多为Qt内部优化选项。
三、如何选择取值？
选择 QT_QPA_EGLFS_INTEGRATION的值需结合具体硬件和需求，通常步骤如下：
-
确认显示硬件架构：
检查设备的GPU类型（如Mali、Adreno、Vivante）及显示控制器驱动（是否支持KMS/DRM Atomic）。
-
查看Qt日志：
启动Qt应用时设置
QT_LOGGING_RULES=qt.qpa.*=true，日志会输出当前EGLFS使用的集成方式（如QEglFSKmsIntegration表示eglfs_kms）。 -
测试验证：
若默认值（
eglfs_kms）无法正常工作（如黑屏、光标异常），尝试切换至其他模式（如eglfs_kms_atomic或eglfs_kms_egldevice）。
四、相关环境变量与配置
QT_QPA_EGLFS_INTEGRATION需与其他EGLFS相关环境变量配合使用，常见组合：
-
QT_QPA_EGLFS_ALWAYS_SET_MODE=1：强制设置显示模式（即使应用未请求）。 -
QT_QPA_EGLFS_WIDTH/QT_QPA_EGLFS_HEIGHT：手动指定显示分辨率（覆盖自动检测）。 -
QT_QPA_EGLFS_PHYSICAL_WIDTH/QT_QPA_EGLFS_PHYSICAL_HEIGHT：设置屏幕物理尺寸（用于DPI计算）。 -
QT_QPA_EGLFS_ROTATION=90：旋转显示方向（0/90/180/270）。
五、ZynqMP平台的典型应用
在ZynqMP（如XCZU9EG）中，通常使用Xilinx的ARM Mali GPU。此时：
-
若使用Mali GPU，推荐默认
eglfs_kms，利用其KMS/DRM驱动实现硬件加速； -
若需多屏异显或高帧率渲染，可尝试
eglfs_kms_atomic以利用原子模式设置； -
若遇到光标异常，可设置
eglfs_kms_no_hwcursor切换为软件光标。
惠州大亚湾