图片支持库

Y++ / YStudio 开发文档 · 一点滴

扁平命令式支持库（不是类）。路径：支持库 → 图片支持库。

约定：图片 = 编码后的图像字节集（PNG / JPEG / BMP / GIF / TIFF / ICO / WebP 等）。命令以字节集进出，不持有句柄。处理后可直接赋给图片框：

图片框1.图片 = 图

底层为 Windows WIC（解码/编码）+ Direct2D / DirectWrite（合成、文字、任意角旋转、绘图）。

相关：图片框 YSS · 摄像头类（取一帧() 得到 JPEG 字节集，可继续用本库处理）。

快速开始

函数 按钮打开.单击 () {
    文本 路径 = 打开文件对话框("选择图片", "", "图片|*.png;*.jpg;*.bmp;*.gif|所有文件|*.*")
    如果 (路径 == "") {
        返回()
    }
    字节集 图 = 图片_读文件(路径)
    如果 (图片_是否有效(图) == 假) {
        输出(图片_取最后错误())
        返回()
    }
    图 = 图片_缩略图(图, 800, 800)
    图 = 图片_画文字(图, "仅供办理", 16, 16, 28, "#CCFFFFFF", "", 0)
    图 = 图片_转JPEG(图, 85)
    图片框1.图片 = 图
    图片_写文件(图, "C:\\out.jpg")
}

约定与错误

约定	说明
失败返回值	字节集命令返回空；逻辑返回假；整数多为 `0`；文本为空
查原因	`图片_取最后错误()`
几何重编码	尽量保持原容器格式；GIF 几何只处理第一帧；ICO / 无法回写时输出 PNG
任意角旋转	非 `0/90/180/270` 时扩大画布（透明底）并输出 PNG
颜色文本	`#RRGGBB` 或 `#AARRGGBB`
像素整数	`0xAARRGGBB`（与 `图片_取像素` / `置像素` / `取主色` 一致）
JPEG 质量	全局用 `图片_置JPEG质量`；`图片_转JPEG` 可传本次质量（`0`=沿用全局，默认约 90）
插值	`0` 近邻 · `1` 线性 · `2` 高质量（默认）· `3` 立方
系统	Windows 10 / 11，x86 / x64

读写与信息

命令	返回	说明
`图片_读文件(路径)`	字节集	校验可解码后返回原文件字节（不重编码）
`图片_写文件(图像, 路径)`	逻辑	原样落盘；扩展名建议与格式一致
`图片_是否有效(图像)`	逻辑	能否被 WIC 解码
`图片_取宽度` / `图片_取高度`	整数	像素尺寸；无效为 0
`图片_取格式(图像)`	文本	`png` / `jpeg` / `bmp` / `gif` / `tiff` / `ico` / `webp` / `unknown`
`图片_取最后错误()`	文本	最近一次失败原因；成功时为空
`图片_是否有透明(图像)`	逻辑	任一像素 Alpha < 255

几何

命令	返回	说明
`图片_缩放(图像, 宽, 高, [插值=2])`	字节集	宽或高为 `0` 时按另一边保持比例
`图片_按比例缩放(图像, 比例, [插值=2])`	字节集	`1`=原大，`0.5`=一半；比例须大于 0 且不超过 64
`图片_裁剪(图像, 左, 上, 宽, 高)`	字节集	宽或高 ≤0 表示取到右/下边缘；区域须落在图内
`图片_旋转(图像, 角度)`	字节集	`0/90/180/270` 精确；其它角度扩大画布→PNG
`图片_翻转(图像, 方向)`	字节集	`1` 水平 · `2` 垂直 · `3` 两者
`图片_缩略图(图像, 最大宽, 最大高)`	字节集	等比缩进框内、不放大；某一边 ≤0 表示不限制该边
`图片_扶正(图像)`	字节集	按拍摄方向摆正；无方向返回原字节；读文件不自动扶正
`图片_扩展画布(图像, 左, 上, 右, 下, [颜色=""])`	字节集	四周加边不缩放；空颜色=透明

字节集 小 = 图片_缩放(图, 320, 0)           // 宽 320，高按比例
字节集 半 = 图片_按比例缩放(图, 0.5, 1)     // 线性插值
字节集 块 = 图片_裁剪(图, 10, 20, 0, 80)    // 宽取到右边缘，高 80
字节集 转 = 图片_旋转(图, 90)
字节集 镜 = 图片_翻转(图, 1)
字节集 缩 = 图片_缩略图(图, 160, 160)

绘制与合成

命令	返回	说明
`图片_创建(宽, 高, [颜色=\"\"])`	字节集	空白 PNG；空颜色=全透明
`图片_绘制(底图, 图层, 左, 上, [透明度=100], [宽=0], [高=0])`	字节集	贴图层；宽/高>0 时拉伸，只给一边则保持图层比例
`图片_画文字(图像, 内容, 左, 上, [字号=16], [颜色], [字体], [对齐=0])`	字节集	对齐：`0` 左 · `1` 中 · `2` 右；字体空=微软雅黑
`图片_填充矩形(图像, 左, 上, 宽, 高, 颜色)`	字节集	填充矩形
`图片_画线(图像, x1, y1, x2, y2, 颜色, [线宽=1])`	字节集	线宽 1–64
`图片_画圆(图像, 圆心左, 圆心上, 半径, 颜色, [填充=1])`	字节集	`1` 实心 · `0` 空心
`图片_九宫格(图像, 左, 上, 右, 下, 目标宽, 目标高)`	字节集	四角不变形拉伸；输出 PNG
`图片_圆角(图像, 半径)`	字节集	四角透明圆角；`0` 返回原字节；输出 PNG
`图片_描边矩形(图像, 左, 上, 宽, 高, 颜色, [线宽=1])`	字节集	空心矩形，线宽 1–64

