4. 工程创建与配置
TouchGFX 的量产部署并不是从写界面代码开始的，而是从“工程骨架”开始的。一个配置正确的 CubeMX 工程，决定了后续 TouchGFX 能否顺利集成、屏幕能否点亮、DMA2D 与 LTDC 能否协同工作。本节围绕三条主线展开：CubeMX 生成工程、TouchGFX 集成、屏幕与驱动参数设置。
一、核心原理：三层配置决定显示链路
STM32 上的 TouchGFX 显示链路可以抽象为三层：时钟与电源层、显示控制器层（LTDC/DMA2D）、应用框架层（TouchGFX Generator）。CubeMX 负责前两层，TouchGFX Generator 负责把框架层“挂”到 CubeMX 生成的初始化代码上。三者顺序不能颠倒：时钟不对，LTDC 像素时钟就错；LTDC 时序不对，屏幕花屏或黑屏；Generator 配置不对，TouchGFX 任务无法调度。
因此，工程创建的本质是：先让裸屏能显示纯色，再让 TouchGFX 接管帧缓冲。很多“TouchGFX 不显示”的问题，其实在 CubeMX 阶段就已经埋下。
二、方法流程：从 CubeMX 到 TouchGFX 的六步操作
- 新建 CubeMX 工程：选择与开发板一致的 MCU 型号，开启 HSE 外部晶振，配置 Debug 为 Serial Wire，避免后续无法烧录。
- 配置时钟树：先满足系统主频，再单独配置 LTDC 的像素时钟。以 800×480 屏、60Hz 刷新为例，像素时钟约 33MHz，需通过 PLLSAI 分频得到。
- 开启 LTDC 与 DMA2D：在 Multimedia 中启用 LTDC，设置图层、像素格式、帧缓冲首地址；启用 DMA2D 用于加速填充与混合。
- 配置 SDRAM/FMC：若帧缓冲放在外部 SDRAM，必须先在 FMC 中配置时序参数，并做一次读写测试。
- 生成工程并添加 TouchGFX：在 CubeMX 的 Middleware 中选择 TouchGFX，设置分辨率、颜色深度、帧缓冲数量、OS 类型，然后生成代码。
- 在 TouchGFX Designer 中验证：打开生成的 .touchgfx 工程，添加一个 Box 控件并设置颜色，编译下载，确认屏幕能显示纯色块。
关键顺序：先让 LTDC 显示纯色 → 再让 TouchGFX 接管 → 最后做界面。跳过第一步，后面所有问题都会混在一起，难以定位。
三、参数设置：屏幕与驱动参数对照
屏幕参数来自屏厂规格书，驱动参数来自 MCU 参考手册，两者必须一一对应。下表以常见 800×480 RGB 屏为例，列出关键参数与配置位置。
| 参数 | 典型值 | 配置位置 | 错误后果 |
|---|---|---|---|
| HSYNC / HBP / HFP | 1 / 46 / 210 | LTDC 时序 | 水平偏移、花屏 |
| VSYNC / VBP / VFP | 1 / 23 / 22 | LTDC 时序 | 垂直滚动、撕裂 |
| 像素时钟 | ≈33 MHz | PLLSAI | 闪烁、无显示 |
| 像素格式 | RGB565 | LTDC 图层 | 颜色失真 |
| 帧缓冲地址 | 0xC0000000 | SDRAM 映射 | 黑屏、HardFault |
| TouchGFX 颜色深度 | 16 bpp | Generator | 与 LTDC 不匹配 |
四、案例与复盘：一次“黑屏”的排查
某项目使用 STM32F429 + 800×480 RGB 屏，CubeMX 生成工程后屏幕始终黑屏。排查过程如下：
- 先测背光电压，正常；
- 再用 LTDC 显示纯红色，仍黑屏；
- 检查 PLLSAI 配置，发现像素时钟被误设为 20MHz，远低于屏要求的 33MHz；
- 修正 PLLSAI 后，纯色显示正常；
- 最后重新生成 TouchGFX 工程，界面正常显示。
常见误区：把 TouchGFX 的“颜色深度”与 LTDC 的“像素格式”当成两个独立选项。实际上它们必须一致：LTDC 用 RGB565，TouchGFX 也应选 16bpp，否则会出现颜色错位或花屏。
另一个高频问题是帧缓冲放在内部 SRAM。800×480×2 字节 ≈ 768KB，远超多数 MCU 内部 SRAM，必须外扩 SDRAM。若 SDRAM 时序未配置正确，LTDC 读取帧缓冲时会取到随机数据，表现为雪花点或闪屏。
五、配置检查清单
- HSE 是否开启，时钟树是否锁定；
- LTDC 像素时钟是否与屏规格一致；
- HSYNC/HBP/HFP/VSYNC/VBP/VFP 是否按屏厂参数填写；
- 帧缓冲地址是否落在有效 SDRAM 区域；
- DMA2D 是否使能，中断优先级是否合理；
- TouchGFX Generator 的分辨率、色深、帧缓冲数量是否与 LTDC 一致；
- Touch 控制器 I2C/SPI 是否配置，采样周期是否满足手感要求。
/* LTDC 时序配置示例（CubeMX 生成） */
hltdc.Init.HorizontalSync = 1;
hltdc.Init.VerticalSync = 1;
hltdc.Init.AccumulatedHBP = 47;
hltdc.Init.AccumulatedVBP = 24;
hltdc.Init.AccumulatedActiveW = 847;
hltdc.Init.AccumulatedActiveH = 504;
hltdc.Init.TotalWidth = 1057;
hltdc.Init.TotalHeigh = 526;
hltdc.Init.Backcolor.Blue = 0;
hltdc.Init.Backcolor.Green = 0;
hltdc.Init.Backcolor.Red = 0;
完成以上配置后，工程骨架就具备了“可显示、可调度、可扩展”的基础。后续的界面开发、性能优化与量产烧录，都建立在这一步的正确性之上。