lodepng.Common
Types and functions common to both the encode and decoder of lodepng, as well as image format
conversion routines
License:
Copyright (c) 2005-2007 Lode Vandevenne
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Lode Vandevenne nor the names of his contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Authors:
Lode Vandevenne (original version in C++), Lutger Blijdestijn (D version) : lutger dot blijdestijn at gmail dot com,
Stewart Gordon (modifications)
Date:
August 7, 2007
References:
Original lodepng
PNG Specification
PNG Suite: set of test images
OptiPNG: tool to experimentally optimize png images
- class
PngException
: object.Exception;
- Png specific exception.
Instead of errors codes, this port of lodepng makes use of exceptions.
At the moment, the decoder is very strict and will tolerate no errors whatsoever even
if they could safely be ignored. CRC checking is always done.
This might be slightly relaxed in a future release to be more in line with the
recommendations of the specification.
- enum
ColorType
;
- An enumeration of the color types supported by the png format.
see the png specification
for details.
-
Greyscale
- allowed bit depths: 1, 2, 4, 8 and 16
-
RGB
- allowed bit depths: 8 and 16
-
Palette
- allowed bit depths: 1, 2, 4 and 8
-
GreyscaleAlpha
- allowed bit depths: 8 and 16
-
RGBA
- allowed bit depths: 8 and 16
-
Any
- one of the above
- ubyte[]
convert
(ubyte[] source, ref PngInfo info, ColorType destColorType = cast(ColorType)cast(ubyte)6u);
ubyte[]
convert
(ubyte[] source, PngInfo info, ref ubyte[] buffer, ColorType destColorType = cast(ColorType)cast(ubyte)6u);
- Convert source pixels from the color type described by info the color type destColorType.
Conversion can be from any color type supported by the png specification to
24 / 32 bit RGB(A). If RGBA is specified and the info has a colorkey, transparency is applied.
If a buffer is given, it may be used to store the result and a slice from it can be returned.
Returns:
converted image in RGB(A) format, pixels are from left to right, top to bottom
- struct
PngImage
;
- Description of the image.
- static PngImage
opCall
(uint w, uint h, ubyte bd, ColorType ct, ubyte ilace = cast(ubyte)0);
- constructor
- uint
width
;
- in pixels
- uint
height
;
- in pixels
- ubyte
bitDepth
;
- bits per color channel, see also: ColorType
- ubyte
bpp
;
- bits per pixel
- ColorType
colorType
;
- the color format, see also: ColorType
- struct
PngInfo
;
- Png file and image description.
A simple data type describing the png file. Usually the image field will contain all the
required information.
There is one member that behaves a bit different: parseText(bool). This is used to tell
the decoder whether to ignore textual metadata (which it does by default).
- PngImage
image
;
- Information related to the
image
, see also: PngImage.
- ubyte[]
backgroundColor
;
- Recommended background color or empty if none is given.
Interpretation of the array depends on the color type:
- palette
- palette[
backgroundColor
[0]] is the background color
- greyscale (8 bit or less)
-
backgroundColor
[0] is used
- RGB(A) (8 bit or less)
-
backgroundColor
[0..3] is the rgb triplet used
- 16-bit greyscale or RGB(A)
- same as above, but the color/greyscale channels are 2 bytes wide
- ubyte[4u][]
palette
;
- Palette colors or empty if this image does not make use of it.
Each
palette
entry is a 32-bit RGBA pixel represented as an ubyte[4].
When a colorkey is specified, it is automatically applied to the
palette
by the decoder.
- bool
colorKey
;
- Whether there is a colorkey transparency associated with the png image.
Note that this is applicable only when the image has no seperate alpha channel, and
the image format is not ColorType.Palette. In the latter case, transparency is always
stored in the palette by the decoder.
The transparent color is stored in keyR, keyG and keyB, for brevity greyscale is in keyR.
- ushort
keyR
;
- ushort
keyG
;
- ushort
keyB
;
- void
parseText
(bool flag);
- By default, lodepng will not parse textual metadata, set to true if this is desired.
- bool
parseText
();
- Whether parsing of metadata is enabled.
- PngText
text
();
- Retrieve the dictionary of textual metadata.
When no
text
is read, because it was set to be ignored or there wasn't any,
this returns null so check the return value.
In the case that a PngInfo instance is passed more than once to the api,
an existing dictionary is not reused. Instead a new one will be
created. It is therefore not necessary to copy anything, the strings they are all yours.
- bool
hasUnicodeText
();
- Returns whether any unicode text has been stored.
- bool
hasLatin1Text
();
- Returns whether any latin-1 text has been stored.
- class
PngText
;
- Dictionary of key-value textual metadata in utf-8 and / or latin-1 encoding.
- this();
- this(char[][char[]] unicodeText);
- this(ubyte[][ubyte[]] latin1Text);
- int
opApply
(int delegate(ref char[] keyword, ref char[] contents) dg);
- Visit utf-8 dictionary
- int
opApply
(int delegate(ref ubyte[] keyword, ref ubyte[] contents) dg);
- Visit latin-1 dictionary
- PngText
opIndexAssign
(ubyte[] value, ubyte[] keyword);
PngText
opIndexAssign
(char[] value, char[] keyword);
- Assign key-value pair
- uint
numChannels
(ColorType colorType);
- Number of color or alpha channels associated with this color type.
- bool
isGreyscale
(ColorType colorType);
- bool
hasAlphaChannel
(ColorType colorType);
- bool
hasAlpha
(ref PngInfo info);
- Whether the image contains any alpha information (channel / colorkey / palette)
- struct
Chunk
;
- Abstracts a png chunk
- static Chunk
fromStream
(ubyte[] byteStream);
- Construct a Chunk from a stream of bytes
Params:
ubyte[] byteStream |
the whole chunk needs to be available in this array |
Returns:
a crc-checked chunk from byteStream, the data is sliced, not copied
- uint
length
();
- Returns:
total
length
of this chunk (not only data)
- Chunk
dup
();
- Returns:
chunk containing a copy of the data
- uint
type
;
-
type
of the chunk packed into a uint, see the png specification for details
- ubyte[]
data
;
- (slice of) the
data
of this chunk
- uint
toUint
(ubyte a, ubyte b, ubyte c, ubyte d);
- Params:
ubyte a |
|
ubyte b |
|
ubyte c |
|
ubyte d |
|
Returns:
- uint
toUint
(ubyte[] source);
- Params:
Returns:
- const uint
IHDR
;
- const uint
IDAT
;
- const uint
PLTE
;
- const uint
tRNS
;
- const uint
bKGD
;
- const uint
IEND
;
- const uint
tEXt
;
- const uint
iTXt
;
- const uint
zTXt
;
- const uint
cHRM
;
- const uint
gAMA
;
- const uint
hIST
;
- const uint
iCCP
;
- const uint
oFFs
;
- const uint
pCAL
;
- const uint
pHYs
;
- const uint
sBIT
;
- const uint
sCAL
;
- const uint
sPLT
;
- const uint
sRGB
;
- char[]
chunkTypeToString
(uint chunkType);
- Params:
Returns:
|