reference/image/functions/imagefilter.xml
9960a09a5705102bf4dd0ce63e03d9ec716d0015
...
...
@@ -1,4 +1,4 @@
1
-
<?xml version="1.0" encoding="UTF-8"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="function.imagefilter" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
...
...
@@ -9,16 +9,13 @@
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>bool</type><methodname>imagefilter</methodname>
12
-
<methodparam><type>resource</type><parameter>image</parameter></methodparam>
13
-
<methodparam><type>int</type><parameter>filtertype</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>arg1</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>arg2</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>arg3</parameter></methodparam>
17
-
<methodparam choice="opt"><type>int</type><parameter>arg4</parameter></methodparam>
12
+
<methodparam><type>GdImage</type><parameter>image</parameter></methodparam>
13
+
<methodparam><type>int</type><parameter>filter</parameter></methodparam>
14
+
<methodparam rep="repeat"><type class="union"><type>array</type><type>int</type><type>float</type><type>bool</type></type><parameter>args</parameter></methodparam>
18
15
</methodsynopsis>
19
16
<para>
20
17
<function>imagefilter</function> applies the given filter
21
-
<parameter>filtertype</parameter> on the <parameter>image</parameter>.
18
+
<parameter>filter</parameter> on the <parameter>image</parameter>.
22
19
</para>
23
20
</refsect1>
24
21
<refsect1 role="parameters">
...
...
@@ -27,10 +24,10 @@
27
24
<variablelist>
28
25
&gd.image.description;
29
26
<varlistentry>
30
-
<term><parameter>filtertype</parameter></term>
27
+
<term><parameter>filter</parameter></term>
31
28
<listitem>
32
29
<para>
33
-
<parameter>filtertype</parameter> can be one of the following:
30
+
<parameter>filter</parameter> can be one of the following:
34
31
<itemizedlist>
35
32
<listitem>
36
33
<simpara>
...
...
@@ -41,20 +38,23 @@
41
38
<listitem>
42
39
<simpara>
43
40
<constant>IMG_FILTER_GRAYSCALE</constant>: Converts the image into
44
-
grayscale.
41
+
grayscale by changing the red, green and blue components to their
42
+
weighted sum using the same coefficients as the REC.601 luma (Y')
43
+
calculation. The alpha components are retained. For palette images the
44
+
result may differ due to palette limitations.
45
45
</simpara>
46
46
</listitem>
47
47
<listitem>
48
48
<simpara>
49
49
<constant>IMG_FILTER_BRIGHTNESS</constant>: Changes the brightness
50
-
of the image. Use <parameter>arg1</parameter> to set the level of
51
-
brightness.
50
+
of the image. Use <parameter>args</parameter> to set the level of
51
+
brightness. The range for the brightness is -255 to 255.
52
52
</simpara>
53
53
</listitem>
54
54
<listitem>
55
55
<simpara>
56
56
<constant>IMG_FILTER_CONTRAST</constant>: Changes the contrast of
57
-
the image. Use <parameter>arg1</parameter> to set the level of
57
+
the image. Use <parameter>args</parameter> to set the level of
58
58
contrast.
59
59
</simpara>
60
60
</listitem>
...
...
@@ -62,10 +62,10 @@
62
62
<simpara>
63
63
<constant>IMG_FILTER_COLORIZE</constant>: Like
64
64
<constant>IMG_FILTER_GRAYSCALE</constant>, except you can specify the
65
-
color. Use <parameter>arg1</parameter>, <parameter>arg2</parameter> and
65
+
color. Use <parameter>args</parameter>, <parameter>arg2</parameter> and
66
66
<parameter>arg3</parameter> in the form of
67
-
<parameter>red</parameter>, <parameter>blue</parameter>,
68
-
<parameter>green</parameter> and <parameter>arg4</parameter> for the
67
+
<parameter>red</parameter>, <parameter>green</parameter>,
68
+
<parameter>blue</parameter> and <parameter>arg4</parameter> for the
69
69
<parameter>alpha</parameter> channel. The range for each color is 0 to 255.
70
70
</simpara>
71
71
</listitem>
...
...
@@ -100,22 +100,31 @@
100
100
<listitem>
101
101
<simpara>
102
102
<constant>IMG_FILTER_SMOOTH</constant>: Makes the image smoother.
103
-
Use <parameter>arg1</parameter> to set the level of smoothness.
103
+
Use <parameter>args</parameter> to set the level of smoothness.
104
104
</simpara>
105
105
</listitem>
106
106
<listitem>
107
107
<simpara>
108
108
<constant>IMG_FILTER_PIXELATE</constant>: Applies pixelation effect
109
-
to the image, use <parameter>arg1</parameter> to set the block size
109
+
to the image, use <parameter>args</parameter> to set the block size
110
110
and <parameter>arg2</parameter> to set the pixelation effect mode.
111
111
</simpara>
112
112
</listitem>
113
+
<listitem>
114
+
<simpara>
115
+
<constant>IMG_FILTER_SCATTER</constant>: Applies scatter effect
116
+
to the image, use <parameter>args</parameter> and
117
+
<parameter>arg2</parameter> to define the effect strength and
118
+
additionally <parameter>arg3</parameter> to only apply the
119
+
on select pixel colors.
120
+
</simpara>
121
+
</listitem>
113
122
</itemizedlist>
114
123
</para>
115
124
</listitem>
116
125
</varlistentry>
117
126
<varlistentry>
118
-
<term><parameter>arg1</parameter></term>
127
+
<term><parameter>args</parameter></term>
119
128
<listitem>
120
129
<para>
121
130
<itemizedlist>
...
...
@@ -144,6 +153,13 @@
144
153
<constant>IMG_FILTER_PIXELATE</constant>: Block size in pixels.
145
154
</simpara>
146
155
</listitem>
156
+
<listitem>
157
+
<simpara>
158
+
<constant>IMG_FILTER_SCATTER</constant>: Effect substraction level.
159
+
This must not be higher or equal to the addition level set with
160
+
<parameter>arg2</parameter>.
161
+
</simpara>
162
+
</listitem>
147
163
</itemizedlist>
148
164
</para>
149
165
</listitem>
...
...
@@ -164,6 +180,11 @@
164
180
effect or not (defaults to &false;).
165
181
</simpara>
166
182
</listitem>
183
+
<listitem>
184
+
<simpara>
185
+
<constant>IMG_FILTER_SCATTER</constant>: Effect addition level.
186
+
</simpara>
187
+
</listitem>
167
188
</itemizedlist>
168
189
</para>
169
190
</listitem>
...
...
@@ -178,6 +199,12 @@
178
199
<constant>IMG_FILTER_COLORIZE</constant>: &gd.value.blue;
179
200
</simpara>
180
201
</listitem>
202
+
<listitem>
203
+
<simpara>
204
+
<constant>IMG_FILTER_SCATTER</constant>: Optional array indexed color values
205
+
to apply effect at.
206
+
</simpara>
207
+
</listitem>
181
208
</itemizedlist>
182
209
</para>
183
210
</listitem>
...
...
@@ -207,6 +234,16 @@
207
234
&return.success;
208
235
</para>
209
236
</refsect1>
237
+

238
+
<refsect1 role="errors">
239
+
&reftitle.errors;
240
+
<simpara>
241
+
Throws a <classname>ValueError</classname>
242
+
if <parameter>sub</parameter> or <parameter>plus</parameter> would cause over-/underflow
243
+
with the <constant>IMG_FILTER_SCATTER</constant> <parameter>filter</parameter>.
244
+
</simpara>
245
+
</refsect1>
246
+

210
247
<refsect1 role="changelog">
211
248
&reftitle.changelog;
212
249
<para>
...
...
@@ -220,15 +257,18 @@
220
257
</thead>
221
258
<tbody>
222
259
<row>
223
-
<entry>5.3.0</entry>
260
+
<entry>8.4.0</entry>
224
261
<entry>
225
-
Pixelation support (<constant>IMG_FILTER_PIXELATE</constant>) was added.
262
+
Now throws a <classname>ValueError</classname>
263
+
if <parameter>sub</parameter> or <parameter>plus</parameter> would cause over-/underflow
264
+
with the <constant>IMG_FILTER_SCATTER</constant> <parameter>filter</parameter>.
226
265
</entry>
227
266
</row>
267
+
&gd.changelog.image-param;
228
268
<row>
229
-
<entry>5.2.5</entry>
269
+
<entry>7.4.0</entry>
230
270
<entry>
231
-
Alpha support for <constant>IMG_FILTER_COLORIZE</constant> was added.
271
+
Scatter support (<constant>IMG_FILTER_SCATTER</constant>) was added.
232
272
</entry>
233
273
</row>
234
274
</tbody>
...
...
@@ -256,8 +296,6 @@ else
256
296
{
257
297
echo 'Conversion to grayscale failed.';
258
298
}
259
-

260
-
imagedestroy($im);
261
299
?>
262
300
]]>
263
301
</programlisting>
...
...
@@ -276,7 +314,6 @@ if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
276
314
echo 'Image brightness changed.';
277
315

