FreeBASIC PNG Library (v1.9.0)
Copyright (C) 2007 Simon Nash
zlib code Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler
See license.txt and zlib/zlib.h for more information.
This library provides easy to use functions for using PNG images in your FreeBASIC
programs. The functions provide a way to load PNG images to old or new style PUT buffers
and also in a format ready for use with OpenGL. Images can be loaded from file, or
memory buffer.
Compiling
=========
In order to compile you need GNU make, FreeBASIC 0.16 or newer, and GCC if you wish to
compile in the zlib. Just type 'make' in the main directory to make the default build.
You can also do 'make STATICZ=1' to build the library to include zlib. Other options
are 'DEBUG=1', 'PROFILE=1' and 'EXX=1'.
Notes for users of previous versions (before v1.8.4)
====================================================
The librarys interface has changed, due to the new target parameter, and the old
redundant target depth has been removed, the library always returns a 32 bit image.
There is also now no error global variable, however if you compile with make DEBUG=1
then much debugging info will be printed to the console
Usage
=====
Once compiled you will need two files, 'build/libfbpng.a' and 'inc/fbpng.bi'. These
should be placed either in your projects directory, or in the lib/ and inc/ dirs of your
FreeBASIC installation, along with the other libary and header files.
There are 5 functions for users, I will give the details here:
------------------------------------------------------
For those functions that accept a target, the following are the allowed values
For an old style FreeBASIC buffer, as used in older versions of FB
PNG_TARGET_FBOLD
For a new style FreeBASIC buffer, as used in the newer versions of FB
PNG_TARGET_FBNEW
For a buffer that is ready to be used with OpenGL
PNG_TARGET_OPENGL
------------------------------------------------------
declare function png_load cdecl alias "png_load" _
( _
byref filename as string, _
byval target as png_target_e = PNG_TARGET_FBOLD _
) as any ptr
The filename parameter should be obvious, something like "foo.png"
The target parameter is one of the values listed above, ie PNG_TARGET_FBOLD
The return value will be a pointer to a buffer that contains the image in the format
specified by target. The returned buffer will always be a 32-bit image.
If the function fails, then the return will be NULL
It is the users responsibity to free the returned image when finished with, using
the normal DEALLOCATE/free
Example
dim as any ptr img
screenres 640, 480, 32
img = png_load( "test.png" )
if img <> NULL then
put( 0, 0 ), img
deallocate( img )
else
print "Failed to load"
end if
------------------------------------------------------
declare function png_load_mem cdecl alias "png_load_mem" _
( _
byval buffer as any ptr, _
byval buffer_len as integer, _
byval target as png_target_e = PNG_TARGET_FBOLD _
) as any ptr
The buffer parameter is a pointer to a memory location that holds a PNG image
The buffer_len parameter is the size of this buffer, ie the files size
The target parameter is one of the values listed above, ie PNG_TARGET_FBOLD
The return value will be a pointer to a buffer that contains the image in the format
specified by target. The returned buffer will always be a 32-bit image.
If the function fails, then the return will be NULL
It is the users responsibity to free the returned image when finished with, using
the normal DEALLOCATE/free
------------------------------------------------------
declare function png_save cdecl alias "png_save" _
( _
byref filename as string, _
byval img as any ptr _
) as integer
The filename parameter should be obvious, something like "foo.png"
The img parameter is a pointer to either a new or old style FreeBASIC buffer, the
library will determine what type it is, it must be in 32-bit format.
The return value will be 0 (zero) on success, and non zero otherwise
------------------------------------------------------
declare sub png_dimensions cdecl alias "png_dimensions" _
( _
byref filename as string, _
byref w as uinteger, _
byref h as uinteger _
)
The filename parameter should be obvious, something like "foo.png"
The w and h parameters (note the byref) are how the dimensions are returned
If the sub fails, then then w and h will be zero
Example
dim as uinteger w, h
png_dimensions( "test.png", w, h )
print w, h
------------------------------------------------------
declare sub png_dimensions_mem cdecl alias "png_dimensions_mem" _
( _
byval buffer as any ptr, _
byref w as uinteger, _
byref h as uinteger _
)
The buffer parameter is a pointer to a memory location that holds a PNG image
The w and h parameters (note the byref) are how the dimensions are returned
If the sub fails, then then w and h will be zero
Credits
=======
Technical credits:
victor for the FreeBASIC compiler, and the rest of the team for their work on it.
The creators of the PNG format, and the RFC that was very useful for me.
Willem van Schaik for the pngsuite of testing images.
The creators of zlib, for the compression, and decompression routines.
counting_pine, for one line of code that has since been eliminated, but was
very helpful at the time.
DrV for the memory leak detector
Coderjeff and others for the Wiki manual
The makers of all the other tools I use, especially GDB, valgrind, gcc, fasm, make
cha0s for building the windows prebuilt version
General greetings:
All FreeBASIC users, especially those who are on the IRC channel and the forum, in
particular (but in no particular order)
mr_cha0s, stylin, {1000101}, voodooattack, {Nathan}, spaz, pritchard,
shadowwolf, insomninja, ijjekw, DJ Peters, relsoft, Dr_D
Notes on the zlib usage
=======================
The source files for zlib are just taken directly from an official zlib distribution
I haven't modified them in any way