diff options
Diffstat (limited to 'devdocs/elisp/image-descriptors.html')
| -rw-r--r-- | devdocs/elisp/image-descriptors.html | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/devdocs/elisp/image-descriptors.html b/devdocs/elisp/image-descriptors.html new file mode 100644 index 00000000..307e1a11 --- /dev/null +++ b/devdocs/elisp/image-descriptors.html @@ -0,0 +1,46 @@ + <h4 class="subsection">Image Descriptors</h4> <p>An <em>image descriptor</em> is a list which specifies the underlying data for an image, and how to display it. It is typically used as the value of a <code>display</code> overlay or text property (see <a href="other-display-specs">Other Display Specs</a>); but See <a href="showing-images">Showing Images</a>, for convenient helper functions to insert images into buffers. </p> <p>Each image descriptor has the form <code>(image . <var>props</var>)</code>, where <var>props</var> is a property list of alternating keyword symbols and values, including at least the pair <code>:type <var>type</var></code> that specifies the image type. </p> <p>Image descriptors which define image dimensions, <code>:width</code>, <code>:height</code>, <code>:max-width</code> and <code>:max-height</code>, may take either an integer, which represents the dimension in pixels, or a pair <code>(<var>value</var> . em)</code>, where <var>value</var> is the dimension’s length in <em>ems</em><a id="DOCF27" href="#FOOT27"><sup>27</sup></a>. One em is equivalent to the height of the font and <var>value</var> may be an integer or a float. </p> <p>The following is a list of properties that are meaningful for all image types (there are also properties which are meaningful only for certain image types, as documented in the following subsections): </p> <dl compact> <dt><code>:type <var>type</var></code></dt> <dd> +<p>The image type. See <a href="image-formats">Image Formats</a>. Every image descriptor must include this property. </p> </dd> <dt><code>:file <var>file</var></code></dt> <dd> +<p>This says to load the image from file <var>file</var>. If <var>file</var> is not an absolute file name, it is expanded relative to the <samp>images</samp> subdirectory of <code>data-directory</code>, and failing that, relative to the directories listed by <code>x-bitmap-file-path</code> (see <a href="face-attributes">Face Attributes</a>). </p> </dd> <dt><code>:data <var>data</var></code></dt> <dd> +<p>This specifies the raw image data. Each image descriptor must have either <code>:data</code> or <code>:file</code>, but not both. </p> <p>For most image types, the value of a <code>:data</code> property should be a string containing the image data. Some image types do not support <code>:data</code>; for some others, <code>:data</code> alone is not enough, so you need to use other image properties along with <code>:data</code>. See the following subsections for details. </p> </dd> <dt><code>:margin <var>margin</var></code></dt> <dd> +<p>This specifies how many pixels to add as an extra margin around the image. The value, <var>margin</var>, must be a non-negative number, or a pair <code>(<var>x</var> . <var>y</var>)</code> of such numbers. If it is a pair, <var>x</var> specifies how many pixels to add horizontally, and <var>y</var> specifies how many pixels to add vertically. If <code>:margin</code> is not specified, the default is zero. </p> </dd> <dt><code>:ascent <var>ascent</var></code></dt> <dd> +<p>This specifies the amount of the image’s height to use for its ascent—that is, the part above the baseline. The value, <var>ascent</var>, must be a number in the range 0 to 100, or the symbol <code>center</code>. </p> <p>If <var>ascent</var> is a number, that percentage of the image’s height is used for its ascent. </p> <p>If <var>ascent</var> is <code>center</code>, the image is vertically centered around a centerline which would be the vertical centerline of text drawn at the position of the image, in the manner specified by the text properties and overlays that apply to the image. </p> <p>If this property is omitted, it defaults to 50. </p> </dd> <dt><code>:relief <var>relief</var></code></dt> <dd> +<p>This adds a shadow rectangle around the image. The value, <var>relief</var>, specifies the width of the shadow lines, in pixels. If <var>relief</var> is negative, shadows are drawn so that the image appears as a pressed button; otherwise, it appears as an unpressed button. </p> </dd> <dt><code>:width <var>width</var>, :height <var>height</var></code></dt> <dd> +<p>The <code>:width</code> and <code>:height</code> keywords are used for scaling the image. If only one of them is specified, the other one will be calculated so as to preserve the aspect ratio. If both are specified, aspect ratio may not be preserved. </p> </dd> <dt><code>:max-width <var>max-width</var>, :max-height <var>max-height</var></code></dt> <dd> +<p>The <code>:max-width</code> and <code>:max-height</code> keywords are used for scaling if the size of the image exceeds these values. If <code>:width</code> is set, it will have precedence over <code>max-width</code>, and if <code>:height</code> is set, it will have precedence over <code>max-height</code>, but you can otherwise mix these keywords as you wish. </p> <p>If both <code>:max-width</code> and <code>:height</code> are specified, but <code>:width</code> is not, preserving the aspect ratio might require that width exceeds <code>:max-width</code>. If this happens, scaling will use a smaller value for the height so as to preserve the aspect ratio while not exceeding <code>:max-width</code>. Similarly when both <code>:max-height</code> and <code>:width</code> are specified, but <code>:height</code> is not. For example, if you have a 200x100 image and specify that <code>:width</code> should be 400 and <code>:max-height</code> should be 150, you’ll end up with an image that is 300x150: Preserving the aspect ratio and not exceeding the “max” setting. This combination of parameters is a useful way of saying “display this image as large as possible, but no larger than the available display area”. </p> </dd> <dt><code>:scale <var>scale</var></code></dt> <dd> +<p>This should be a number, where values higher than 1 means to increase the size, and lower means to decrease the size, by multiplying both the width and height. For instance, a value of 0.25 will make the image a quarter size of what it originally was. If the scaling makes the image larger than specified by <code>:max-width</code> or <code>:max-height</code>, the resulting size will not exceed those two values. If both <code>:scale</code> and <code>:height</code>/<code>:width</code> are specified, the height/width will be adjusted by the specified scaling factor. </p> </dd> <dt><code>:rotation <var>angle</var></code></dt> <dd> +<p>Specifies a rotation angle in degrees. Only multiples of 90 degrees are supported, unless the image type is <code>imagemagick</code>. Positive values rotate clockwise, negative values counter-clockwise. Rotation is performed after scaling and cropping. </p> </dd> <dt><code>:transform-smoothing <var>smooth</var></code></dt> <dd> +<p>If this is <code>t</code>, any image transform will have smoothing applied; if <code>nil</code>, no smoothing will be applied. The exact algorithm used is platform dependent, but should be equivalent to bilinear filtering. Disabling smoothing will use the nearest neighbor algorithm. </p> <p>If this property is not specified, <code>create-image</code> will use the <code>image-transform-smoothing</code> user option to say whether scaling should be done or not. This option can be <code>nil</code> (no smoothing), <code>t</code> (use smoothing) or a predicate function that’s called with the image object as the only parameter, and should return either <code>nil</code> or <code>t</code>. The default is for down-scaling to apply smoothing, and for large up-scaling to not apply smoothing. </p> </dd> <dt><code>:index <var>frame</var></code></dt> <dd> +<p>See <a href="multi_002dframe-images">Multi-Frame Images</a>. </p> </dd> <dt><code>:conversion <var>algorithm</var></code></dt> <dd> +<p>This specifies a conversion algorithm that should be applied to the image before it is displayed; the value, <var>algorithm</var>, specifies which algorithm. </p> <dl compact> <dt><code>laplace</code></dt> <dt><code>emboss</code></dt> <dd> +<p>Specifies the Laplace edge detection algorithm, which blurs out small differences in color while highlighting larger differences. People sometimes consider this useful for displaying the image for a disabled button. </p> </dd> <dt><code>(edge-detection :matrix <var>matrix</var> :color-adjust <var>adjust</var>)</code></dt> <dd> + <p>Specifies a general edge-detection algorithm. <var>matrix</var> must be either a nine-element list or a nine-element vector of numbers. A pixel at position <em>x/y</em> in the transformed image is computed from original pixels around that position. <var>matrix</var> specifies, for each pixel in the neighborhood of <em>x/y</em>, a factor with which that pixel will influence the transformed pixel; element <em>0</em> specifies the factor for the pixel at <em>x-1/y-1</em>, element <em>1</em> the factor for the pixel at <em>x/y-1</em> etc., as shown below: </p> +<div class="display"> <pre class="display"> (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) +</pre> +</div> <p>The resulting pixel is computed from the color intensity of the color resulting from summing up the RGB values of surrounding pixels, multiplied by the specified factors, and dividing that sum by the sum of the factors’ absolute values. </p> <p>Laplace edge-detection currently uses a matrix of </p> +<div class="display"> <pre class="display"> (1 0 0 + 0 0 0 + 0 0 -1) +</pre> +</div> <p>Emboss edge-detection uses a matrix of </p> +<div class="display"> <pre class="display"> ( 2 -1 0 + -1 0 1 + 0 1 -2) +</pre> +</div> </dd> <dt><code>disabled</code></dt> <dd><p>Specifies transforming the image so that it looks disabled. </p></dd> </dl> </dd> <dt><code>:mask <var>mask</var></code></dt> <dd> +<p>If <var>mask</var> is <code>heuristic</code> or <code>(heuristic <var>bg</var>)</code>, build a clipping mask for the image, so that the background of a frame is visible behind the image. If <var>bg</var> is not specified, or if <var>bg</var> is <code>t</code>, determine the background color of the image by looking at the four corners of the image, assuming the most frequently occurring color from the corners is the background color of the image. Otherwise, <var>bg</var> must be a list <code>(<var>red</var> <var>green</var> <var>blue</var>)</code> specifying the color to assume for the background of the image. </p> <p>If <var>mask</var> is <code>nil</code>, remove a mask from the image, if it has one. Images in some formats include a mask which can be removed by specifying <code>:mask nil</code>. </p> </dd> <dt><code>:pointer <var>shape</var></code></dt> <dd> +<p>This specifies the pointer shape when the mouse pointer is over this image. See <a href="pointer-shape">Pointer Shape</a>, for available pointer shapes. </p> </dd> <dt><code>:map <var>map</var></code></dt> <dd> + <p>This associates an image map of <em>hot spots</em> with this image. </p> <p>An image map is an alist where each element has the format <code>(<var>area</var> <var>id</var> <var>plist</var>)</code>. An <var>area</var> is specified as either a rectangle, a circle, or a polygon. </p> <p>A rectangle is a cons <code>(rect . ((<var>x0</var> . <var>y0</var>) . (<var>x1</var> . <var>y1</var>)))</code> which specifies the pixel coordinates of the upper left and bottom right corners of the rectangle area. </p> <p>A circle is a cons <code>(circle . ((<var>x0</var> . <var>y0</var>) . <var>r</var>))</code> which specifies the center and the radius of the circle; <var>r</var> may be a float or integer. </p> <p>A polygon is a cons <code>(poly . [<var>x0</var> <var>y0</var> <var>x1</var> <var>y1</var> ...])</code> where each pair in the vector describes one corner in the polygon. </p> <p>When the mouse pointer lies on a hot-spot area of an image, the <var>plist</var> of that hot-spot is consulted; if it contains a <code>help-echo</code> property, that defines a tool-tip for the hot-spot, and if it contains a <code>pointer</code> property, that defines the shape of the mouse cursor when it is on the hot-spot. See <a href="pointer-shape">Pointer Shape</a>, for available pointer shapes. </p> <p>When you click the mouse when the mouse pointer is over a hot-spot, an event is composed by combining the <var>id</var> of the hot-spot with the mouse event; for instance, <code>[area4 mouse-1]</code> if the hot-spot’s <var>id</var> is <code>area4</code>. </p> +</dd> </dl> <dl> <dt id="image-mask-p">Function: <strong>image-mask-p</strong> <em>spec &optional frame</em> +</dt> <dd><p>This function returns <code>t</code> if image <var>spec</var> has a mask bitmap. <var>frame</var> is the frame on which the image will be displayed. <var>frame</var> <code>nil</code> or omitted means to use the selected frame (see <a href="input-focus">Input Focus</a>). </p></dd> +</dl> <dl> <dt id="image-transforms-p">Function: <strong>image-transforms-p</strong> <em>&optional frame</em> +</dt> <dd> +<p>This function returns non-<code>nil</code> if <var>frame</var> supports image scaling and rotation. <var>frame</var> <code>nil</code> or omitted means to use the selected frame (see <a href="input-focus">Input Focus</a>). The returned list includes symbols that indicate which image transform operations are supported: </p> <dl compact> <dt><code>scale</code></dt> <dd><p>Image scaling is supported by <var>frame</var> via the <code>:scale</code>, <code>:width</code>, <code>:height</code>, <code>:max-width</code>, and <code>:max-height</code> properties. </p></dd> <dt><code>rotate90</code></dt> <dd><p>Image rotation is supported by <var>frame</var> if the rotation angle is an integral multiple of 90 degrees. </p></dd> </dl> <p>If image transforms are not supported, <code>:rotation</code>, <code>:crop</code>, <code>:width</code>, <code>:height</code>, <code>:scale</code>, <code>:max-width</code> and <code>:max-height</code> will only be usable through ImageMagick, if available (see <a href="imagemagick-images">ImageMagick Images</a>). </p> +</dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Image-Descriptors.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Image-Descriptors.html</a> + </p> +</div> |