字节集 画布 = 图片_创建(800, 600, "#FF202020")
字节集 合 = 图片_绘制(画布, 水印, 20, 20, 80, 120, 0)  // 宽 120，高按比例
字节集 出 = 图片_画文字(合, "YStudio", 400, 16, 28, "#FFFFFFFF", "", 1)
出 = 图片_填充矩形(出, 8, 8, 120, 40, "#CCFF8800")
出 = 图片_画线(出, 0, 0, 200, 80, "#FFFF0000", 2)
出 = 图片_画圆(出, 80, 80, 36, "#FF3399FF", 0)
图片框1.图片 = 图片_九宫格(皮肤, 8, 8, 8, 8, 240, 64)

滤镜与色彩

命令	返回	说明
`图片_灰度(图像)`	字节集	灰度
`图片_反色(图像)`	字节集	反相（保留 Alpha）
`图片_亮度(图像, 增量)`	字节集	`-100..100`，`0` 返回原字节
`图片_对比度(图像, 增量)`	字节集	同上
`图片_饱和度(图像, 增量)`	字节集	同上；`-100` 接近灰度
`图片_模糊(图像, 半径)`	字节集	`0..32`，`0` 返回原字节
`图片_锐化(图像, [强度=50])`	字节集	`0..100`，`0` 返回原字节
`图片_色相(图像, 偏移)`	字节集	`-180..180` 度，`0` 返回原字节
`图片_去背景色(图像, 颜色, [容差=32])`	字节集	接近色变透明；容差 `0..255`
`图片_置透明度(图像, 透明度)`	字节集	整图 Alpha 按百分比缩放；`100` 不变
`图片_马赛克(图像, 块大小, [左=0], [上=0], [宽=0], [高=0])`	字节集	块大小 1–256；宽/高≤0 到边缘

图片框1.图片 = 图片_灰度(图)
图片框1.图片 = 图片_亮度(图, 20)
图片框1.图片 = 图片_模糊(图, 3)
图片框1.图片 = 图片_去背景色(图, "#FFFFFFFF", 24)

格式转换

命令	返回	说明
`图片_转PNG` / `转BMP` / `转GIF` / `转WebP`	字节集	失败返回空（不静默回退成 PNG）
`图片_转JPEG(图像, [质量=0])`	字节集	`1..100` 仅本次；`0` 沿用全局
`图片_置JPEG质量(质量)`	逻辑	`1..100`，影响后续 JPEG 编码

转WebP 依赖系统 WIC 编码器。Windows 10 通常只有 WebP 解码器、没有编码器，这条会失败；Windows 11 才有编码器。失败时看 图片_取最后错误()。

像素

命令	返回	说明
`图片_取像素(图像, 左, 上)`	整数	`0xAARRGGBB`；越界返回 0
`图片_置像素(图像, 左, 上, 颜色)`	字节集	返回新图
`图片_取像素数据(图像)`	字节集	BGRA 行主序，步长=`宽×4`
`图片_从像素数据(宽, 高, 像素)`	字节集	重建为 PNG；长度须为 `宽×高×4`
`图片_取主色(图像)`	整数	平均色 `0xAARRGGBB`

整数 c = 图片_取像素(图, 0, 0)
图 = 图片_置像素(图, 10, 10, 0xFFFF0000)
字节集 px = 图片_取像素数据(图)
整数 w = 图片_取宽度(图)
整数 h = 图片_取高度(图)
图片框1.图片 = 图片_从像素数据(w, h, px)

剪贴板

命令	返回	说明
`图片_读剪贴板()`	字节集	优先 PNG 格式，否则 DIB→PNG
`图片_写剪贴板(图像)`	逻辑	写入 PNG + DIB（会改系统剪贴板）

与「剪贴板支持库」的路径/文本 API 独立；本库面向图像字节集。

多帧（GIF）

命令	返回	说明
`图片_取帧数(图像)`	整数	普通图为 1
`图片_取帧(图像, 索引)`	字节集	指定帧→PNG；索引从 0 起
`图片_取帧延时(图像, 索引)`	整数	GIF 帧延时（毫秒）；无元数据时可能为 0

几何/滤镜仍按第一帧处理；要处理动图请先 取帧 再处理。

与图片框 / 摄像头

// 文件 → 处理 → 显示
字节集 图 = 图片_读文件(路径)
图片框1.图片 = 图片_灰度(图)

// 摄像头抓拍 JPEG → 本库
摄像头类 cam
cam.打开(0)
字节集 jpg = cam.取一帧()
图片框1.图片 = 图片_缩略图(jpg, 640, 480)

// 嵌入资源（见 resource-embed.md）
图片框1.图片 = 到字节集(":/img/logo.png")

图片框负责显示模式（拉伸/等比等）；本库负责像素处理。实时摄像头预览请用 cam.开始预览(图片框)，不要每帧走本库编解码。

注意

大图会占内存：缩放/滤镜先解码为 32bpp BGRA。可用 图片_缩略图 先缩小再处理。
图片_读文件 不重编码；缩放/滤镜/绘制 等会重编码。
图片_扶正 按 EXIF 拍摄方向摆正；图片_读文件 不会自动调用。
写入剪贴板会覆盖用户当前剪贴板内容。
命令签名以 IDE 支持库 → 图片支持库 面板为准。