Skip to content

imagick: document the image types #5826

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
+175 −93
Open

imagick: document the image types #5826

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 73 additions & 1 deletion reference/imagick/constants.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1025,14 +1025,35 @@

<variablelist xml:id="imagick.constants.imagetype">
<title><constant>IMGTYPE_<replaceable>*</replaceable></constant> constants</title>
<para></para>
<simpara>
An image type combines a color model with the presence or absence of an
alpha channel.
Passing one of these constants to
<methodname>Imagick::setImageType</methodname> converts the image to that
type.
<methodname>Imagick::getImageType</methodname> reports the type of an image,
but only ever returns a type that describes actual pixel data, never
<constant>imagick::IMGTYPE_UNDEFINED</constant> or
<constant>imagick::IMGTYPE_OPTIMIZE</constant>.
</simpara>
<simpara>
The constants whose name ends in <literal>MATTE</literal> are the variants
that carry an alpha channel; the others have none.
In ImageMagick 6 the alpha channel was known as the matte channel, and when
Imagick is built against ImageMagick 7 each of these constants also exists
under an <constant>IMGTYPE_<replaceable>*</replaceable>ALPHA</constant> name
with the same value.
</simpara>
<varlistentry xml:id="imagick.constants.imgtype-undefined">
<term>
<constant>imagick::IMGTYPE_UNDEFINED</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
The image type is not known.
<methodname>Imagick::setImageType</methodname> converts nothing for this
value, but still records it on the image.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1043,6 +1064,10 @@
</term>
<listitem>
<simpara>
Two colors only.
The image is converted to grayscale, its contrast is stretched, and every
pixel becomes either black or white depending on whether it is lighter or
darker than mid-gray; any alpha channel is discarded.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1053,6 +1078,9 @@
</term>
<listitem>
<simpara>
Shades of gray.
The image is converted to the grayscale colorspace, and any alpha channel
is discarded.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1063,6 +1091,10 @@
</term>
<listitem>
<simpara>
Shades of gray with an alpha channel.
The same as <constant>imagick::IMGTYPE_GRAYSCALE</constant>, except that
the alpha channel is kept, and if the image has none, an opaque one is
added.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1073,6 +1105,10 @@
</term>
<listitem>
<simpara>
Indexed color.
The image is converted to sRGB and, if it is not already indexed or has
more than 256 colors, it is quantized to 256 colors; any alpha channel is
discarded.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1083,6 +1119,12 @@
</term>
<listitem>
<simpara>
Indexed color with an alpha channel.
The image is converted to sRGB, the alpha channel is kept, and if the
image has none, an opaque one is added.
Unlike <constant>imagick::IMGTYPE_PALETTE</constant>, the colors are
quantized even when the image is already indexed, and the alpha channel
is included in the quantization.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1093,6 +1135,8 @@
</term>
<listitem>
<simpara>
Direct color: one red, green, and blue value per pixel, with no palette.
The image is converted to sRGB, and any alpha channel is discarded.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1103,6 +1147,10 @@
</term>
<listitem>
<simpara>
Direct color with an alpha channel.
The same as <constant>imagick::IMGTYPE_TRUECOLOR</constant>, except that
the alpha channel is kept, and if the image has none, an opaque one is
added.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1113,6 +1161,9 @@
</term>
<listitem>
<simpara>
One channel per printing ink, with no palette.
The image is converted to the CMYK colorspace, and any alpha channel is
discarded.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1123,6 +1174,25 @@
</term>
<listitem>
<simpara>
One channel per printing ink, with no palette, plus an alpha channel.
The same as <constant>imagick::IMGTYPE_COLORSEPARATION</constant>, except
that the alpha channel is kept, and if the image has none, an opaque one
is added.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="imagick.constants.imgtype-palettebilevelmatte">
<term>
<constant>imagick::IMGTYPE_PALETTEBILEVELMATTE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Indexed color with a fully transparent or fully opaque alpha channel.
The image is converted to sRGB, an opaque alpha channel is added if it
has none, that channel alone is reduced to two values, and the colors
are then quantized.
This is the type of a PNG using binary transparency.
</simpara>
</listitem>
</varlistentry>
Expand All @@ -1133,6 +1203,8 @@
</term>
<listitem>
<simpara>
<methodname>Imagick::setImageType</methodname> converts nothing for this
value, but still records it on the image.
</simpara>
</listitem>
</varlistentry>
Expand Down
124 changes: 60 additions & 64 deletions reference/imagick/imagick/getimagetype.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="imagick.getimagetype">
<refnamediv>
<refname>Imagick::getImageType</refname>
<refpurpose>Gets the potential image type</refpurpose>
<refpurpose>Gets the image type</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -12,9 +12,12 @@
<modifier>public</modifier> <type>int</type><methodname>Imagick::getImageType</methodname>
<void/>
</methodsynopsis>
<para>
Gets the potential image type.
</para>
<simpara>
Returns the type of the image, derived from its colorspace, its storage
class and whether it carries an alpha channel. The pixels themselves are
not examined, so the value reflects how the image is currently held rather
than the smallest type it could be reduced to.
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -24,66 +27,59 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the potential image type.
<itemizedlist>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_UNDEFINED</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_BILEVEL</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_GRAYSCALE</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_GRAYSCALEMATTE</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_PALETTE</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_PALETTEMATTE</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_TRUECOLOR</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_TRUECOLORMATTE</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_COLORSEPARATION</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_COLORSEPARATIONMATTE</constant>
</simpara>
</listitem>
<listitem>
<simpara>
<constant>imagick::IMGTYPE_OPTIMIZE</constant>
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
Returns one of the following
<link linkend="imagick.constants.imagetype"><constant>imagick::IMGTYPE_<replaceable>*</replaceable></constant></link>
constants. <constant>imagick::IMGTYPE_UNDEFINED</constant> and
<constant>imagick::IMGTYPE_OPTIMIZE</constant> are never returned.
</simpara>
<itemizedlist>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-bilevel"><constant>imagick::IMGTYPE_BILEVEL</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-grayscale"><constant>imagick::IMGTYPE_GRAYSCALE</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-grayscalematte"><constant>imagick::IMGTYPE_GRAYSCALEMATTE</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-palette"><constant>imagick::IMGTYPE_PALETTE</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-palettematte"><constant>imagick::IMGTYPE_PALETTEMATTE</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-truecolor"><constant>imagick::IMGTYPE_TRUECOLOR</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-truecolormatte"><constant>imagick::IMGTYPE_TRUECOLORMATTE</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-colorseparation"><constant>imagick::IMGTYPE_COLORSEPARATION</constant></link>
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="imagick.constants.imgtype-colorseparationmatte"><constant>imagick::IMGTYPE_COLORSEPARATIONMATTE</constant></link>
</simpara>
</listitem>
</itemizedlist>
</refsect1>

