Next: XBM 图像, Previous: 图像格式, Up: 图像   [Contents][Index]

---

42.17.2 图像描述符 ¶

图像描述符(image descriptor) 是一个列表，用于指定图像的底层数据及其显示方式。它通常用作 display 覆盖层或文本属性的值（see 其他显示规范）；而将图像插入缓冲区的便捷辅助函数参见 See 显示图像。

每个图像描述符格式为 (image . props)，其中 props 是由关键字符号与值交替组成的属性列表，至少必须包含指定图像类型的 :type type 键值对。

定义图像尺寸的图像描述符属性 :width、:height、max-width 和 :max-height，取值可以是代表像素尺寸的整数，也可以是 (value . em) 形式的对，其中 value 为以 em 为单位的长度³³。1 em 等于当前字体大小，value 可以是整数或浮点数。此外，尺寸还可以使用 (value . ch) 和 (value . cw) 形式指定，其中 ch 表示标准字符高度，cw 表示标准字符宽度。

以下是对所有图像类型均有效的属性列表（部分属性仅对特定图像类型有效，详见后续小节）：

:type type

图像类型。 See 图像格式. 每个图像描述符都必须包含该属性。

:file file

表示从文件 file 加载图像。若 file 不是绝对路径，则会按照 image-load-path 中的目录依次展开查找（see 定义图像）。

:data data

指定原始图像数据。每个图像描述符必须包含 :data 或 :file 二者之一，不可同时使用。

对大多数图像类型，:data 属性的值应为包含图像数据的字符串。部分图像类型不支持 :data；另一些类型仅靠 :data 不足，需要搭配其他图像属性使用。详情见后续小节。

:margin margin

指定在图像周围添加的额外边距像素数。值 margin 必须是非负数，或此类数字组成的对 (x . y)。若为对，则 x 指定水平边距像素数，y 指定垂直边距像素数。若未指定 :margin，默认为 0。

:ascent ascent

指定图像高度中用作升部的比例—即基线以上的部分。值 ascent 必须是 0 到 100 之间的数字，或符号 center。

若 ascent 为数字，则该百分比的图像高度作为升部。

若 ascent 为 center，图像会围绕中心线垂直居中，该中心线即为应用于图像的文本属性与覆盖层所指定的、在图像位置绘制文本的垂直中心线。

若省略该属性，默认值为 50。

:relief relief

在图像周围添加阴影矩形。值 relief 指定阴影线宽度，单位为像素。若 relief 为负数，阴影会让图像呈现按下按钮的效果；否则呈现未按下效果。

:width width, :height height

:width 和 :height 关键字用于缩放图像。若只指定其中一个，另一个会按比例自动计算以保持纵横比。若两者均指定，纵横比可能不保留。

:max-width max-width, :max-height max-height

:max-width 和 :max-height 关键字用于在图像尺寸超出该值时进行缩放。若已设置 :width，则优先级高于 max-width；若已设置 :height，则优先级高于 max-height，除此之外可按需组合使用这些关键字。

若同时指定 :max-width 和 :height 但未指定 :width，保留纵横比可能导致宽度超出 :max-width。此时会使用更小的高度值，在不超出 :max-width 的同时保持比例。同理，同时指定 :max-height 和 :width 但未指定 :height 时也会如此处理。例如，对一张 200x100 的图像指定 :width 为 400、:max-height 为 150，最终图像会是 300x150：既保留纵横比，又不超出 “最大(max)” 限制。这种参数组合可用于实现 “尽可能大显示图像，但不超出可用显示区域”。

:scale scale

应为图像的缩放系数（数字）。大于 1 的值放大图像，小于 1 的值缩小图像，缩放会同时作用于宽和高。例如，值 0.25 会将图像缩小为原尺寸的四分之一。若缩放后图像超出 :max-width 或 :max-height，最终尺寸不会超过这两个值。若同时指定 :scale 和 :height/:width，宽高会按指定缩放系数调整。

scale 的值也可以是符号 default，表示使用 image-scaling-factor 的值。若该值为数字，则直接作为缩放系数；若为 auto（默认值），则根据 框架默认文本视觉样式所用字体的像素尺寸计算缩放系数（see 底层字体表示）。

具体来说，若默认文本视觉样式字体的像素宽度大于 10，图像会按字体宽度与 10 的比值放大；若字体宽度小于等于 10 像素，则不缩放。例如，默认字体宽度为 15，则图像缩放系数为 1.5。

若未提供 scale，create-image 会根据 image-scaling-factor 的值缩放图像。

:rotation angle

指定旋转角度，单位为度。仅支持 90 度的整数倍，图像类型为 imagemagick 时除外。正值顺时针旋转，负值逆时针旋转。旋转在缩放与裁剪之后执行。

:flip flip

若为 t，图像会水平翻转。当前对 imagemagick 类型图像无效。垂直翻转可通过将图像旋转 180 度并切换该值实现。

:transform-smoothing smooth

若为 t，所有图像变换都会应用平滑处理；若为 nil，则不应用平滑。具体算法依赖平台，但效果等价于双线性过滤。禁用平滑则使用邻近像素算法。

