PNG_CheckSig()
Synopsis
LONG PNG_CheckSig(
CONST_STRPTR name );
Function
Open a file, read its first eight bytes, and compare them with the PNG
signature. Close the file before returning. No image data is decoded.
Result
8 if all eight signature bytes match. 0 if eight bytes were read but
do not match. -1 if the file could not be opened or fewer than eight
bytes were read. No separate result distinguishes a short file from
an I/O error.
Notes
Include <proto/pngdt.h> and open datatypes/png.datatype into PNGBase.
This is the datatype's direct interface, not png.library. Call from
DOS process context where file I/O is permitted. The call can block
in Open(), Read() or Close(); it supplies no timeout or cancellation.
A matching signature is not a complete PNG validation or a promise
that PNG_LoadImage() will succeed. The function neither returns an
open handle nor defines a decoder-specific IoErr() result.
PNG_FreeChunk()
Synopsis
void PNG_FreeChunk(
APTR chunk );
Function
Release one retained chunk handle and its inline payload in one
FreeVec() call.
Result
No return value. NULL has no effect. A non-NULL chunk handle and any
payload pointer returned by PNG_GetChunkInfo() become invalid.
Notes
Include <proto/pngdt.h>; keep png.datatype open for this call. Release
each chunk exactly once, after every payload consumer has finished.
No reference count or consumer wait is provided, and caller variables
are not cleared. The call performs no decoding or file I/O.
A retained chunk is independent of its image handle and source bytes.
It can outlive PNG_FreeImage(). Loaders can leave partial chunks in
chunkstore even when their image result is NULL; those chunks still
require release. Existing non-NULL slots skipped by a loader retain
their previous ownership.
Bugs
Invalid handles, double frees and concurrent use are not detected.
PNG_FreeImage()
Synopsis
void PNG_FreeImage(
APTR pnghandle );
Function
Release an image handle and its inline decoded pixel buffer in one
FreeVec() call.
Result
No return value. NULL has no effect. A non-NULL handle and all borrowed
pixel pointers become invalid when freed.
Notes
Include <proto/pngdt.h>; keep png.datatype open for this call. Release
an image exactly once, after every consumer has finished. This call
does not wait for consumers and does not clear caller variables.
It performs no image decoding or file I/O.
Chunks returned through a loader's chunkstore array are separately
allocated and are not released here. Free each with PNG_FreeChunk().
The caller's original file or memory buffer is not released.
Bugs
Invalid handles, double frees and concurrent use are not detected.
PNG_GetChunkInfo()
Synopsis
void PNG_GetChunkInfo(
APTR chunk,
APTR * dataptr,
ULONG * sizeptr );
Function
Return a retained chunk's borrowed payload pointer and payload length.
The payload contains the chunk data bytes, without its PNG length,
type or CRC fields.
Result
No return value. Each non-NULL output is written from the chunk handle.
No validation or independent success indicator is provided.
Notes
Include <proto/pngdt.h>; PNGBase must refer to the open png.datatype.
The call allocates nothing, copies no payload and performs no I/O.
Keep the chunk alive until all borrowed-payload users have finished.
Free the chunk handle with PNG_FreeChunk(), never the payload pointer.
Interpret and bounds-check the payload according to the requested
chunk type. No chunk-name or source-position output is provided; the
loader's request-array position identifies the requested type.
Bugs
Unlike PNG_GetImageInfo(), this function has no NULL-handle check.
NULL chunk with a requested output is dereferenced. A payload pointer
and length do not validate the chunk's application-specific structure.
PNG_GetImageData()
Synopsis
void PNG_GetImageData(
APTR pnghandle,
APTR * gfxdataptr,
APTR * paldataptr );
Function
Return borrowed pointers to the decoded pixel buffer and palette
field. No pixel or palette data is copied.
Result
No return value. For a valid handle, gfxdataptr receives the pixel
pointer and paldataptr receives NULL. With NULL pnghandle, outputs
remain unchanged. Do not use the same location for both outputs.
Notes
Include <proto/pngdt.h>; PNGBase must refer to the open png.datatype.
The pixel pointer remains valid only until PNG_FreeImage(pnghandle).
Do not free it separately. The call allocates nothing and performs no
I/O. Synchronize all consumers against image destruction or mutation.
Rows are contiguous, top to bottom, with no padding. Row size is width
multiplied by depth / 8; obtain those values with PNG_GetImageInfo().
Recompute sizes with checked arithmetic in the caller. Byte layouts
and conversion limits are described by PNG_LoadImageFH().
Bugs
The loader always stores NULL in its palette field. With makeARGB FALSE,
paletted images therefore expose index bytes without their color table.
Use makeARGB TRUE when a self-contained decoded color buffer is needed.
The returned pointers do not establish that image-size arithmetic was
checked during loading.
PNG_GetImageInfo()
Synopsis
void PNG_GetImageInfo(
APTR pnghandle,
LONG * widthptr,
LONG * heightptr,
LONG * depthptr,
LONG * typeptr );
Function
Copy the dimensions, decoded bits per pixel and normalized PNG color
type from an image handle. Each output is optional.
Result
No return value. With a non-NULL handle, the requested outputs are
written. With NULL pnghandle, every output is left unchanged.
Notes
Include <proto/pngdt.h>; PNGBase must refer to the open png.datatype.
This is a metadata copy with no allocation, I/O or ownership transfer.
Do not free the image concurrently. Distinct output locations are
required if all requested results must be retained.
typeptr is a PNG color-type value, not a PBPAFMT_* value. Type 6 can
describe RGBA or ARGB bytes; retain the makeARGB choice used when
loading. TRUE makeARGB reports type 6 and depth 32 for every successful
conversion. Grayscale alpha was already discarded by the loader.
Bugs
Non-NULL handles and output addresses are not validated. The stored
pixel-format field is not exposed, and the original sample depth and
original color type cannot be recovered through this function.
PNG_LoadImage()
Synopsis
APTR PNG_LoadImage(
CONST_STRPTR name,
CONST_STRPTR const * chunkstoread,
APTR * chunkstore,
BOOL makeARGB );
Function
Open a named file for reading, decode its PNG image, and close the file
before returning. The decoding and chunk-retention rules are those of
PNG_LoadImageFH().
Result
An opaque image handle on success, owned by the caller and released
with PNG_FreeImage(). NULL on a normally completed failure path, such
as an invalid signature, read failure, decoder error or allocation
failure. The error-recovery limitations below still apply. No detailed
decoder error code is returned; IoErr() is not a complete error channel.
Failure to open the named file also returns NULL without decoding.
Example
// PNGBase is open. The source must meet the loader's size constraints.
CONST_STRPTR wanted[] = { "icOn", NULL };
APTR chunks[1] = { NULL };
APTR image = PNG_LoadImage("RAM:sample.png", wanted, chunks, TRUE);
if (image != NULL) {
// Use the image; borrowed pixel data expires at PNG_FreeImage().
PNG_FreeImage(image);
}
// Chunk ownership is independent of image success and lifetime.
PNG_FreeChunk(chunks[0]);
Notes
Include <proto/pngdt.h> and open datatypes/png.datatype into PNGBase.
Call from DOS process context. File I/O, decoding and allocation are
synchronous and have no timeout or cancellation interface. The image
handle owns a copy of the decoded pixels, not the source file.
Release the image with PNG_FreeImage() and every separately returned
chunk with PNG_FreeChunk() before closing the datatype. Inspect and
release partial chunk results even when this call returns NULL.
See PNG_LoadImageFH() for the exact pixel layouts, transparency losses,
gamma behavior, chunk selection and output-slot rules.
Bugs
Image-size products and allocation-size additions are not checked for
overflow. Paletted output has no accompanying palette, grayscale alpha
is lost, and RGB/grayscale tRNS is not preserved. Gamma arguments are
passed in the reverse order from libpng's declared interface.
Error recovery reads automatic allocation pointers modified after
setjmp() without volatile qualification. Cleanup after a decoder error
is therefore not reliable. Partial chunk results are not rolled back.
A NULL result is not a guarantee of safe or complete error recovery.
PNG_LoadImageFH()
Synopsis
APTR PNG_LoadImageFH(
BPTR fh,
CONST_STRPTR const * chunkstoread,
APTR * chunkstore,
BOOL makeARGB );
Function
Decode one PNG image from the current position of an open DOS file.
Read the signature, image and trailing chunks through the PNG end
marker. The operation is synchronous and does not close the file.
Result
An opaque image handle on success, owned by the caller and released
with PNG_FreeImage(). NULL on a normally completed failure path, such
as an invalid signature, read failure, decoder error or allocation
failure. The error-recovery limitations below still apply. No detailed
decoder error code is returned; IoErr() is not a complete error channel.
Notes
Include <proto/pngdt.h> and open datatypes/png.datatype into PNGBase.
Use DOS process context. Reads and allocation can block, with no
timeout or cancellation interface. The stream must start at the PNG
signature; do not consume it first with another reader.
File position advances on both success and failure and is not restored.
Keep the datatype open while using its handles and release those handles
before closing it. No source bytes are retained after decoding.
Output rows are tightly packed, in image order, with eight-bit samples.
Sixteen-bit samples are stripped to eight bits. Grayscale samples below
eight bits are expanded to eight-bit intensity; palette indices below
eight bits are unpacked to one byte per pixel.
With makeARGB FALSE, grayscale uses one byte, palette images one index
byte, RGB three bytes and RGBA four bytes per pixel. No palette is
returned. With makeARGB TRUE, palette indices and grayscale are expanded
to RGB, and pixels occupy four bytes in A,R,G,B order. These are byte
layouts, not host-endian ULONG color values. Alpha is not premultiplied.
Grayscale alpha is discarded in both modes. Palette tRNS transparency
is expanded only with makeARGB TRUE. Grayscale and RGB tRNS transparency
are not expanded. Opaque filler bytes are 255. The loader requests gamma
processing; callers cannot select a gamma or color-management policy.
When both chunk arrays are supplied, the loader copies matching retained
chunks before returning. It visits chunks before IDAT first, then chunks
after IDAT, and fills only empty output slots. An absent requested chunk
leaves its slot unchanged. Retained chunks are separate allocations:
release each newly returned non-NULL handle with PNG_FreeChunk(), even
if the image result is NULL. PNG_FreeImage() does not release them.
The chunk arrays themselves are borrowed, not retained. Requesting a
chunk normally interpreted by libpng can change how that chunk is
decoded. Do not use the retention list as an unrestricted metadata API.
Bugs
Image-size products and allocation-size additions are not checked for
overflow. Paletted output has no accompanying palette, grayscale alpha
is lost, and RGB/grayscale tRNS is not preserved. Gamma arguments are
passed in the reverse order from libpng's declared interface.
Error recovery reads automatic allocation pointers modified after
setjmp() without volatile qualification. Cleanup after a decoder error
is therefore not reliable. Partial chunk results are not rolled back.
A NULL result is not a guarantee of safe or complete error recovery.
PNG_LoadImageMEM()
Synopsis
APTR PNG_LoadImageMEM(
APTR mem,
ULONG memsize,
CONST_STRPTR const * chunkstoread,
APTR * chunkstore,
BOOL makeARGB );
Function
Decode a PNG image from a contiguous memory buffer beginning with its
eight-byte signature. Copy the decoded pixels and requested retained
chunks into separate allocations. The source buffer is not retained.
Result
An opaque image handle on success, owned by the caller and released
with PNG_FreeImage(). NULL on a normally completed failure path, such
as an invalid signature, read failure, decoder error or allocation
failure. The error-recovery limitations below still apply. No detailed
decoder error code is returned; IoErr() is not a complete error channel.
Notes
Include <proto/pngdt.h> and open datatypes/png.datatype into PNGBase.
Use task context where allocation and decoder work are permitted.
This entry point performs no DOS file reads. It provides no timeout,
progress callback or cancellation interface and reports no consumed
byte count. Trailing bytes beyond the decoded PNG are not returned.
The caller retains ownership of mem and may release it after this call.
Image and chunk lifetimes are independent of that source. Release the
image with PNG_FreeImage() and all returned chunks with PNG_FreeChunk(),
including partial chunks returned alongside a NULL image result.
See PNG_LoadImageFH() for pixel layouts, transparency, gamma and chunk
selection. Keep the datatype open until its handles have been released.
Bugs
The read callback checks pos + length against memsize without checking
the addition for overflow. On a 32-bit size_t target this sum can wrap.
An overstated length also permits reads beyond the real allocation;
the loader cannot infer its true size. NULL mem with memsize >= 8
reaches memcpy() rather than a reported failure.
Image-size products and allocation-size additions are not checked for
overflow. Paletted output has no accompanying palette, grayscale alpha
is lost, and RGB/grayscale tRNS is not preserved. Gamma arguments are
passed in the reverse order from libpng's declared interface.
Error recovery reads automatic allocation pointers modified after
setjmp() without volatile qualification. Cleanup after a decoder error
is therefore not reliable. Partial chunk results are not rolled back.
A NULL result is not a guarantee of safe or complete error recovery.
