这是一个 Windows 当前用户级图片工具。发布版是单 EXE 应用，提供图片预览、轻量编辑、批量转换、Explorer 缩略图注册、默认打开候选和右键图片转换菜单。
.
├─ CMakeLists.txt # 版本号、目标、依赖和构建入口
├─ LICENSE
├─ README.md
├─ .vscode/
│ ├─ launch.json # VS Code Debug 启动配置
│ └─ tasks.json # CMake 配置、Debug、Release、打包任务
├─ scripts/
│ ├─ compile-imgui-shaders.ps1 # 预编译 ImGui DX11 shader
│ ├─ embed-provider.ps1 # 把缩略图 DLL 追加嵌入 EXE
│ ├─ package-release.ps1 # 生成 dist 发布包
│ ├─ refresh-explorer.ps1 # 刷新 Explorer 关联/缩略图缓存
│ ├─ register-user.ps1 # 注册当前用户缩略图 COM 组件
│ └─ unregister-user.ps1 # 取消注册当前用户组件和关联
├─ src/
│ ├─ core/ # 文件类型、解码、编码、图像操作、注册表逻辑
│ ├─ config_gui/ # Win32 + Direct3D 11 + ImGui 主程序
│ ├─ thumb_provider/ # Explorer IThumbnailProvider COM DLL
│ └─ version.h.in # 构建时生成版本头
├─ third_party/
│ ├─ imgui/
│ └─ stb/
├─ build/ # VS 2022/CMake 构建目录，忽略
├─ build-vs2026/ # VS 2026/CMake 构建目录，忽略
├─ dist/ # 发布输出，忽略
└─ local-obj/ # 手工实验 obj 临时目录，忽略
ico.ico 是根目录本地图标副本，已加入忽略；正式程序图标在 src/config_gui/app.ico。
- Windows 10/11 x64
- CMake 3.24 或更新
- Visual Studio 2026 或 Visual Studio 2022，安装 C++ 桌面开发工具
- Windows SDK，需要能找到
fxc.exe
项目使用静态 MSVC 运行库，Release 发布时不依赖额外 VC Runtime。GUI 使用 Direct3D 11，硬件设备创建失败时会尝试 WARP。
版本号集中在根目录 CMakeLists.txt：
project(TextureThumbPreview VERSION 1.0.0 LANGUAGES CXX RC)Windows 文件版本第 4 位可通过 TEXTURE_THUMB_VERSION_BUILD 指定。构建会自动生成 version.h 和 manifest，图片工具箱.exe、TextureThumbProvider.dll、缩略图组件释放目录和发布包名都会使用同一套版本号。
VS 2026 推荐命令：
cmake -S . -B build-vs2026 -G "Visual Studio 18 2026" -A x64
cmake --build build-vs2026 --config Release指定 build 号：
cmake -S . -B build-vs2026 -G "Visual Studio 18 2026" -A x64 -DTEXTURE_THUMB_VERSION_BUILD=12
cmake --build build-vs2026 --config ReleaseVS 2022 可使用：
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release生成发布包：
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\package-release.ps1发布输出：
dist\图片工具箱.exedist\TextureThumbPreview-<version>-win-x64\dist\TextureThumbPreview-<version>-win-x64.zip
图片工具箱.exe 会内嵌 TextureThumbProvider.dll。首次运行或配置缩略图时，程序会把 DLL 自动释放到当前用户目录后注册。
VS Code 里可直接使用任务：
配置 CMake (VS 2026)构建 Debug启动 Debug构建 Release打包 Release
无参数启动进入 配置关联 页：
.\build-vs2026\bin\Release\图片工具箱.exe可为每个扩展名单独勾选：
缩略图：写入 Explorer 当前用户缩略图处理器关联。双击候选：把本程序注册为当前用户的“打开方式/默认应用候选”。图片转换目标格式：控制 Explorer 右键图片转换二级菜单里显示的目标格式。
系统默认应用 按钮会先写入当前勾选的双击候选，再打开 Windows 默认应用设置，并优先定位到本程序的默认值页面。
Windows 10/11 的 UserChoice 有哈希保护。如果某扩展名已有受保护默认应用，本程序不会写入或伪造 UserChoice；需要在系统默认应用设置中确认到 图片工具箱 后，双击文件才会直接打开本程序而不再弹选择框。
单个文件作为命令行参数启动时，自动进入首页预览：
.\build-vs2026\bin\Release\图片工具箱.exe .\test.png也可以在程序里打开图片，或把图片拖进窗口。首页预览支持：
- 适应窗口、重置视图、滚轮缩放、拖拽平移
- 图片边界半透明细框
Alpha 通道显示透明度显示，默认开启并持久记忆- 底栏显示尺寸、文件大小和 Alpha 模式
- 左/右旋转 90°、旋转 180°
- 水平翻转、垂直翻转
- 缩放、裁剪
- 亮度/对比度调整
- 灰度
编辑默认只修改内存中的当前图像副本。保存可选择 另存为 PNG/JPG/BMP/TIFF；覆盖原文件 需要用户明确点击，且仅对当前编码器支持的输出格式生效。
多个文件作为命令行参数启动时，自动进入批量转换：
.\build-vs2026\bin\Release\图片工具箱.exe .\a.blp .\b.tga .\c.png也可以把多个图片拖进窗口，或拖入文件夹扫描。批量转换支持：
- 输入：BMP、TGA、BLP、JPG、PNG、DDS，可选择递归处理子文件夹。
- 输出：BLP1、PNG、JPG、BMP、TIFF、TGA。
- 原文件夹和目标文件夹输入框会本地缓存。
- 可选择保留目标文件夹结构。
- 同名输出文件直接覆盖。
- 后台执行，支持进度显示、取消和失败项重试。
- BLP1 支持自适应 256 色调色板或 JPEG 模式、0/1/4/8-bit alpha、mipmaps 和抖动。
- JPG 不保留 alpha，编码时以白色背景合成。
命令行批量转换：
.\build-vs2026\bin\Release\图片工具箱.exe --batch-convert <原文件夹> <目标文件夹> <目标格式>Explorer 右键二级菜单调用：
.\build-vs2026\bin\Release\图片工具箱.exe --convert-selected-to <目标格式> <文件...>目标格式支持 blp1、png、jpg、bmp、tiff、tga。
- WIC 优先：JPEG、PNG、BMP、GIF、TIFF、ICO、JXR，以及系统已安装 WIC 编解码器的格式。
- 内置 BLP：支持 Warcraft III 常见的 BLP1 JPEG 压缩和 256 色调色板格式，支持 BLP2 DXT 解码。
stb_image兜底：TGA、HDR、PSD、PNM 等部分格式。- WebP、HEIC、AVIF 是否可用取决于系统 WIC 编解码器。
- DDS 目前主要用于解码预览和批量输入，输出仍按目标格式编码。
主要当前用户注册表位置：
- 缩略图 COM：
HKCU\Software\Classes\CLSID\{6B93F7E4-4B22-4A6C-A90F-7AF657A72F28} - 缩略图扩展：
HKCU\Software\Classes\.ext\ShellEx\{E357FCCD-A995-4576-B01F-234630154E96} - 打开方式 ProgID：
HKCU\Software\Classes\TextureThumbPreview.Image - 打开方式候选：
HKCU\Software\Classes\.ext\OpenWithProgids\TextureThumbPreview.Image - 默认应用能力：
HKCU\Software\TextureThumbPreview\Capabilities\FileAssociations - 注册应用入口：
HKCU\Software\RegisteredApplications\图片工具箱 - 应用入口和图标：
HKCU\Software\Classes\Applications\图片工具箱.exe - App Paths：
HKCU\Software\Microsoft\Windows\CurrentVersion\App Paths\图片工具箱.exe - 右键转换菜单：
HKCU\Software\Classes\SystemFileAssociations\.ext\shell\TextureThumbPreview.ConvertSelected - 批量转换路径缓存：
HKCU\Software\TextureThumbPreview\ConfigGui\Batch - 预览显示缓存：
HKCU\Software\TextureThumbPreview\ConfigGui\Viewer
缩略图组件释放目录：
%LocalAppData%\图片工具箱\Provider\<version>\exe-<size>-<timestamp>\
启动诊断日志：
%LocalAppData%\图片工具箱\Logs\startup.log
%LocalAppData%\图片工具箱\Logs\crash.log
如果双击图片仍然弹“选择应用”：
- 在
配置关联勾选对应扩展名的双击候选。 - 点击
应用或系统默认应用。 - 在 Windows 默认应用设置里把扩展名确认到
图片工具箱。
如果 Explorer 缩略图不刷新，可尝试：
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\refresh-explorer.ps1也可以改文件名、刷新目录或重启 Explorer。Explorer 有缩略图缓存，注册成功不一定立刻刷新旧文件。
如果在其他电脑上白屏、无响应或闪退，请先查看：
%LocalAppData%\图片工具箱\Logs\startup.log
%LocalAppData%\图片工具箱\Logs\crash.log
startup.log 会记录 Direct3D、字体和界面初始化进度；发生未处理异常时会写入 crash.log。
在 GUI 中点击 卸载本程序关联，或执行：
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\unregister-user.ps1卸载逻辑只移除本程序拥有或仍指向本程序的当前用户注册表项，不删除其他应用的扩展名配置，不写入或伪造 UserChoice 哈希。
构建验证：
cmake --build build-vs2026 --config Release导出函数验证：
& "C:\Program Files\Microsoft Visual Studio\18\Community\VC\Tools\MSVC\14.50.35717\bin\Hostx64\x64\dumpbin.exe" /exports .\build-vs2026\bin\Release\TextureThumbProvider.dll应看到：
DllCanUnloadNowDllGetClassObjectDllRegisterServerDllUnregisterServer
注册表验证可检查 OpenWithProgids、Applications、Capabilities、SystemFileAssociations 是否写入 HKCU。