sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-28 14:58:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/functions/image.xml
Hartmut Holzgraefe b7636c8035 content-type typo fix 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@29992 c90b9560-bf6c-de11-be94-00142212c4b1
2000-08-09 22:00:42 +00:00

2198 lines
71 KiB
XML
Raw Blame History

<reference id="ref.image">
<title>Image functions</title>
<titleabbrev>Graphics</titleabbrev>
<partintro>
<simpara>
You can use the image functions in PHP to get the size of
<acronym>JPEG</acronym>, <acronym>GIF</acronym>,
<acronym>PNG</acronym>, and <acronym>SWF</acronym> images, and if
you have the <acronym>GD</acronym> library (available at <ulink
url="&url.gd;">&url.gd;</ulink>) you will also be able to create
and manipulate images.
</simpara>
<simpara>
The format of images you are able to manipulate depend on the
version of gd you install, and any other libraries gd might need
to access those image formats. Versions of gd older than gd-1.6
support gif format images, and do not support png, where versions
greater than gd-1.6 support png, not gif.
</simpara>
<simpara>
In order to read and write images in jpeg format, you will need to
obtain and install jpeg-6b (available at
<ulink url="&url.jpeg;">&url.jpeg;</ulink>), and then recompile gd to
make use of jpeg-6b. You will also have to compile PHP with
<option role="configure">--with-jpeg-dir=/path/to/jpeg-6b</option>.
</simpara>
<simpara>
To add support for Type 1 fonts, you can install t1lib (available
at <ulink url="&url.t1lib;">&url.t1lib;</ulink>), and then add
<option role="configure">--with-t1lib[=dir]</option>.
</simpara>
</partintro>
<refentry id="function.getimagesize">
<refnamediv>
<refname>GetImageSize</refname>
<refpurpose>Get the size of a GIF, JPEG, PNG or SWF image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>getimagesize</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
<paramdef>array
<parameter><optional>imageinfo</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>GetImageSize</function> function will determine the
size of any <acronym>GIF</acronym>, <acronym>JPG</acronym>,
<acronym>PNG</acronym> or <acronym>SWF</acronym> image file and
return the dimensions along with the file type and a height/width
text string to be used inside a normal <acronym>HTML</acronym>
<sgmltag>IMG</sgmltag> tag.
</para>
<para>
Returns an array with 4 elements. Index 0 contains the width of
the image in pixels. Index 1 contains the height. Index 2 a
flag indicating the type of the image. 1 = GIF, 2 = JPG, 3 =
PNG, 4 = SWF. Index 3 is a text string with the correct
"height=xxx width=xxx" string that can be used directly in an IMG
tag.
<example>
<title>GetImageSize</title>
<programlisting role="php">
&lt;?php $size = GetImageSize ("img/flag.jpg"); ?>
&lt;IMG SRC="img/flag.jpg" &lt;?php echo $size[3]; ?>
</programlisting>
</example>
</para>
<para>
The optional <parameter>imageinfo</parameter> parameter allows
you to extract some extended information from the image
file. Currently this will return the diffrent
<acronym>JPG</acronym> APP markers in an associative Array. Some
Programs use these APP markers to embedd text information in
images. A very common one in to embed <acronym>IPTC</acronym>
<ulink url="&url.iptc;">&url.iptc;</ulink> information in the
APP13 marker. You can use the <function>iptcparse</function>
function to parse the binary APP13 marker into something
readable.
<example>
<title>GetImageSize returning IPTC</title>
<programlisting>
&lt;?php
$size = GetImageSize ("testimg.jpg",&amp;$info);
if (isset ($info["APP13"])) {
$iptc = iptcparse ($info["APP13"]);
var_dump ($iptc);
}
?&gt;
</programlisting>
</example>
<note>
<simpara>
This function does not require the GD image library.
</simpara>
</note>
</para>
</refsect1>
</refentry>
<refentry id="function.imagearc">
<refnamediv>
<refname>ImageArc</refname>
<refpurpose>Draw a partial ellipse</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagearc</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>cx</parameter></paramdef>
<paramdef>int <parameter>cy</parameter></paramdef>
<paramdef>int <parameter>w</parameter></paramdef>
<paramdef>int <parameter>h</parameter></paramdef>
<paramdef>int <parameter>s</parameter></paramdef>
<paramdef>int <parameter>e</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageArc</function> draws a partial ellipse centered at
<parameter>cx</parameter>, <parameter>cy</parameter> (top left is
0, 0) in the image represented by im. <parameter>W</parameter>
and <parameter>h</parameter> specifies the ellipse's width and
height respectively while the start and end points are specified
in degrees indicated by the <parameter>s</parameter> and
<parameter>e</parameter>. arguments.
</para>
</refsect1>
</refentry>
<refentry id="function.imagechar">
<refnamediv>
<refname>ImageChar</refname>
<refpurpose>Draw a character horizontally</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagechar</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>font</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>string <parameter>c</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageChar</function> draws the first character of
<parameter>c</parameter> in the image identified by
<parameter>id</parameter> with its upper-left at
<parameter>x</parameter>,<parameter>y</parameter> (top left is 0,
0) with the color <parameter>col</parameter>. If font is 1, 2, 3,
4 or 5, a built-in font is used (with higher numbers
corresponding to larger fonts).
</para>
<para>
See also <function>imageloadfont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecharup">
<refnamediv>
<refname>ImageCharUp</refname>
<refpurpose>Draw a character vertically</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecharup</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>font</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>string <parameter>c</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageCharUp</function> draws the character
<parameter>c</parameter> vertically in the image identified by
<parameter>im</parameter> at coordinates
<parameter>x</parameter>, <parameter>y</parameter> (top left is
0, 0) with the color <parameter>col</parameter>. If font is 1,
2, 3, 4 or 5, a built-in font is used.
</para>
<para>
See also <function>imageloadfont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorallocate">
<refnamediv>
<refname>ImageColorAllocate</refname>
<refpurpose>Allocate a color for an image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolorallocate</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>red</parameter></paramdef>
<paramdef>int <parameter>green</parameter></paramdef>
<paramdef>int <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageColorAllocate</function> returns a color
identifier representing the color composed of the given
<acronym>RGB</acronym> components. The <parameter>im</parameter>
argument is the return from the <function>imagecreate</function>
function. <function>ImageColorAllocate</function> must be called
to create each color that is to be used in the image represented
by <parameter>im</parameter>.
<informalexample>
<programlisting role="php">
$white = ImageColorAllocate ($im, 255, 255, 255);
$black = ImageColorAllocate ($im, 0, 0, 0);
</programlisting>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolordeallocate">
<refnamediv>
<refname>ImageColorDeAllocate</refname>
<refpurpose>
De-allocate a color for an image
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int
<function>imagecolordeallocate</function>
</funcdef>
<paramdef>int
<parameter>im</parameter>
</paramdef>
<paramdef>int
<parameter>index</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>ImageColorDeAllocate</function> function
de-allocates a color previously allocated with the
<function>ImageColorAllocate</function> function.
<informalexample>
<programlisting role="php">
$white = ImageColorAllocate($im, 255, 255, 255);
ImageColorDeAllocate($im, $white);
</programlisting>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorat">
<refnamediv>
<refname>ImageColorAt</refname>
<refpurpose>Get the index of the color of a pixel</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolorat</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the index of the color of the pixel at the
specified location in the image.
</para>
<para>
See also <function>imagecolorset</function> and
<function>imagecolorsforindex</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorclosest">
<refnamediv>
<refname>ImageColorClosest</refname>
<refpurpose>
Get the index of the closest color to the specified color
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolorclosest</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>red</parameter></paramdef>
<paramdef>int <parameter>green</parameter></paramdef>
<paramdef>int <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the index of the color in the palette of the image which
is "closest" to the specified <acronym>RGB</acronym> value.
</para>
<para>
The "distance" between the desired color and each color in the
palette is calculated as if the <acronym>RGB</acronym> values
represented points in three-dimensional space.
</para>
<para>
See also <function>imagecolorexact</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorexact">
<refnamediv>
<refname>ImageColorExact</refname>
<refpurpose>Get the index of the specified color</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolorexact</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>red</parameter></paramdef>
<paramdef>int <parameter>green</parameter></paramdef>
<paramdef>int <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the index of the specified color in the palette of the
image.
</para>
<para>
If the color does not exist in the image's palette, -1 is
returned.
</para>
<para>
See also <function>imagecolorclosest</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorresolve">
<refnamediv>
<refname>ImageColorResolve</refname>
<refpurpose>
Get the index of the specified color or its closest possible
alternative
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolorresolve</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>red</parameter></paramdef>
<paramdef>int <parameter>green</parameter></paramdef>
<paramdef>int <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function is guaranteed to return a color index for a
requested color, either the exact color or the closest possible
alternative.
</para>
<para>
See also <function>imagecolorclosest</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagegammacorrect">
<refnamediv>
<refname>ImageGammaCorrect</refname>
<refpurpose>
Apply a gamma correction to a GD image
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int
<function>imagegammacorrect</function>
</funcdef>
<paramdef>int
<parameter>im</parameter>
</paramdef>
<paramdef>double
<parameter>inputgamma</parameter>
</paramdef>
<paramdef>double
<parameter>outputgamma</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>ImageGammaCorrect</function> function applies gamma
correction to a gd image stream (<parameter>im</parameter>) given
an input gamma, the parameter <parameter>inputgamma</parameter>
and an output gamma, the parameter
<parameter>outputgamma</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorset">
<refnamediv>
<refname>ImageColorSet</refname>
<refpurpose>
Set the color for the specified palette index
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>imagecolorset</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>index</parameter></paramdef>
<paramdef>int <parameter>red</parameter></paramdef>
<paramdef>int <parameter>green</parameter></paramdef>
<paramdef>int <parameter>blue</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This sets the specified index in the palette to the specified
color. This is useful for creating flood-fill-like effects in
paletted images without the overhead of performing the actual
flood-fill.
</para>
<para>
See also <function>imagecolorat</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorsforindex">
<refnamediv>
<refname>ImageColorsForIndex</refname>
<refpurpose>Get the colors for an index</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>imagecolorsforindex</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>index</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This returns an associative array with red, green, and blue keys
that contain the appropriate values for the specified color
index.
</para>
<para>
See also <function>imagecolorat</function> and
<function>imagecolorexact</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolorstotal">
<refnamediv>
<refname>ImageColorsTotal</refname>
<refpurpose>
Find out the number of colors in an image's palette
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolorstotal</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This returns the number of colors in the specified image's
palette.
</para>
<para>
See also <function>imagecolorat</function> and
<function>imagecolorsforindex</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecolortransparent">
<refnamediv>
<refname>ImageColorTransparent</refname>
<refpurpose>Define a color as transparent</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecolortransparent</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int
<parameter><optional>col</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageColorTransparent</function> sets the transparent
color in the <parameter>im</parameter> image to
<parameter>col</parameter>. <parameter>Im</parameter> is the
image identifier returned by <function>ImageCreate</function> and
<parameter>col</parameter> is a color identifier returned by
<function>ImageColorAllocate</function>.
</para>
<para>
The identifier of the new (or current, if none is specified)
transparent color is returned.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecopy">
<refnamediv>
<refname>ImageCopy</refname>
<refpurpose>
Copy part of an image
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int
<function>ImageCopy</function>
</funcdef>
<paramdef>int
<parameter>dst_im</parameter>
</paramdef>
<paramdef>int
<parameter>src_im</parameter>
</paramdef>
<paramdef>int
<parameter>dst_x</parameter>
</paramdef>
<paramdef>int
<parameter>dst_y</parameter>
</paramdef>
<paramdef>int
<parameter>src_x</parameter>
</paramdef>
<paramdef>int
<parameter>src_y</parameter>
</paramdef>
<paramdef>int
<parameter>src_w</parameter>
</paramdef>
<paramdef>int
<parameter>src_h</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Copy a part of <parameter>src_im</parameter> onto
<parameter>dst_im</parameter> starting at the x,y coordinates
<parameter>src_x</parameter>, <parameter>src_y </parameter> with
a width of <parameter>src_w</parameter> and a height of
<parameter>src_h</parameter>. The portion defined will be copied
onto the x,y coordinates, <parameter>dst_x</parameter> and
<parameter>dst_y</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecopyresized">
<refnamediv>
<refname>ImageCopyResized</refname>
<refpurpose>Copy and resize part of an image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecopyresized</function></funcdef>
<paramdef>int <parameter>dst_im</parameter></paramdef>
<paramdef>int <parameter>src_im</parameter></paramdef>
<paramdef>int <parameter>dstX</parameter></paramdef>
<paramdef>int <parameter>dstY</parameter></paramdef>
<paramdef>int <parameter>srcX</parameter></paramdef>
<paramdef>int <parameter>srcY</parameter></paramdef>
<paramdef>int <parameter>dstW</parameter></paramdef>
<paramdef>int <parameter>dstH</parameter></paramdef>
<paramdef>int <parameter>srcW</parameter></paramdef>
<paramdef>int <parameter>srcH</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageCopyResized</function> copies a rectangular
portion of one image to another image.
<parameter>Dst_im</parameter> is the destination image,
<parameter>src_im</parameter> is the source image identifier. If
the source and destination coordinates and width and heights
differ, appropriate stretching or shrinking of the image fragment
will be performed. The coordinates refer to the upper left
corner. This function can be used to copy regions within the
same image (if <parameter>dst_im</parameter> is the same as
<parameter>src_im</parameter>) but if the regions overlap the
results will be unpredictable.
</para>
</refsect1>
</refentry>
<refentry id="function.imagecreate">
<refnamediv>
<refname>ImageCreate</refname>
<refpurpose>Create a new image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecreate</function></funcdef>
<paramdef>int <parameter>x_size</parameter></paramdef>
<paramdef>int <parameter>y_size</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageCreate</function> returns an image identifier
representing a blank image of size <parameter>x_size</parameter>
by <parameter>y_size</parameter>.
<example>
<title>
Creating a new GD image stream and outputting an image.
</title>
<programlisting role="php">
&lt;?php
header ("Content-type: image/png");
$im = @ImageCreate (50, 100)
or die ("Cannot Initialize new GD image stream");
$background_color = ImageColorAllocate ($im, 255, 255, 255);
$text_color = ImageColorAllocate ($im, 233, 14, 91);
ImageString ($im, 1, 5, 5, "A Simple Text String", $text_color);
ImagePng ($im);
?>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imagecreatefromgif">
<refnamediv>
<refname>ImageCreateFromGIF</refname>
<refpurpose>Create a new image from file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecreatefromgif</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageCreateFromGif</function> returns an image identifier
representing the image obtained from the given filename.
</para>
<para>
<function>ImageCreateFromGif</function> returns an empty string
on failure. It also outputs an error message, which unfortunately
displays as a broken link in a browser. To ease debugging the
following example will produce an error GIF:
<example>
<title>
Example to handle an error during creation (courtesy
vic@zymsys.com)
</title>
<programlisting role="php">
function LoadGif ($imgname) {
$im = @ImageCreateFromGIF ($imgname); /* Attempt to open */
if (!$im) { /* See if it failed */
$im = ImageCreate (150, 30); /* Create a blank image */
$bgc = ImageColorAllocate ($im, 255, 255, 255);
$tc = ImageColorAllocate ($im, 0, 0, 0);
ImageFilledRectangle ($im, 0, 0, 150, 30, $bgc);
/* Output an errmsg */
ImageString($im, 1, 5, 5, "Error loading $imgname", $tc);
}
return $im;
}
</programlisting>
</example>
<note>
<para>
Since all GIF support was removed from the GD library in
version 1.6, this function is not available if you are using
that version of the GD library.
</para>
</note>
</para>
</refsect1>
</refentry>
<refentry id="function.imagecreatefromjpeg">
<refnamediv>
<refname>ImageCreateFromJPEG</refname>
<refpurpose>Create a new image from file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecreatefromjpeg</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageCreateFromJPEG</function> returns an image identifier
representing the image obtained from the given filename.
</para>
<para>
<function>ImagecreateFromJPEG</function> returns an empty string
on failure. It also outputs an error message, which unfortunately
displays as a broken link in a browser. To ease debugging the
following example will produce an error <acronym>JPEG</acronym>:
<example>
<title>
Example to handle an error during creation (courtesy
vic@zymsys.com )
</title>
<programlisting role="php">
function LoadJpeg ($imgname) {
$im = @ImageCreateFromJPEG ($imgname); /* Attempt to open */
if (!$im) { /* See if it failed */
$im = ImageCreate (150, 30); /* Create a blank image */
$bgc = ImageColorAllocate ($im, 255, 255, 255);
$tc = ImageColorAllocate ($im, 0, 0, 0);
ImageFilledRectangle ($im, 0, 0, 150, 30, $bgc);
/* Output an errmsg */
ImageString ($im, 1, 5, 5, "Error loading $imgname", $tc);
}
return $im;
}
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imagecreatefrompng">
<refnamediv>
<refname>ImageCreateFromPNG</refname>
<refpurpose>Create a new image from file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagecreatefrompng</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageCreateFromPNG</function> returns an image identifier
representing the image obtained from the given filename.
</para>
<para>
<function>ImageCreateFromPNG</function> returns an empty string
on failure. It also outputs an error message, which unfortunately
displays as a broken link in a browser. To ease debugging the
following example will produce an error <acronym>PNG</acronym>:
<example>
<title>
Example to handle an error during creation (courtesy
vic@zymsys.com)
</title>
<programlisting role="php">
function LoadPNG ($imgname) {
$im = @ImageCreateFromPNG ($imgname); /* Attempt to open */
if (!$im) { /* See if it failed */
$im = ImageCreate (150, 30); /* Create a blank image */
$bgc = ImageColorAllocate ($im, 255, 255, 255);
$tc = ImageColorAllocate ($im, 0, 0, 0);
ImageFilledRectangle ($im, 0, 0, 150, 30, $bgc);
/* Output an errmsg */
ImageString ($im, 1, 5, 5, "Error loading $imgname", $tc);
}
return $im;
}
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.imagedashedline">
<refnamediv>
<refname>ImageDashedLine</refname>
<refpurpose>Draw a dashed line</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagedashedline</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x1</parameter></paramdef>
<paramdef>int <parameter>y1</parameter></paramdef>
<paramdef>int <parameter>x2</parameter></paramdef>
<paramdef>int <parameter>y2</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageDashedLine</function> draws a dashed line from
<parameter>x1</parameter>, <parameter>y1</parameter> to
<parameter>x2</parameter>, <parameter>y2</parameter> (top left is
0, 0) in image <parameter>im</parameter> of color
<parameter>col</parameter>.
</para>
<para>
See also <function>ImageLine</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagedestroy">
<refnamediv>
<refname>ImageDestroy</refname>
<refpurpose>Destroy an image</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagedestroy</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageDestroy</function> frees any memory associated
with image <parameter>im</parameter>. <parameter>Im</parameter>
is the image identifier returned by the
<function>ImageCreate</function> function.
</para>
</refsect1>
</refentry>
<refentry id="function.imagefill">
<refnamediv>
<refname>ImageFill</refname>
<refpurpose>Flood fill</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagefill</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageFill</function> performs a flood fill starting at
coordinate <parameter>x</parameter>, <parameter>y</parameter>
(top left is 0, 0) with color <parameter>col</parameter> in the
image <parameter>im</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagefilledpolygon">
<refnamediv>
<refname>ImageFilledPolygon</refname>
<refpurpose>Draw a filled polygon</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagefilledpolygon</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>array <parameter>points</parameter></paramdef>
<paramdef>int <parameter>num_points</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageFilledPolygon</function> creates a filled polygon
in image <parameter>im</parameter>.
<parameter>Points</parameter> is a PHP array containing the
polygon's vertices, ie. points[0] = x0, points[1] = y0, points[2]
= x1, points[3] = y1, etc. <parameter>Num_points</parameter> is
the total number of vertices.
</para>
</refsect1>
</refentry>
<refentry id="function.imagefilledrectangle">
<refnamediv>
<refname>ImageFilledRectangle</refname>
<refpurpose>Draw a filled rectangle</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagefilledrectangle</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x1</parameter></paramdef>
<paramdef>int <parameter>y1</parameter></paramdef>
<paramdef>int <parameter>x2</parameter></paramdef>
<paramdef>int <parameter>y2</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageFilledRectangle</function> creates a filled
rectangle of color <function>col</function> in image
<parameter>im</parameter> starting at upper left coordinates
<parameter>x1</parameter>, <parameter>y1</parameter> and ending
at bottom right coordinates <parameter>x2</parameter>,
<parameter>y2</parameter>. 0, 0 is the top left corner of the
image.
</para>
</refsect1>
</refentry>
<refentry id="function.imagefilltoborder">
<refnamediv>
<refname>ImageFillToBorder</refname>
<refpurpose>Flood fill to specific color</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagefilltoborder</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>int <parameter>border</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageFillToBorder</function> performs a flood fill
whose border color is defined by <parameter>border</parameter>.
The starting point for the fill is <parameter>x</parameter>,
<parameter>y</parameter> (top left is 0, 0) and the region is
filled with color <parameter>col</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagefontheight">
<refnamediv>
<refname>ImageFontHeight</refname>
<refpurpose>Get font height</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagefontheight</function></funcdef>
<paramdef>int <parameter>font</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the pixel height of a character in the specified font.
</para>
<para>
See also <function>ImageFontWidth</function> and
<function>ImageLoadFont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagefontwidth">
<refnamediv>
<refname>ImageFontWidth</refname>
<refpurpose>Get font width</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagefontwidth</function></funcdef>
<paramdef>int <parameter>font</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the pixel width of a character in font.
</para>
<para>
See also <function>ImageFontHeight</function> and
<function>ImageLoadFont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagegif">
<refnamediv>
<refname>ImageGIF</refname>
<refpurpose>Output image to browser or file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagegif</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>string
<parameter><optional>filename</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageGIF</function> creates the <acronym>GIF</acronym>
file in filename from the image <parameter>im</parameter>. The
<parameter>im</parameter> argument is the return from the
<function>imagecreate</function> function.
</para>
<para>
The image format will be <acronym>GIF87a</acronym> unless the
image has been made transparent with
<function>ImageColorTransparent</function>, in which case the
image format will be <acronym>GIF89a</acronym>.
</para>
<para>
The filename argument is optional, and if left off, the raw image
stream will be output directly. By sending an image/gif
content-type using <function>header</function>, you can create a
PHP script that outputs <acronym>GIF</acronym> images directly.
<note>
<para>
Since all <acronym>GIF</acronym> support was removed from the
<acronym>GD</acronym> library in version 1.6, this function is
not available if you are using that version of the GD library.
</para>
</note>
</para>
</refsect1>
</refentry>
<refentry id="function.imagepng">
<refnamediv>
<refname>ImagePNG</refname>
<refpurpose>
Output a PNG image to either the browser or a file
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int
<function>imagepng</function>
</funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>string <parameter><optional>filename</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>ImagePng</function> outputs a GD image stream
(<parameter>im</parameter>) in PNG format to standard output
(usually the browser) or, if a filename is given by the
<parameter>filename</parameter> it outputs the image to the file.
<informalexample>
<programlisting role="php">
&lt;?php
$im = ImageCreateFromPng("test.png");
ImagePng($im);
?>
</programlisting>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.imagejpeg">
<refnamediv>
<refname>ImageJPEG</refname>
<refpurpose>Output image to browser or file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagejpeg</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>string
<parameter><optional>filename</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>quality</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageJPEG</function> creates the
<acronym>JPEG</acronym> file in filename from the image
<parameter>im</parameter>. The <parameter>im</parameter> argument
is the return from the <function>ImageCreate</function> function.
</para>
<para>
The filename argument is optional, and if left off, the raw image
stream will be output directly. To skip the filename argument in
order to provide a quality argument just use an empty string
(''). By sending an image/jpeg content-type using
<function>header</function>, you can create a PHP script that
outputs JPEG images directly.
<note>
<para>
JPEG support is only available in PHP if PHP was compiled
against GD-1.8 or later.
</para>
</note>
</para>
</refsect1>
</refentry>
<refentry id="function.imageinterlace">
<refnamediv>
<refname>ImageInterlace</refname>
<refpurpose>Enable or disable interlace</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imageinterlace</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int
<parameter><optional>interlace</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageInterlace</function> turns the interlace bit on or off.
If interlace is 1 the im image will be interlaced, and if interlace
is 0 the interlace bit is turned off.
</para>
<para>
This functions returns whether the interlace bit is set for the
image.
</para>
</refsect1>
</refentry>
<refentry id="function.imageline">
<refnamediv>
<refname>ImageLine</refname>
<refpurpose>Draw a line</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imageline</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x1</parameter></paramdef>
<paramdef>int <parameter>y1</parameter></paramdef>
<paramdef>int <parameter>x2</parameter></paramdef>
<paramdef>int <parameter>y2</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageLine</function> draws a line from
<parameter>x1</parameter>, <parameter>y1</parameter> to
<parameter>x2</parameter>, <parameter>y2</parameter> (top left is
0, 0) in image im of color <parameter>col</parameter>.
</para>
<para>
See also <function>ImageCreate</function> and
<function>ImageColorAllocate</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imageloadfont">
<refnamediv>
<refname>ImageLoadFont</refname>
<refpurpose>Load a new font</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imageloadfont</function></funcdef>
<paramdef>string <parameter>file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageLoadFont</function> loads a user-defined bitmap
font and returns an identifier for the font (that is always
greater than 5, so it will not conflict with the built-in fonts).
</para>
<para>
The font file format is currently binary and architecture
dependent. This means you should generate the font files on the
same type of CPU as the machine you are running PHP on.
</para>
<para>
<table>
<title>Font file format</title>
<tgroup cols="3">
<thead>
<row>
<entry>byte position</entry>
<entry>C data type</entry>
<entry>description</entry>
</row>
</thead>
<tbody>
<row>
<entry>byte 0-3</entry>
<entry>int</entry>
<entry>number of characters in the font</entry>
</row>
<row>
<entry>byte 4-7</entry>
<entry>int</entry>
<entry>
value of first character in the font (often 32 for space)
</entry>
</row>
<row>
<entry>byte 8-11</entry>
<entry>int</entry>
<entry>pixel width of each character</entry>
</row>
<row>
<entry>byte 12-15</entry>
<entry>int</entry>
<entry>pixel height of each character</entry>
</row>
<row>
<entry>byte 16-</entry>
<entry>char</entry>
<entry>
array with character data, one byte per pixel in each
character, for a total of (nchars*width*height) bytes.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
See also <function>ImageFontWidth</function> and
<function>ImageFontHeight</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepolygon">
<refnamediv>
<refname>ImagePolygon</refname>
<refpurpose>Draw a polygon</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagepolygon</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>array <parameter>points</parameter></paramdef>
<paramdef>int <parameter>num_points</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImagePolygon</function> creates a polygon in image id.
<parameter>Points</parameter> is a PHP array containing the
polygon's vertices, ie. points[0] = x0, points[1] = y0, points[2]
= x1, points[3] = y1, etc. <parameter>Num_points</parameter> is
the total number of vertices.
</para>
<para>
See also <function>imagecreate</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepsbbox">
<refnamediv>
<refname>ImagePSBBox</refname>
<refpurpose>
Give the bounding box of a text rectangle using PostScript Type1
fonts
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>imagepsbbox</function></funcdef>
<paramdef>string <parameter>text</parameter></paramdef>
<paramdef>int <parameter>font</parameter></paramdef>
<paramdef>int <parameter>size</parameter></paramdef>
<paramdef>int <parameter><optional>space</optional></parameter></paramdef>
<paramdef>int <parameter><optional>tightness</optional></parameter></paramdef>
<paramdef>float <parameter><optional>angle</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<parameter>Size</parameter> is expressed in pixels.
</para>
<para>
<parameter>Space</parameter> allows you to change the default
value of a space in a font. This amount is added to the normal
value and can also be negative.
</para>
<para>
<parameter>Tightness</parameter> allows you to control the amount
of white space between characters. This amount is added to the
normal character width and can also be negative.
</para>
<para>
<parameter>Angle</parameter> is in degrees.
</para>
<para>
Parameters <parameter>space</parameter> and
<parameter>tightness</parameter> are expressed in character space
units, where 1 unit is 1/1000th of an em-square.
</para>
<para>
Parameters <parameter>space</parameter>,
<parameter>tightness</parameter>, and <parameter>angle</parameter>
are optional.
</para>
<para>
The bounding box is calculated using information available from
character metrics, and unfortunately tends to differ slightly
from the results achieved by actually rasterizing the text. If
the angle is 0 degrees, you can expect the text to need 1 pixel
more to every direction.
</para>
<para>
This function returns an array containing the following elements:
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>0</entry>
<entry>lower left x-coordinate</entry>
</row>
<row>
<entry>1</entry>
<entry>lower left y-coordinate</entry>
</row>
<row>
<entry>2</entry>
<entry>upper right x-coordinate</entry>
</row>
<row>
<entry>3</entry>
<entry>upper right y-coordinate</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
See also <function>imagepstext</function>.
</para>
</refsect1>
</refentry>
<!-- The function in t1lib which this function uses seems to be buggy...
Currently, just comment out everywhere in the docs and source until time
permits to find a solution.
<refentry id="function.imagepscopyfont">
<refnamediv>
<refname>ImagePSCopyFont</refname>
<refpurpose>
Make a copy of an already loaded font for further modification
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagepscopyfont</function></funcdef>
<paramdef>int <parameter>fontindex</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Use this function if you need make further modifications to the
font, for example extending/condensing, slanting it or changing
it's character encoding vector, but need to keep the original
along as well. Note that the font you want to copy must be one
obtained using <function>ImagePSLoadFont</function>, not a font
that is itself a copied one. You can although make modifications
to it before copying.
</para>
<para>
If you use this function, you <emphasis>must</emphasis> free the
fonts obtained this way yourself and in reverse order. Otherwise
your script <emphasis>will</emphasis> hang.
</para>
<para>
In the case everything went right, a valid font index will be
returned and can be used for further purposes. Otherwise the
function returns false and prints a message describing what went
wrong.
</para>
<para>
See also <function>ImagePSLoadFont</function>.
</para>
</refsect1>
</refentry>
-->
<refentry id="function.imagepsencodefont">
<refnamediv>
<refname>ImagePSEncodeFont</refname>
<refpurpose>
Change the character encoding vector of a font
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagepsencodefont</function></funcdef>
<paramdef>string <parameter>encodingfile</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Loads a character encoding vector from from a file and changes
the fonts encoding vector to it. As a PostScript fonts default
vector lacks most of the character positions above 127, you'll
definitely want to change this if you use an other language than
english. The exact format of this file is described in T1libs
documentation. T1lib comes with two ready-to-use files,
IsoLatin1.enc and IsoLatin2.enc.
</para>
<para>
If you find yourself using this function all the time, a much
better way to define the encoding is to set ps.default_encoding in
the <link linkend="configuration.file">configuration file</link>
to point to the right encoding file and all fonts you load will
automatically have the right encoding.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepsfreefont">
<refnamediv>
<refname>ImagePSFreeFont</refname>
<refpurpose>Free memory used by a PostScript Type 1 font</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>imagepsfreefont</function></funcdef>
<paramdef>int <parameter>fontindex</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
See also <function>ImagePSLoadFont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepsloadfont">
<refnamediv>
<refname>ImagePSLoadFont</refname>
<refpurpose>Load a PostScript Type 1 font from file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagepsloadfont</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
In the case everything went right, a valid font index will be
returned and can be used for further purposes. Otherwise the
function returns false and prints a message describing what went
wrong.
</para>
<para>
See also <function>ImagePSFreeFont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepsextendfont">
<refnamediv>
<refname>ImagePsExtendFont</refname>
<refpurpose>
Extend or condense a font
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool
<function>imagepsextendfont</function>
</funcdef>
<paramdef>int
<parameter>font_index</parameter>
</paramdef>
<paramdef>double
<parameter>extend</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Extend or condense a font (<parameter>font_index</parameter>), if
the value of the <parameter>extend</parameter> parameter is less
than one you will be condensing the font.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepsslantfont">
<refnamediv>
<refname>ImagePsSlantFont</refname>
<refpurpose>
Slant a font
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool
<function>imagepsslantfont</function>
</funcdef>
<paramdef>int
<parameter>font_index</parameter>
</paramdef>
<paramdef>double
<parameter>slant</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Slant a font given by the <parameter>font_index</parameter>
parameter with a slant of the value of the
<parameter>slant</parameter> parameter.
</para>
</refsect1>
</refentry>
<refentry id="function.imagepstext">
<refnamediv>
<refname>ImagePSText</refname>
<refpurpose>
To draw a text string over an image using PostScript Type1 fonts
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>imagepstext</function></funcdef>
<paramdef>int <parameter>image</parameter></paramdef>
<paramdef>string <parameter>text</parameter></paramdef>
<paramdef>int <parameter>font</parameter></paramdef>
<paramdef>int <parameter>size</parameter></paramdef>
<paramdef>int <parameter>foreground</parameter></paramdef>
<paramdef>int <parameter>background</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>int
<parameter>
<optional>space</optional>
</parameter>
</paramdef>
<paramdef>int
<parameter>
<optional>tightness</optional>
</parameter>
</paramdef>
<paramdef>float
<parameter>
<optional>angle</optional>
</parameter>
</paramdef>
<paramdef>int
<parameter>
<optional>antialias_steps</optional>
</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<parameter>Size</parameter> is expressed in pixels.
</para>
<para>
<parameter>Foreground</parameter> is the color in which the text
will be painted. <parameter>Background</parameter> is the color
to which the text will try to fade in with antialiasing. No
pixels with the color <parameter>background</parameter> are
actually painted, so the background image does not need to be of
solid color.
</para>
<para>
The coordinates given by <parameter>x</parameter>,
<parameter>y</parameter> will define the origin (or reference
point) of the first character (roughly the lower-left corner of
the character). This is different from the
<function>ImageString</function>, where <parameter>x</parameter>,
<parameter>y</parameter> define the upper-right corner of the
first character. Refer to PostScipt documentation about fonts and
their measuring system if you have trouble understanding how this
works.
</para>
<para>
<parameter>Space</parameter> allows you to change the default
value of a space in a font. This amount is added to the normal
value and can also be negative.
</para>
<para>
<parameter>Tightness</parameter> allows you to control the amount
of white space between characters. This amount is added to the
normal character width and can also be negative.
</para>
<para>
<parameter>Angle</parameter> is in degrees.
</para>
<para>
<parameter>Antialias_steps</parameter> allows you to control the
number of colours used for antialiasing text. Allowed values are
4 and 16. The higher value is recommended for text sizes lower
than 20, where the effect in text quality is quite visible. With
bigger sizes, use 4. It's less computationally intensive.
</para>
<para>
Parameters <parameter>space</parameter> and
<parameter>tightness</parameter> are expressed in character space
units, where 1 unit is 1/1000th of an em-square.
</para>
<para>
Parameters <parameter>space</parameter>,
<parameter>tightness</parameter>, <parameter>angle</parameter>
and <parameter>antialias</parameter> are optional.
</para>
<para>
This function returns an array containing the following elements:
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>0</entry>
<entry>lower left x-coordinate</entry>
</row>
<row>
<entry>1</entry>
<entry>lower left y-coordinate</entry>
</row>
<row>
<entry>2</entry>
<entry>upper right x-coordinate</entry>
</row>
<row>
<entry>3</entry>
<entry>upper right y-coordinate</entry>
</row>
</tbody>
</tgroup>
</informaltable></para>
<para>
See also <function>imagepsbbox</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagerectangle">
<refnamediv>
<refname>ImageRectangle</refname>
<refpurpose>Draw a rectangle</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagerectangle</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x1</parameter></paramdef>
<paramdef>int <parameter>y1</parameter></paramdef>
<paramdef>int <parameter>x2</parameter></paramdef>
<paramdef>int <parameter>y2</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageRectangle</function> creates a rectangle of color
col in image im starting at upper left coordinate x1, y1 and
ending at bottom right coordinate x2, y2. 0, 0 is the top left
corner of the image.
</para>
</refsect1>
</refentry>
<refentry id="function.imagesetpixel">
<refnamediv>
<refname>ImageSetPixel</refname>
<refpurpose>Set a single pixel</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagesetpixel</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageSetPixel</function> draws a pixel at
<parameter>x</parameter>, <parameter>y</parameter> (top left is
0, 0) in image <parameter>im</parameter> of color
<parameter>col</parameter>.
</para>
<para>
See also <function>ImageCreate</function> and
<function>ImageColorAllocate</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagestring">
<refnamediv>
<refname>ImageString</refname>
<refpurpose>Draw a string horizontally</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagestring</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>font</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>string <parameter>s</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageString</function> draws the string
<parameter>s</parameter> in the image identified by
<parameter>im</parameter> at coordinates
<parameter>x</parameter>, <parameter>y</parameter> (top left is
0, 0) in color <parameter>col</parameter>. If font is 1, 2, 3, 4
or 5, a built-in font is used.
</para>
<para>
See also <function>ImageLoadFont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagestringup">
<refnamediv>
<refname>ImageStringUp</refname>
<refpurpose>Draw a string vertically</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagestringup</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>font</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>string <parameter>s</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageStringUp</function> draws the string
<parameter>s</parameter> vertically in the image identified by
<parameter>im</parameter> at coordinates
<parameter>x</parameter>, <parameter>y</parameter> (top left is
0, 0) in color <parameter>col</parameter>. If font is 1, 2, 3, 4
or 5, a built-in font is used.
</para>
<para>
See also <function>ImageLoadFont</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagesx">
<refnamediv>
<refname>ImageSX</refname>
<refpurpose>Get image width</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagesx</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageSX</function> returns the width of the image
identified by <parameter>im</parameter>.
</para>
<para>
See also <function>ImageCreate</function> and
<function>ImageSY</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagesy">
<refnamediv>
<refname>ImageSY</refname>
<refpurpose>Get image height</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagesy</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageSY</function> returns the height of the image
identified by <parameter>im</parameter>.
</para>
<para>
See also <function>ImageCreate</function> and
<function>ImageSX</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagettfbbox">
<refnamediv>
<refname>ImageTTFBBox</refname>
<refpurpose>
Give the bounding box of a text using TypeType fonts
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>imagettfbbox</function></funcdef>
<paramdef>int <parameter>size</parameter></paramdef>
<paramdef>int <parameter>angle</parameter></paramdef>
<paramdef>string <parameter>fontfile</parameter></paramdef>
<paramdef>string <parameter>text</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function calculates and returns the bounding box in pixels
for a TrueType text.
<variablelist>
<varlistentry>
<term>
<parameter>text</parameter>
</term>
<listitem>
<simpara>The string to be measured.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>size</parameter>
</term>
<listitem>
<simpara>The font size.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>fontfile</parameter>
</term>
<listitem>
<simpara>
The name of the TrueType font file. (Can also be an URL.)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>angle</parameter>
</term>
<listitem>
<simpara>
Angle in degrees in which <parameter>text</parameter> will be
measured.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<function>ImageTTFBBox</function> returns an array with 8
elements representing four points making the bounding box of the
text:
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>0</entry>
<entry>lower left corner, X position</entry>
</row>
<row>
<entry>1</entry>
<entry>lower left corner, Y position</entry>
</row>
<row>
<entry>2</entry>
<entry>lower right corner, X position</entry>
</row>
<row>
<entry>3</entry>
<entry>lower right corner, Y position</entry>
</row>
<row>
<entry>4</entry>
<entry>upper right corner, X position</entry>
</row>
<row>
<entry>5</entry>
<entry>upper right corner, Y position</entry>
</row>
<row>
<entry>6</entry>
<entry>upper left corner, X position</entry>
</row>
<row>
<entry>7</entry>
<entry>upper left corner, Y position</entry>
</row>
</tbody>
</tgroup>
</informaltable>
The points are relative to the <emphasis>text</emphasis>
regardless of the angle, so "upper left" means in the top
left-hand corner seeing the text horizontallty.
</para>
<para>
This function requires both the GD library and the FreeType
library.
</para>
<para>
See also <function>ImageTTFText</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagettftext">
<refnamediv>
<refname>ImageTTFText</refname>
<refpurpose>
Write text to the image using TrueType fonts
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>imagettftext</function></funcdef>
<paramdef>int <parameter>im</parameter></paramdef>
<paramdef>int <parameter>size</parameter></paramdef>
<paramdef>int <parameter>angle</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>int <parameter>col</parameter></paramdef>
<paramdef>string <parameter>fontfile</parameter></paramdef>
<paramdef>string <parameter>text</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ImageTTFText</function> draws the string
<parameter>text</parameter> in the image identified by
<parameter>im</parameter>, starting at coordinates
<parameter>x</parameter>, <parameter>y</parameter> (top left is
0, 0), at an angle of <parameter>angle</parameter> in color
<parameter>col</parameter>, using the TrueType font file
identified by <parameter>fontfile</parameter>.
</para>
<para>
The coordinates given by <parameter>x</parameter>,
<parameter>y</parameter> will define the basepoint of the first
character (roughly the lower-left corner of the character). This
is different from the <function>ImageString</function>, where x,
y define the upper-right corner of the first character.
</para>
<para>
<parameter>Angle</parameter> is in degrees, with 0 degrees being
left-to-right reading text (3 o'clock direction), and higher
values representing a counter-clockwise rotation. (i.e., a value
of 90 would result in bottom-to-top reading text).
</para>
<para>
<parameter>Fontfile</parameter> is the path to the TrueType font
you wish to use.
</para>
<para>
<parameter>Text</parameter> is the text string which may include
UTF-8 character sequences (of the form: &amp;#123;) to access
characters in a font beyond the first 255.
</para>
<para>
<parameter>Col</parameter> is the color index. Using the
negative of a color index has the effect of turning off
antialiasing.
</para>
<para>
<function>ImageTTFText</function> returns an array with 8
elements representing four points making the bounding box of the
text. The order of the points is upper left, upper right, lower
right, lower left. The points are relative to the text
regardless of the angle, so "upper left" means in the top
left-hand corner when you see the text horizontallty.
</para>
<para>
This example script will produce a black GIF 400x30 pixels, with
the words "Testing..." in white in the font Arial.
<example>
<title>ImageTTFText</title>
<programlisting role="php">
&lt;?php
Header ("Content-type: image/gif");
$im = imagecreate (400, 30);
$black = ImageColorAllocate ($im, 0, 0, 0);
$white = ImageColorAllocate ($im, 255, 255, 255);
ImageTTFText ($im, 20, 0, 10, 20, $white, "/path/arial.ttf",
"Testing... Omega: &amp;#937;");
ImageGif ($im);
ImageDestroy ($im);
?&gt;
</programlisting>
</example>
</para>
<para>
This function requires both the GD library and the <ulink
url="&url.freetype;">FreeType</ulink> library.
</para>
<para>
See also <function>ImageTTFBBox</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.imagetypes">
<refnamediv>
<refname>ImageTypes</refname>
<refpurpose>
Return the image types supported by this PHP build
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>imagetypes</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
This function returns a bit-field corresponding to the image
formats supported by the version of GD linked into PHP. The
following bits are returned, IMG_GIF | IMG_JPG | IMG_PNG |
IMG_WBMP. To check for PNG support, for example, do this:
<example>
<title>ImageTypes</title>
<programlisting role="php">
&lt;?php
if (ImageTypes() &amp; IMG_PNG) {
echo "PNG Support is enabled";
}
?&gt;
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.read-exif-data">
<refnamediv>
<refname>read_exif_data</refname>
<refpurpose>Read the EXIF headers from a JPEG</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>read_exif_data</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>read_exif_data</function> function reads the
EXIF headers from a JPEG image file. It returns an associative
array where the indexes are the Exif header names and the values
are the values associated with those Exif headers. Exif headers
tend to be present in JPEG images generated by digital cameras, but
unfortunately each digital camera maker has a different idea of how
to actually tag their images, so you can't always rely on a specific
Exif header being present.
<example>
<title>read_exif_data</title>
<programlisting role="php">
&lt;?php
$exif = read_exif_data ('p0001807.jpg');
while(list($k,$v)=each($exif)) {
echo "$k: $v&lt;br>\n";
}
?>
Output:
FileName: p0001807.jpg
FileDateTime: 929353056
FileSize: 378599
CameraMake: Eastman Kodak Company
CameraModel: KODAK DC265 ZOOM DIGITAL CAMERA (V01.00)
DateTime: 1999:06:14 01:37:36
Height: 1024
Width: 1536
IsColor: 1
FlashUsed: 0
FocalLength: 8.0mm
RawFocalLength: 8
ExposureTime: 0.004 s (1/250)
RawExposureTime: 0.0040000001899898
ApertureFNumber: f/ 9.5
RawApertureFNumber: 9.5100002288818
FocusDistance: 16.66m
RawFocusDistance: 16.659999847412
Orientation: 1
ExifVersion: 0200
</programlisting>
</example>
</para>
<para>
<note>
<simpara>
This function is only available in PHP4 compiled using --enable-exif
</simpara>
<simpara>
This function does not require the GD image library.
</simpara>
</note>
</para>
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Reference in a new issue View git blame Copy permalink