278
316
imagepng($im, 'sean.png');
279
-
imagedestroy($im);
280
317
}
281
318
else
282
319
{
...
...
@@ -301,7 +338,6 @@ if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
301
338
echo 'Image successfully shaded green.';
302
339

303
340
imagepng($im, 'philip.png');
304
-
imagedestroy($im);
305
341
}
306
342
else
307
343
{
...
...
@@ -349,7 +385,6 @@ if($im && negate($im))
349
385
echo 'Image successfully converted to negative colors.';
350
386

351
387
imagejpeg($im, 'kalle.jpg', 100);
352
-
imagedestroy($im);
353
388
}
354
389
else
355
390
{
...
...
@@ -383,13 +418,10 @@ imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);
383
418
// Merge the differences onto the output image
384
419
imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
385
420
imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);
386
-
imagedestroy($logo1);
387
-
imagedestroy($logo2);
388
421

389
422
// Output the differences
390
423
header('Content-Type: image/png');
391
424
imagepng($output);
392
-
imagedestroy($output);
393
425
?>
394
426
]]>
395
427
</programlisting>
...
...
@@ -402,21 +434,49 @@ imagedestroy($output);
402
434
</mediaobject>
403
435
</example>
404
436
</para>
437
+
<para>
438
+
<example>
439
+
<title><function>imagefilter</function> scatter example</title>
440
+
<programlisting role="php">
441
+
<![CDATA[
442
+
<?php
443
+
// Load the image
444
+
$logo = imagecreatefrompng('./php.png');
445
+

446
+
// Apply a very soft scatter effect to the image
447
+
imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);
448
+

449
+
// Output the image with the scatter effect
450
+
header('Content-Type: image/png');
451
+
imagepng($logo);
452
+
?>
453
+
]]>
454
+
</programlisting>
455
+
&example.outputs.similar;
456
+
<mediaobject>
457
+
<alt>Output of example : imagefilter() scatter</alt>
458
+
<imageobject>
459
+
<imagedata fileref="en/reference/image/figures/scatter.png"/>
460
+
</imageobject>
461
+
</mediaobject>
462
+
</example>
463
+
</para>
405
464
</refsect1>
406
465
<refsect1 role="notes">
407
466
&reftitle.notes;
408
-
&note.bundled.gd;
467
+
<note>
468
+
<simpara>
469
+
The result of <constant>IMG_FILTER_SCATTER</constant> is always random.
470
+
</simpara>
471
+
</note>
409
472
</refsect1>
410
473
<refsect1 role="seealso">
411
474
&reftitle.seealso;
412
-
<para>
413
-
<simplelist>
414
-
<member><function>imageconvolution</function></member>
415
-
</simplelist>
416
-
</para>
475
+
<simplelist>
476
+
<member><function>imageconvolution</function></member>
477
+
</simplelist>
417
478
</refsect1>
418
479
</refentry>
419
-

420
480
<!-- Keep this comment at the end of the file
421
481
Local variables:
422
482
mode: sgml
423
483