补强注释

src/source/TetrisRender.cpp

@@ -1,4 +1,9 @@
 #include "stdafx.h"
+/**
+ * @file TetrisRender.cpp
+ * @brief 实现主菜单、帮助页、游戏棋盘、侧栏、覆盖层和升级界面的完整绘制逻辑。
+ */
+
 #include "Tetris.h"
 #include "TetrisRenderInternal.h"
 #include <objidl.h>
@@ -8,6 +13,11 @@
 
 using namespace Gdiplus;
 
+/**
+ * @brief 按颜色缓存粒子画刷，减少动画绘制时重复创建 GDI 对象。
+ * @param color 画刷颜色。
+ * @return 可复用的实心画刷句柄；缓存满时返回临时新建画刷。
+ */
 static HBRUSH GetCachedParticleBrush(COLORREF color)
 {
     static COLORREF cachedColors[16] = {};
@@ -34,11 +44,22 @@ static HBRUSH GetCachedParticleBrush(COLORREF color)
     return CreateSolidBrush(color);
 }
 
+/**
+ * @brief 绘制当前游戏窗口的完整界面。
+ *
+ * 函数按当前屏幕状态绘制主菜单、帮助页、游戏棋盘、侧栏、覆盖层和升级选择。
+ * 由于大量绘图辅助逻辑共享当前缩放、字体和颜色，保持在同一函数内集中管理，
+ * 避免拆分时改变 GDI 对象的选择和释放顺序。
+ *
+ * @param hdc 目标绘图设备上下文。
+ * @param hWnd 当前窗口句柄，用于读取客户区大小。
+ */
 void TDrawScreen(HDC hdc, HWND hWnd)
 {
     RECT clientRect;
     GetClientRect(hWnd, &clientRect);
 
+    // 根据窗口大小计算统一缩放比例，所有坐标都从设计稿尺寸映射到实际窗口。
     int clientWidth = clientRect.right - clientRect.left;
     int clientHeight = clientRect.bottom - clientRect.top;
     int scaleX = MulDiv(clientWidth, 1000, WINDOW_CLIENT_WIDTH);
@@ -119,6 +140,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
     const BYTE panelNestedAlpha = 128;
     const BYTE panelStrongAlpha = 168;
 
+    // 背景图片存在时优先绘制图片并叠加浅色遮罩，否则使用纯色和装饰形状。
     Bitmap* backgroundImage = LoadBackgroundImage();
     if (backgroundImage != nullptr)
     {
@@ -155,6 +177,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         DeleteObject(blobBrushB);
     }
 
+    // 本函数集中创建字体，所有提前 return 分支都要在返回前释放这些 GDI 对象。
     HFONT titleFont = CreateFont(
         -SS(36), 0, 0, 0, FW_BOLD, FALSE, FALSE, FALSE,
         DEFAULT_CHARSET, OUT_OUTLINE_PRECIS, CLIP_DEFAULT_PRECIS, CLEARTYPE_NATURAL_QUALITY,
@@ -178,6 +201,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
     SetBkMode(hdc, TRANSPARENT);
     SetTextColor(hdc, textColor);
 
+    // 以下局部绘图函数共享 hdc、缩放函数和颜色，避免每个小控件重复计算上下文。
     auto DrawPanelCard = [&](const RECT& rect, COLORREF fillColor, COLORREF borderColor, int radius)
     {
         HBRUSH cardBrush = CreateSolidBrush(fillColor);
@@ -312,6 +336,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         DeleteObject(backPen);
     };
 
+    // 主菜单独立绘制并提前返回，避免后续游戏棋盘和侧栏在菜单后面继续绘制。
     if (currentScreen == SCREEN_MENU)
     {
         RECT menuCard =
@@ -439,6 +464,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         return;
     }
 
+    // 帮助、规则、图鉴、致谢和技能演示入口共用规则页卡片框架。
     if (currentScreen == SCREEN_RULES)
     {
         RECT rulesCard =
@@ -2300,6 +2326,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
             DT_LEFT | DT_TOP | DT_WORDBREAK);
     }
 
+    // 暂停和结束覆盖层只盖住棋盘区域，让两侧战斗信息仍然可见。
     if (suspendFlag || gameOverFlag)
     {
         RECT overlayRect =
@@ -2427,6 +2454,7 @@ void TDrawScreen(HDC hdc, HWND hWnd)
         }
     }
 
+    // 升级选择界面在当前战局上方绘制半透明遮罩，保留背景局势作为上下文。
     if (currentScreen == SCREEN_UPGRADE)
     {
         RECT dimRect =