本插件可实现Windows控制台窗体内显示图像、连贯动画（缓动函数、高斯模糊等），支持不同显示DPI下正确显示。

本插件主要服务于HUOCHAIOSP框架，也可独立使用。

HUOCHAIOSP（HUOCHAI Open Source Project）是作者开发且开源的Windows前端应用程序框架；HARe引擎（HUOCHAI Animation Rendering Engine）是服务于HUOCHAIOSP的图形引擎，是Batch、C++、Python混合引擎；HAReCore是服务于HARe引擎显示功能的图形内核。

访问https://wwbus.lanzouv.com/iiz9C3p9ahkf以获取HAReCore。

HAReCore 使用文档

目录

1. [概述](#1-概述)
2. [运行模式](#2-运行模式)
3. [图片绘制](#3-图片绘制)
4. [GIF 动画](#4-gif-动画)
5. [层叠动画](#5-层叠动画)
6. [动效模块 (Ease)](#6-动效模块-ease)
7. [PagesBlur 模式](#7-pagesblur-模式)
8. [脚本命令](#8-脚本命令)
9. [Batch 端集成](#9-batch-端集成)
10. [完整示例](#10-完整示例)

1. 概述

HAReCore 是一个基于 GDI+ 的 Windows 控制台图片渲染引擎，支持：

• 静态图片显示（PNG/JPG/BMP，含 Alpha 通道半透明）
• GIF 动画播放（支持循环次数和倍速）
• 层叠动画（底图 + 逐帧叠加序列）
• 五次方缓动动画（ease-out / ease-in-out）
• PagesBlur 截屏模糊管线（截屏 → 缩小 → 边缘扩展 → 高斯模糊 → 遮罩 → 半透明输出）
• 脚本批处理（文件 / stdin / 命令行单次执行）

渲染管线: 双缓冲 → 拷屏获取背景 → 逐像素 Alpha 混合 → BitBlt 输出。完全绕开 GDI+ 的 Alpha 语义坑。

2. 运行模式

2.1 单次模式（命令行直接执行）

HAReCore photo.png
HAReCore photo.png?100,200,640,480

显示单张图片后退出。适合快速预览。

2.2 文件模式

HAReCore --file script.txt
HAReCore -f script.txt

逐行读取脚本文件并执行。适合预定义的动画序列。

2.3 批处理模式

HAReCore --batch script.txt

与文件模式相同，但自动关闭逐帧刷新（等效于脚本开头加 __NOPRESENT__），脚本结束后统一 PresentFrame()。适合需要精确控制输出时机的场景。

2.4 stdin 监听模式

HAReCore --listen

从标准输入逐行读取命令。适合由外部进程（如 Python/Node/C# batch 端）通过管道实时驱动。

2.5 PagesBlur 模式

HAReCore --pagesblur
HAReCore --pagesblur "main,255,_dark"

纯 C++ 截屏模糊管线，详见 [第 7 节](#7-pagesblur-模式)。

3. 图片绘制

基本语法

路径?x,y,w,h
路径:x,y,w,h

• ? 分隔符 → 透明模式（有 Alpha 通道时自动做半透明混合）
• : 分隔符 → 不透明模式（GDI+ 直接绘制，忽略 Alpha，更快）

参数说明

参数	类型	默认值	说明
x	int	0	左上角 X 坐标
y	int	0	左上角 Y 坐标
w	int	图片原始宽度	缩放宽度（0 = 原始尺寸）
h	int	图片原始高度	缩放高度（0 = 原始尺寸）

示例

# 原始尺寸显示
HAReCore photo.png

# 在 (100, 200) 位置，缩放到 640×480
HAReCore photo.png?100,200,640,480

# 不透明模式（忽略 Alpha 通道）
HAReCore photo.png:100,200,640,480

脚本中使用

# 背景色
__CLS__0,0,0

# 透明叠加
logo.png?10,10,200,100

# 不透明覆盖
background.jpg:0,0,1920,1080

__FLUSH__

4. GIF 动画

语法

路径?x,y,w,h,loopCount,speed
路径:x,y,w,h,loopCount,speed

参数说明

参数	类型	默认值	说明
x	int	0	左上角 X
y	int	0	左上角 Y
w	int	GIF 原始宽度	缩放宽度
h	int	GIF 原始高度	缩放高度
loopCount	int	1	循环次数（0 = 无限循环）
speed	int	1	倍速（1=原速, 2=2倍速, 5=5倍速）

示例

# 原尺寸，播放 1 次，原速
HAReCore animation.gif

# 缩放到 200×200，播放 3 次，2 倍速
HAReCore animation.gif?0,0,200,200,3,2

# 无限循环，5 倍速
HAReCore animation.gif?50,50,300,300,0,5

脚本中使用

__SIZE__800,600
__CLEAR__0,0,0

# 正常速度播放 1 次
loading.gif?300,200,200,200,1,1

# 无限循环，3 倍速
spinner.gif?350,250,100,100,0,3

5. 层叠动画

语法

__LAYER_ANIM__底图路径?底图x,底图y,底图w,底图h,帧延迟ms,循环次数
叠加帧1路径?x,y,w,h
叠加帧2路径?x,y,w,h
叠加帧3路径?x,y,w,h
...
__LAYER_END__

参数说明

`__LAYER_ANIM__` 头部参数：

参数	类型	默认值	说明
底图路径	string	(必填)	底图文件路径
x	int	0	底图绘制位置 X
y	int	0	底图绘制位置 Y
w	int	底图原始宽度	底图缩放宽度
h	int	底图原始高度	底图缩放高度
帧延迟	int	100	帧间等待时间（毫秒）
循环次数	int	1	播放次数（0 = 无限循环）

叠加帧参数（每行）：

参数	类型	默认值	说明
路径	string	(必填)	叠加图文件路径
x	int	0	叠加位置 X
y	int	0	叠加位置 Y
w	int	图片原始宽度	缩放宽度
h	int	图片原始高度	缩放高度

执行流程（每帧）

1. DrawOpaque(底图)       → 清除上一帧，画底图
2. DrawImageToBuffer(叠加) → Alpha 混合叠加当前帧
3. PresentFrame()         → 输出到屏幕
4. Sleep(帧延迟)          → 等待

示例

# 底图 bg.png 在 (0,0) 800×600，每帧间隔 120ms，播放 1 次
__LAYER_ANIM__bg.png?0,0,800,600,120,1
overlay_01.png?100,200,400,300
overlay_02.png?100,200,400,300
overlay_03.png?100,200,400,300
overlay_04.png?100,200,400,300
__LAYER_END__

效果：bg+01 → bg+02 → bg+03 → bg+04，每帧都是底图重新绘制 + 当前叠加图。

6. 动效模块 (Ease)

6.1 五次方 Ease-Out

__NOPRESENT__
dummy?sx,sy,ex,ey,sw,sh,ew,eh,total_frames,endrounder,canvasW,canvasH#easequint

曲线特征: 先快后慢，动画结束时平滑减速停止。适合 UI 元素弹出、滑入到位。

6.2 五次方 Ease-In-Out

__NOPRESENT__
dummy?sx,sy,ex,ey,sw,sh,ew,eh,total_frames,endrounder,canvasW,canvasH#easeInOutQuint

曲线特征: 对称曲线，先加速后减速。适合滑入滑出、对称过渡。

参数说明

参数	说明
sx, sy	起始位置 (左上角)
ex, ey	结束位置 (左上角)
sw, sh	起始尺寸
ew, eh	结束尺寸
total_frames	缓动计算用的总帧数（越大越平滑）
endrounder	实际输出帧数（最后一帧强制精确目标值）
canvasW, canvasH	画布尺寸

输出格式

每帧输出一行：posX,posY,sizeW,sizeH

# 示例输出（30帧缓动）
2,3,102,102
5,7,105,106
10,14,110,113
...
100,200,200,200    ← 最后一帧强制精确目标

数学原理

Ease-Out: f(t) = 1 - (1 - t)⁵ ，其中 t ∈ [0, 1]

Ease-In-Out:

f(t) = 16t⁵              当 t < 0.5
f(t) = 1 - 16(1-t)⁵      当 t ≥ 0.5

使用整数运算（精度 1/1000），带误差累积补偿，确保动画不会因舍入漂移。

7. PagesBlur 模式

7.1 功能

截取 StuManager 窗口 → 缩小 → 边缘扩展 → 高斯模糊 → 遮罩叠加 → 半透明 → 缩放输出。生成 3 级不同模糊程度的背景图。

7.2 语法

HAReCore --pagesblur
HAReCore --pagesblur "mode,darkMode,saveMark,blurR1,blurR2,blurR3"

7.3 参数说明

参数	说明	默认值
mode	main (800px 宽) 或 mini (520px 宽)	main
darkMode	遮罩颜色：0 = 白色（亮色模式），255 = 黑色（暗色模式）	0
saveMark	输出文件名后缀（用于区分不同场景）	空
blurR1	第 1 级模糊半径	5
blurR2	第 2 级模糊半径	10
blurR3	第 3 级模糊半径	18

7.4 输出文件

保存到 <项目根>/HAREngine/TempPics/ 目录：

文件名	说明
PicBeforeProcessed{mark}.png	原始截屏
PicAfterProcessed1{mark}.png	第 1 级模糊（缩小 0.6×，最清晰）
PicAfterProcessed2{mark}.png	第 2 级模糊（缩小 0.4×，中等）
PicAfterProcessed3{mark}.png	第 3 级模糊（缩小 0.2×，最模糊）

7.5 处理流程

┌─────────────┐
│ StuManager  │ ← FindWindow("StuManager")
│   窗口       │
└──────┬──────┘
       │ BitBlt 截屏
       ▼
┌─────────────┐
│ 原始截屏     │ → 保存 PicBeforeProcessed.png
│ 800×592      │
└──────┬──────┘
       │ 重复 3 次（每次缩小 5px 宽度，高度按比例）
       ▼
  ┌────────────────────────────────────┐
  │ 1. 缩小 (curW × curH)             │
  │ 2. 边缘扩展填充 (EdgeExtendFill)   │ ← 拉伸边缘像素填满画布
  │ 3. 高斯模糊 (3-pass box blur)      │ ← radius 递增: 5 → 10 → 18
  │ 4. 遮罩 + 半透明                   │ ← maskOpacity: 0.03 → 0.06 → 0.09
  │ 5. 缩放输出                        │ ← scale: 0.6 → 0.4 → 0.2
  └────────────────────────────────────┘
       │
       ▼
  PicAfterProcessed1.png  (最清晰)
  PicAfterProcessed2.png  (中等模糊)
  PicAfterProcessed3.png  (最模糊)

7.6 示例

# 默认参数：main 模式，白色遮罩
HAReCore --pagesblur

# 暗色模式，自定义后缀
HAReCore --pagesblur "main,255,_dark_v1"

# mini 窗口，自定义模糊半径
HAReCore --pagesblur "mini,0,_mini,8,15,25"

7.7 Batch 集成

@echo off
REM 生成模糊背景用于 UI 叠加
HAReCore.exe --pagesblur "main,255,_bg_dark"

REM 读取生成的图片作为 UI 背景
(
echo __SIZE__800,592
echo HAREngine\TempPics\PicAfterProcessed2_bg_dark.png:0,0,800,592
echo ui_panel.png?50,50,700,492
echo close_btn.png?700,60,32,32
echo __FLUSH__
) | HAReCore.exe --listen

7.8 窗口查找逻辑

1. 先用 FindWindowW(NULL, L"StuManager") 精确匹配
2. 失败则用 EnumWindows 遍历，模糊匹配标题包含 "StuManager" 的窗口
3. 找不到则输出错误并返回 1

7.9 技术细节

• 高斯模糊: 3-pass box blur 近似，每 pass 水平+垂直两趟滑动窗口，O(w×h) 复杂度
• 边缘扩展: 将缩小后的图片居中，拉伸最左/最右 1 列像素填满水平空白，再拉伸最上/最下 1 行填满垂直空白，避免模糊时出现黑边
• OpenMP 加速: 水平/垂直模糊的写回循环使用 #pragma omp parallel for，大图时自动并行

8. 脚本命令

控制命令

命令	说明
__CLEAR__	清除缓冲区为黑色
__CLS__r,g,b	清除缓冲区为指定颜色
__SIZE__w,h	设置缓冲区尺寸
__NOPRESENT__	关闭自动刷新（进入批处理模式）
__AUTOPRESENT__	重新开启自动刷新
__PRESENT__ / __FLUSH__	手动将缓冲区输出到屏幕
__EXIT__	退出程序
# 注释 / ; 注释 / // 注释	注释行，忽略执行

绘制命令

命令	说明
path?x,y,w,h	透明模式绘制图片
path:x,y,w,h	不透明模式绘制图片
path?x,y,w,h,loop,speed	GIF 动画（透明模式）
__LAYER_ANIM__...	层叠动画（见第 5 节）
path?...#easequint	ease-out 缓动输出（见第 6 节）
path?...#easeInOutQuint	ease-in-out 缓动输出（见第 6 节）

9. Batch 端集成

9.1 Python 示例

单张图片绘制

import subprocess

proc = subprocess.Popen(
    ["HAReCore.exe", "--listen"],
    stdin=subprocess.PIPE,
    text=True
)

# 设置画布
proc.stdin.write("__SIZE__1920,1080\n")
proc.stdin.write("__CLS__30,30,50\n")

# 透明叠加 logo
proc.stdin.write("logo.png?10,10,200,80\n")

# 不透明背景
proc.stdin.write("bg.jpg:0,0,1920,1080\n")

# 提交
proc.stdin.write("__FLUSH__\n")
proc.stdin.flush()

GIF 控制

# 无限循环，3 倍速
proc.stdin.write("spinner.gif?350,250,100,100,0,3\n")

# 播放 2 次，原速
proc.stdin.write("loading.gif?300,200,200,200,2,1\n")

层叠动画

frames = [f"frame_{i:03d}.png" for i in range(1, 61)]

proc.stdin.write("__NOPRESENT__\n")

# 开始层叠动画：底图 + 60帧，每帧 33ms（~30fps），无限循环
proc.stdin.write("__LAYER_ANIM__bg.png?0,0,800,600,33,0\n")
for f in frames:
    proc.stdin.write(f"{f}?100,100,400,400\n")
proc.stdin.write("__LAYER_END__\n")

proc.stdin.write("__AUTOPRESENT__\n")
proc.stdin.flush()

缓动动画驱动

import subprocess

# 启动 HAReCore
proc = subprocess.Popen(
    ["HAReCore.exe", "--listen"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True
)

# 请求缓动计算（30帧，输出30帧）
proc.stdin.write("__NOPRESENT__\n")
proc.stdin.write(
    "dummy?0,0,400,300,100,100,200,200,30,30,800,600#easequint\n"
)
proc.stdin.flush()

# 读取缓动输出
keyframes = []
for _ in range(30):
    line = proc.stdout.readline().strip()
    x, y, w, h = map(int, line.split(","))
    keyframes.append((x, y, w, h))

# 用缓动坐标驱动绘制
proc.stdin.write("__AUTOPRESENT__\n")
for x, y, w, h in keyframes:
    proc.stdin.write(f"__CLEAR__0,0,0\n")
    proc.stdin.write(f"character.png?{x},{y},{w},{h}\n")
    proc.stdin.write("__FLUSH__\n")
    proc.stdin.flush()

PagesBlur 调用

import subprocess

# 生成暗色模式模糊背景
result = subprocess.run(
    ["HAReCore.exe", "--pagesblur", "main,255,_menu"],
    capture_output=True, text=True
)

if result.returncode == 0:
    # 读取生成的图片用于后续 UI 渲染
    proc.stdin.write("HAREngine\\TempPics\\PicAfterProcessed2_menu.png:0,0,800,592\n")
    proc.stdin.write("ui_overlay.png?50,50,700,492\n")
    proc.stdin.write("__FLUSH__\n")
    proc.stdin.flush()

9.2 C# 示例

var psi = new ProcessStartInfo("HAReCore.exe", "--listen")
{
    RedirectStandardInput = true,
    RedirectStandardOutput = true,
    UseShellExecute = false
};
var proc = Process.Start(psi);
var stdin = proc.StandardInput;

stdin.WriteLine("__SIZE__800,600");
stdin.WriteLine("__CLS__0,0,0");
stdin.WriteLine("bg.png:0,0,800,600");

string[] overlays = { "f1.png", "f2.png", "f3.png", "f4.png" };
stdin.WriteLine("__NOPRESENT__");
stdin.WriteLine("__LAYER_ANIM__bg.png?0,0,800,600,80,1");
foreach (var f in overlays)
    stdin.WriteLine($"{f}?200,200,400,300");
stdin.WriteLine("__LAYER_END__");
stdin.WriteLine("__AUTOPRESENT__");
stdin.Flush();

9.3 管道模式（Shell）

# 从文件管道输入
type commands.txt | HAReCore.exe --listen

# Here Document
HAReCore.exe --listen <<EOF
__SIZE__800,600
__CLS__20,20,40
logo.png?10,10,200,80
__FLUSH__
__EXIT__
EOF

10. 完整示例

10.1 静态界面脚本（script_ui.txt）

# 设置画布
__SIZE__1920,1080
__CLS__15,15,25

# 背景（不透明）
background.jpg:0,0,1920,1080

# Logo（透明叠加）
logo.png?20,20,300,120

# 按钮
button_normal.png?800,900,320,80

__FLUSH__
__EXIT__

HAReCore --file script_ui.txt

10.2 帧动画脚本（script_anim.txt）

__SIZE__800,600
__CLS__0,0,0

# 底图 + 逐帧叠加，80ms/帧，循环 3 次
__LAYER_ANIM__bg.png?0,0,800,600,80,3
sprite_001.png?200,150,400,300
sprite_002.png?200,150,400,300
sprite_003.png?200,150,400,300
sprite_004.png?200,150,400,300
sprite_005.png?200,150,400,300
sprite_006.png?200,150,400,300
__LAYER_END__

__EXIT__

HAReCore --file script_anim.txt

10.3 混合脚本（GIF + 静态 + 动画）

__SIZE__1200,800
__CLS__0,0,0

# 不透明背景
wallpaper.jpg:0,0,1200,800

# 透明 Logo
logo.png?50,50,250,100

# GIF 加载动画（无限循环，2倍速）
loading.gif?500,350,200,200,0,2

# 提交
__FLUSH__

# 等外部信号后可继续追加命令...
__EXIT__

10.4 批处理模式（精确帧控制）

HAReCore --batch animation_script.txt

脚本内容（animation_script.txt）：

# 自动进入 __NOPRESENT__ 模式
__SIZE__800,600
__CLS__0,0,0

# 所有绘制命令执行完毕后，统一刷新一次
bg.jpg:0,0,800,600
overlay1.png?100,100,300,200
overlay2.png?400,100,300,200

# --batch 模式下脚本结束自动 PresentFrame()
# 也可以中途手动 __FLUSH__

10.5 stdin 实时交互

# 终端 1: 启动监听
HAReCore.exe --listen

# 终端 2: 通过管道发送命令
echo "__SIZE__800,600" > \\.\pipe\...
# 或直接在同一终端输入:
> __CLS__0,0,0
> photo.png?100,100,400,300
> __FLUSH__
> __EXIT__

10.6 缓动动画脚本

# 弹窗从左侧滑入（ease-out）
__NOPRESENT__
panel.png?0,300,600,300,400,300,400,300,60,45,1920,1080#easequint

# 每行输出: posX,posY,sizeW,sizeH
# batch 端读取后逐帧绘制

HAReCore -f script_ease.txt

10.7 PagesBlur + UI 叠加

@echo off
REM 第一步：生成模糊背景
HAReCore.exe --pagesblur "main,255,_menu"

REM 第二步：在模糊背景上叠加 UI
(
echo __SIZE__800,592
echo HAREngine\TempPics\PicAfterProcessed2_menu.png:0,0,800,592
echo dialog_box.png?100,80,600,430
echo title_text.png?280,100,240,40
echo btn_confirm.png?250,450,140,40
echo btn_cancel.png?410,450,140,40
echo __FLUSH__
) | HAReCore.exe --listen

附录

渲染模式对比

模式	分隔符	Alpha 处理	适用场景
透明	?	自动检测，有 Alpha 则逐像素混合	PNG 图标、叠加层
不透明	:	忽略 Alpha，GDI+ 直接绘制	背景图、大尺寸不透明图片

性能提示

1. 不透明模式更快：对没有 Alpha 通道的大图用 : 分隔符
2. `__NOPRESENT__`：批量绘制时关闭逐帧刷新，最后统一 __FLUSH__
3. 图片缓存：相同路径的图片只加载一次，后续复用内存缓存
4. GIF 缓存：GIF 帧数据和延迟数组全局缓存，重复播放不重新解析
5. 层叠动画：底图每帧重绘，确保清除干净；叠加图越小越快
6. PagesBlur OpenMP：编译时加 -fopenmp 可启用多线程模糊加速

分隔符速查

符号	含义
?	透明模式绘制
:	不透明模式绘制
#	动效函数名分隔（在参数之后）
# (行首)	注释
;	注释
//	注释

命令速查卡

┌─────────────────────────────────────────────────────────────────┐
│                    HAReCore 命令速查                             │
├─────────────────────────────────────────────────────────────────┤
│  运行模式                                                       │
│    --listen                  stdin 监听                         │
│    --file <script>           文件执行                            │
│    --batch <script>          批处理模式（最后统一刷新）           │
│    --pagesblur "args"        截屏模糊管线                       │
│                                                                 │
│  图片                                                           │
│    path?x,y,w,h             半透明                              │
│    path:x,y,w,h             不透明                              │
│    path?x,y,w,h,loop,speed  GIF                                 │
│                                                                 │
│  动效                                                           │
│    path?...#easequint        五次方 ease-out                     │
│    path?...#easeInOutQuint   五次方 ease-in-out                  │
│                                                                 │
│  层叠动画                                                       │
│    __LAYER_ANIM__base?...    开始                                │
│    overlay?x,y,w,h           叠加帧                             │
│    __LAYER_END__              执行                               │
│                                                                 │
│  控制                                                           │
│    __SIZE__w,h               设置缓冲区                         │
│    __CLS__r,g,b              彩色清屏                           │
│    __CLEAR__                 黑色清屏+提交                       │
│    __NOPRESENT__             抑制自动刷新                        │
│    __AUTOPRESENT__           恢复自动刷新                        │
│    __FLUSH__ / __PRESENT__   手动刷新                           │
│    __EXIT__                  退出                                │
│    # / ; / /                 注释                               │
└─────────────────────────────────────────────────────────────────┘