Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_image_filter_module.xml @ 271:4c6d2c614d2c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cleaned up XML tag mess: - all of <parameter> and <code>, and some of <dirname>, <value>, and <command> were replaced by <literal>; - the rest of <dirname> were replaced by links; - <argument> were replaced by <value>; - <value> is now rendered in HTML in italic; - <literal> and <path> can now contain <value>. Cleaned up terminology mess: - directives take "parameters".
author Ruslan Ermilov <ru@nginx.com>
date Fri, 23 Dec 2011 17:29:59 +0000
parents 945d7299c26c
children 9f5ee1c6fca5
comparison
equal deleted inserted replaced
270:945d7299c26c 271:4c6d2c614d2c
7 lang="en"> 7 lang="en">
8 8
9 <section id="summary"> 9 <section id="summary">
10 10
11 <para> 11 <para>
12 The <code>ngx_http_image_filter_module</code> module is a filter 12 The <literal>ngx_http_image_filter_module</literal> module is a filter
13 that transforms images in JPEG, GIF, and PNG (0.7.54+) formats. 13 that transforms images in JPEG, GIF, and PNG (0.7.54+) formats.
14 </para> 14 </para>
15 15
16 <para> 16 <para>
17 This module is not built by default, it should be enabled with the 17 This module is not built by default, it should be enabled with the
18 <code>--with-http_image_filter_module</code> 18 <literal>--with-http_image_filter_module</literal>
19 configuration parameter. 19 configuration parameter.
20 <note> 20 <note>
21 This module utilizes the 21 This module utilizes the
22 <link url="http://libgd.org">libgd</link> library. 22 <link url="http://libgd.org">libgd</link> library.
23 It is recommended to use the latest available version of the library; 23 It is recommended to use the latest available version of the library;
49 49
50 50
51 <section id="directives" name="Directives"> 51 <section id="directives" name="Directives">
52 52
53 <directive name="image_filter"> 53 <directive name="image_filter">
54 <syntax><parameter>off</parameter></syntax> 54 <syntax><literal>off</literal></syntax>
55 <syntax><parameter>test</parameter></syntax> 55 <syntax><literal>test</literal></syntax>
56 <syntax><parameter>size</parameter></syntax> 56 <syntax><literal>size</literal></syntax>
57 <syntax><parameter>rotate</parameter> 57 <syntax><literal>rotate</literal>
58 <value>90</value> | <value>180</value> | <value>270</value></syntax> 58 <literal>90</literal> | <literal>180</literal> | <literal>270</literal></syntax>
59 <syntax> 59 <syntax>
60 <parameter>resize</parameter> 60 <literal>resize</literal>
61 <argument>width</argument> 61 <value>width</value>
62 <argument>height</argument></syntax> 62 <value>height</value></syntax>
63 <syntax> 63 <syntax>
64 <parameter>crop</parameter> 64 <literal>crop</literal>
65 <argument>width</argument> 65 <value>width</value>
66 <argument>height</argument></syntax> 66 <value>height</value></syntax>
67 <default/> 67 <default/>
68 <context>location</context> 68 <context>location</context>
69 69
70 <para> 70 <para>
71 Sets the type of transformation to perform on images: 71 Sets the type of transformation to perform on images:
72 <list type="tag"> 72 <list type="tag">
73 73
74 <tag-name><parameter>off</parameter></tag-name> 74 <tag-name><literal>off</literal></tag-name>
75 <tag-desc> 75 <tag-desc>
76 turns off module processing in a surrounding location. 76 turns off module processing in a surrounding location.
77 </tag-desc> 77 </tag-desc>
78 78
79 <tag-name><parameter>test</parameter></tag-name> 79 <tag-name><literal>test</literal></tag-name>
80 <tag-desc> 80 <tag-desc>
81 ensures that answers are images in either JPEG, GIF, or PNG format. 81 ensures that answers are images in either JPEG, GIF, or PNG format.
82 Otherwise, the error 82 Otherwise, the error
83 <http-status code="415" text="Unsupported Media Type"/> 83 <http-status code="415" text="Unsupported Media Type"/>
84 is returned. 84 is returned.
85 </tag-desc> 85 </tag-desc>
86 86
87 <tag-name><parameter>size</parameter></tag-name> 87 <tag-name><literal>size</literal></tag-name>
88 <tag-desc> 88 <tag-desc>
89 outputs information about images in a JSON format, e.g.: 89 outputs information about images in a JSON format, e.g.:
90 <example> 90 <example>
91 { "img" : { "width": 100, "height": 100, "type": "gif" } } 91 { "img" : { "width": 100, "height": 100, "type": "gif" } }
92 </example> 92 </example>
94 <example> 94 <example>
95 {} 95 {}
96 </example> 96 </example>
97 </tag-desc> 97 </tag-desc>
98 98
99 <tag-name><parameter>rotate</parameter> 99 <tag-name><literal>rotate</literal>
100 <value>90</value>|<value>180</value>|<value>270</value> 100 <literal>90</literal>|<literal>180</literal>|<literal>270</literal>
101 </tag-name> 101 </tag-name>
102 <tag-desc> 102 <tag-desc>
103 rotates images counter-clockwise by the specified number of degrees. 103 rotates images counter-clockwise by the specified number of degrees.
104 The argument value can contain variables. 104 Value of the parameter can contain variables.
105 Can be used either alone, or along with the 105 Can be used either alone, or along with the
106 <parameter>resize</parameter> and <parameter>crop</parameter> transformations. 106 <literal>resize</literal> and <literal>crop</literal> transformations.
107 </tag-desc> 107 </tag-desc>
108 108
109 <tag-name><parameter>resize</parameter> 109 <tag-name><literal>resize</literal>
110 <argument>width</argument> 110 <value>width</value>
111 <argument>height</argument> 111 <value>height</value>
112 </tag-name> 112 </tag-name>
113 <tag-desc> 113 <tag-desc>
114 proportionally reduces an image to the specified sizes. 114 proportionally reduces an image to the specified sizes.
115 To reduce by only one dimension, another dimension can be specified as 115 To reduce by only one dimension, another dimension can be specified as
116 “<code>-</code>”. 116 “<literal>-</literal>”.
117 In case of an error, the server will return code 117 In case of an error, the server will return code
118 <http-status code="415" text="Unsupported Media Type"/>. 118 <http-status code="415" text="Unsupported Media Type"/>.
119 Values of arguments can contain variables. 119 Values of parameters can contain variables.
120 When used along with the <parameter>rotate</parameter> parameter, 120 When used along with the <literal>rotate</literal> parameter,
121 the rotation happens <emphasis>after</emphasis> reduction. 121 the rotation happens <emphasis>after</emphasis> reduction.
122 </tag-desc> 122 </tag-desc>
123 123
124 <tag-name><parameter>crop</parameter> 124 <tag-name><literal>crop</literal>
125 <argument>width</argument> 125 <value>width</value>
126 <argument>height</argument> 126 <value>height</value>
127 </tag-name> 127 </tag-name>
128 <tag-desc> 128 <tag-desc>
129 proportionally reduces an image to the size of the largest side 129 proportionally reduces an image to the size of the largest side
130 and crops extraneous edges by another side. 130 and crops extraneous edges by another side.
131 To reduce by only one dimension, another dimension can be specified as 131 To reduce by only one dimension, another dimension can be specified as
132 “<code>-</code>”. 132 “<literal>-</literal>”.
133 In case of an error, the server will return code 133 In case of an error, the server will return code
134 <http-status code="415" text="Unsupported Media Type"/>. 134 <http-status code="415" text="Unsupported Media Type"/>.
135 Values of arguments can contain variables. 135 Values of parameters can contain variables.
136 When used along with the <parameter>rotate</parameter> parameter, 136 When used along with the <literal>rotate</literal> parameter,
137 the rotation happens <emphasis>before</emphasis> reduction. 137 the rotation happens <emphasis>before</emphasis> reduction.
138 </tag-desc> 138 </tag-desc>
139 139
140 </list> 140 </list>
141 </para> 141 </para>
158 158
159 </directive> 159 </directive>
160 160
161 161
162 <directive name="image_filter_jpeg_quality"> 162 <directive name="image_filter_jpeg_quality">
163 <syntax><value>1..100</value></syntax> 163 <syntax><value>quality</value></syntax>
164 <default>75</default> 164 <default>75</default>
165 <context>http</context> 165 <context>http</context>
166 <context>server</context> 166 <context>server</context>
167 <context>location</context> 167 <context>location</context>
168 168
169 <para> 169 <para>
170 Sets the desired quality of the transformed JPEG images. 170 Sets the desired <value>quality</value> of the transformed JPEG images.
171 Acceptable values are in the 1..100 range.
171 Lesser values usually imply both lower image quality and less data to transfer. 172 Lesser values usually imply both lower image quality and less data to transfer.
172 The maximum recommended value is 95. 173 The maximum recommended value is 95.
173 The argument value can contain variables. 174 Value of the parameter can contain variables.
174 </para> 175 </para>
175 176
176 </directive> 177 </directive>
177 178
178 179
179 <directive name="image_filter_sharpen"> 180 <directive name="image_filter_sharpen">
180 <syntax><argument>percent</argument></syntax> 181 <syntax><value>percent</value></syntax>
181 <default>0</default> 182 <default>0</default>
182 <context>http</context> 183 <context>http</context>
183 <context>server</context> 184 <context>server</context>
184 <context>location</context> 185 <context>location</context>
185 186
186 <para> 187 <para>
187 Increases sharpness of the final image. 188 Increases sharpness of the final image.
188 The sharpness percentage can exceed 100. 189 The sharpness percentage can exceed 100.
189 The value of 0 disables sharpening. 190 The value of 0 disables sharpening.
190 The argument value can contain variables. 191 Value of the parameter can contain variables.
191 </para> 192 </para>
192 193
193 </directive> 194 </directive>
194 195
195 196
196 <directive name="image_filter_transparency"> 197 <directive name="image_filter_transparency">
197 <syntax><value>on</value>|<value>off</value></syntax> 198 <syntax><literal>on</literal>|<literal>off</literal></syntax>
198 <default>on</default> 199 <default>on</default>
199 <context>http</context> 200 <context>http</context>
200 <context>server</context> 201 <context>server</context>
201 <context>location</context> 202 <context>location</context>
202 203