<refsect1 role="errors">
Expand Down
39 changes: 25 additions & 14 deletions reference/imagick/imagick/setimagetype.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,35 @@
<modifier>public</modifier> <type>bool</type><methodname>Imagick::setImageType</methodname>
<methodparam><type>int</type><parameter>image_type</parameter></methodparam>
</methodsynopsis>
<para>
Sets the image type.
</para>
<simpara>
Converts the image to the given type, which combines a color model with the
presence or absence of an alpha channel.
Depending on the type, this may change the colorspace, quantize the colors,
or change whether the image has an alpha channel.
</simpara>
<simpara>
<methodname>Imagick::setImageType</methodname> modifies the image itself.
To set the type that subsequent images are written with instead, use
<methodname>Imagick::setType</methodname>.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>image_type</parameter></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><parameter>image_type</parameter></term>
<listitem>
<simpara>
One of the
<link linkend="imagick.constants.imagetype"><constant>imagick::IMGTYPE_<replaceable>*</replaceable></constant></link>
constants. <constant>imagick::IMGTYPE_UNDEFINED</constant> and
<constant>imagick::IMGTYPE_OPTIMIZE</constant> convert nothing, but are
still recorded on the image.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
Expand Down
31 changes: 17 additions & 14 deletions reference/imagick/imagick/settype.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,27 @@
<modifier>public</modifier> <type>bool</type><methodname>Imagick::setType</methodname>
<methodparam><type>int</type><parameter>image_type</parameter></methodparam>
</methodsynopsis>
<para>
Sets the image type attribute.
</para>
<simpara>
Sets the image type applied to images written subsequently.
To convert the current image instead, use
<methodname>Imagick::setImageType</methodname>.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>image_type</parameter></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><parameter>image_type</parameter></term>
<listitem>
<simpara>
One of the
<link linkend="imagick.constants.imagetype"><constant>imagick::IMGTYPE_<replaceable>*</replaceable></constant></link>
constants.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
Expand Down