API 速查
| 函数 | 说明 |
|---|---|
int xgeShapeExMaskGet(xge_shape_ex pShape, int* pMethod, int* pTargetType, xge_shape_ex* ppTargetShape, xge_shape_ex_scene* ppTargetScene) | 查询遮罩状态 |
int xgeShapeExMaskClear(xge_shape_ex pShape) | 清除遮罩 |
编译本章示例
gcc -O2 -I. -o ch57.exe ch57_main.c build\xge.lib -lm -lws2_32 -liphlpapi -lgdi32 -luser32 -lshell32 -lopengl32 -lole32 -lwinmm -lavrt
.\ch57.exe示例：查询与清除遮罩
int iMethod, iTargetType;
xge_shape_ex pMaskShape = NULL;
xge_shape_ex_scene pMaskScene = NULL;
xgeShapeExMaskGet(shape, &iMethod, &iTargetType,
&pMaskShape, &pMaskScene);
if (iTargetType == 0) {
// 无遮罩
} else if (iTargetType == 1) {
// Shape 遮罩 → pMaskShape 有效
} else {
// Scene 遮罩 → pMaskScene 有效
}
// 清除遮罩，恢复正常绘制
xgeShapeExMaskClear(shape);完整代码
将以下代码保存为 ch57_main.c，编译后运行即可看到遮罩查询与清除效果：
#include "xge.h"
static int s_bMasked = 1;
static int s_nFrame = 0;
static int onFrame(void* pUser) {
(void)pUser;
xgeClear(0x081114FF);
s_nFrame++;
// 每 120 帧切换遮罩状态
if (s_nFrame % 120 == 0) s_bMasked = !s_bMasked;
// 遮罩形状
xge_shape_ex mask = NULL;
xgeShapeExCreate(&mask);
xgeShapeExAppendCircle(mask, 400, 300, 180, 180, 1);
xgeShapeExFillColor(mask, 0xFFFFFFFF);
// 内容
xge_shape_ex content = NULL;
xgeShapeExCreate(&content);
xgeShapeExAppendRect(content, 100,100, 600,400, 0,0, 1);
xgeShapeExFillColor(content, 0x4FD8C2FF);
if (s_bMasked) {
xgeShapeExMaskShapeSet(content, mask, XGE_SHAPE_EX_MASK_ALPHA);
}
// 查询遮罩状态
int iMethod, iTargetType;
xge_shape_ex pMS = NULL;
xge_shape_ex_scene pSc = NULL;
xgeShapeExMaskGet(content, &iMethod, &iTargetType, &pMS, &pSc);
xgeShapeExDraw(content, 0.25f);
xgeShapeExDestroy(content);
xgeShapeExDestroy(mask);
return XGE_OK;
}
int main(void) {
xge_desc_t d = {0};
d.iWidth = 800;
d.iHeight = 600;
d.sTitle = "ch57 - Mask Query & Clear";
d.iFlags = XGE_INIT_VSYNC;
xgeInit(&d);
xgeRun(onFrame, NULL);
xgeUnit();
return 0;
}代码讲解
- MaskGet：查询当前遮罩状态（方法/目标类型/目标指针）。
- iTargetType：0=无遮罩，1=Shape 遮罩，2=Scene 遮罩。
- MaskClear：清除遮罩，释放内部引用，恢复正常绘制。
- 切换逻辑：每 120 帧切换遮罩开关，展示有/无遮罩对比。
要点与陷阱
- MaskClear 释放引用：内部对遮罩目标 Release，不影响目标本身的生命周期。
- 查询不增加引用：MaskGet 返回的指针不应手动 Destroy。
- 清除后绘制：MaskClear 后 Draw 不再应用任何遮罩。
- 替换即清除：重新 MaskShapeSet 会自动释放旧遮罩。
进阶练习
- 实现遮罩开关切换：按键切换 MaskClear / MaskShapeSet。
- 在编辑器中显示当前遮罩类型信息面板。