若未指定该属性，create-image 会使用用户选项 image-transform-smoothing 决定是否平滑。该选项可为 nil（不平滑）、t（平滑）或一个谓词函数，函数以图像对象为唯一参数并返回 nil 或 t。默认行为是缩小图像时应用平滑，大幅放大时不应用。

:index frame

See 多框架图像。

:conversion algorithm

指定在显示前应用于图像的转换算法，值 algorithm 为具体算法。

laplace

emboss

指定拉普拉斯边缘检测算法，模糊颜色细微差异并突出较大差异。该效果常用于显示禁用状态按钮的图像。

(edge-detection :matrix matrix :color-adjust adjust) ¶

指定通用边缘检测算法。matrix 必须是包含九个数字的列表或向量。变换后图像中坐标 \(x/y\) 的像素由该位置周围的原始像素计算得出。matrix 为 \(x/y\) 邻域内每个像素指定影响系数；元素 \(0\) 对应 \(x-1/y-1\) 处像素的系数，元素 \(1\) 对应 \(x/y-1\) 处系数，依此类推，如下所示：

  (x-1/y-1  x/y-1  x+1/y-1
   x-1/y    x/y    x+1/y
   x-1/y+1  x/y+1  x+1/y+1)

最终像素由以下方式计算得出：将周围像素的 RGB 值相加，再乘以指定的系数，然后将该总和除以系数绝对值的总和。

拉普拉斯边缘检测当前使用的矩阵为

  (1  0  0
   0  0  0
   0  0 -1)

浮雕边缘检测使用的矩阵为

  ( 2 -1  0
   -1  0  1
    0  1 -2)

disabled

指定对图像进行变换，使其呈现禁用状态的外

:mask mask

若 mask 为 heuristic 或 (heuristic bg)，则为图像创建裁剪蒙版，使框架的背景能在图像后方显示。若未指定 bg，或 bg 为 t，则通过查看图像的四个角来确定其背景色，默认角点中出现频率最高的颜色为图像背景色。否则，bg 必须为列表 (red green blue)，用于指定图像的假定背景色。

若 mask 为 nil，则移除图像上已有的蒙版（若存在）。部分格式的图像包含内置蒙版，可通过指定 :mask nil 将其移除。

:pointer shape

指定鼠标指针悬停在该图像上时的指针形状。See 指针形状，查看可用的指针形状。

:map map ¶

为该图像关联包含 热点区域(hot spots) 的图像映射。

图像映射是一个关联列表，每个元素的格式为 (area id plist)。area 可指定为矩形、圆形或多边形。

矩形是一个序对 (rect . ((x0 . y0) . (x1 . y1))) 用于指定矩形区域左上角和右下角的像素坐标。

圆形是一个序对 (circle . ((x0 . y0) . r)) 用于指定圆形的圆心和半径；r 可为浮点数或整数。

多边形是一个序对 (poly . [x0 y0 x1 y1 ...]) 其中向量中的每一组坐标对应多边形的一个顶点。

当鼠标指针位于图像的热点区域上时，会读取该热点的 plist 属性；若包含 help-echo 属性，则为该热点定义工具提示；若包含 pointer 属性，则定义鼠标指针悬停在该热点上时的形状。 See 指针形状，查看可用的指针形状。

当鼠标指针在热点区域上点击时，会将热点的 id 与鼠标事件组合生成新事件；例如，若热点的 id 为 area4，则事件为 [area4 mouse-1]。

注意：图像映射的坐标应对应完成所有变换（旋转、缩放等）后显示的图像，且 Emacs（默认）会对图像执行自动缩放。因此，为保证坐标匹配，你应在创建图像时指定 :scale 1.0，或使用 image-compute-scaling-factor 的结果计算映射元素。

当图像的 :scale、:rotation 或 :flip 发生改变时，:map 会根据 :original-map 的值与这些变换参数重新计算。

:original-map original-map ¶

指定未经过变换的原始图像映射，用于在图像的 :scale、:rotation 或 :flip 改变后重新计算 :map。

若使用 create-image 创建图像时未指定 :original-map，则会根据传入的 :map 以及非空的 :scale、:rotation 或 :flip 自动计算生成。

反之，若指定了 :original-map 但未指定 :map，则会根据 :original-map、:scale、:rotation 和 :flip 计算生成 :map。

User Option: image-recompute-map-p ¶

将该用户选项设置为 nil，可阻止 Emacs 基于 :original-map 自动重新计算图像的 :map。

Function: image-mask-p spec &optional frame ¶

若图像 spec 包含蒙版位图，该函数返回 t。 frame 为图像将要显示的框架。 frame 为 nil 或省略时，表示使用当前选中框架（see 输入焦点）。

Function: image-transforms-p &optional frame ¶

若 frame 支持图像缩放与旋转，该函数返回非 nil 值。 frame 为 nil 或省略时，表示使用当前选中框架（see 输入焦点）。返回的列表包含表示框架支持的图像变换操作的符号：

scale

frame 通过 :scale、:width、:height、:max-width 和 :max-height 属性支持图像缩放。

rotate90

若旋转角度为 90 度的整数倍，frame 支持图像旋转。

若不支持图像变换，则 :rotation、:crop、:width、:height、:scale、:max-width 和 :max-height 仅可通过 ImageMagick 使用（若可用）（see ImageMagick 图像）。