Written by Frank Condello with contributions by Will Leshner and Jonathan Johnson.
Feedback: developer@chaoticbox.com
Web: http://developer.chaoticbox.com/
Portions from LoadSaveJPEG Copyright (c) 2001 Dair Grant and Copyright (c) 2003 Joe Strout
zlib Copyright (c) 1995-2002 Jean-loup Gailly and Mark Adler
libpng Copyright (c) 1998-2002 Glenn Randers-Pehrson
About
|
The PNG image format supports true-colour images with or without alpha channels, using efficient lossless compression. PNG images are ideal when small file sizes are desired without sacrificing image fidelity or transparency information. The PNG Utilities Plugin enables REALbasic developers to easily load and save PNG images, while seamlessly importing and exporting transparency masks. For more information on the PNG format, see the Basic Introduction to PNG Features.
The PNG Utilities Plugin supports Mac OS 8/9 (Classic/Carbon), Mac OS X (PEF/Mach-O), Windows, and Linux targets. PNG Utilities is open source and free to use and modify. Please see the LICENSE.txt file in the source distribution for more information.
|
Usage Notes
|
Place the PNG Utilities Plugin.rbx file included in the download into your REALbasic plugin folder and launch REALbasic. The plugin provides a PNGu module containing various methods. Please see the method reference document and the included example project for more detailed information.
NOTE: If you use Photoshop to create PNG files, do yourself a favour and download the free SuperPNG Photoshop plugin (available for Mac OS and Windows). |
Limitations / Quirks / Tips:
|
IMPORTANT: Linux builds dynamically link with libpng and zlib at runtime. PNG Utilities will not function without these libraries, but they are typically included with Linux distributions and no extra installation will be required under normal circumstances. The Mac and Win32 plugins are self-contained (i.e. statically linked libpng and zlib libraries are built into the plugin itself).
PNG Utilities can load any valid PNG file (true-colour, paletted, greyscale, etc.) but currently only saves true-colour 8bpp RGB and RGBA formats.
Gamma correction is applied destructively when loading a PNG image. This means that the original RGB data no longer exists within the REALbasic Picture object. To avoid gamma correction entirely always pass a gamma value of -1 when loading and/or saving PNG images.
Vector pictures (Pictures with Depth = 0) need to be converted to a bitmap before sending them to the Save/GetData methods.
Picture.Transparent flags are not converted to alpha channels when using the Save/GetData methods. Only Pictures with a valid Mask property will result in a PNG containing an alpha channel, but note that Masks should be grayscale for consistent results.
Masks in REALbasic treat black as opaque, while alpha channels treat black as transparent. The plugin automatically inverts masks into alphas, and alphas into masks, but you should be aware of this behaviour. |
Version History
|
v1.8.1 - March 26 2007
- All: 16 bpp (48 & 64 bit) PNG images now load and display properly.
- Mac OS X: Bundle format plugin segments included for better compatibility with RB2007 IDEs.
v1.8 - October 15 2006
- IMPORTANT: PNG Utilities now requires REALbasic 5.5 or greater.
- Mac OS X: i386 support (Intel/Universal Binary targets).
- All: Added a Picture class extension Picture.HasMask As Boolean
- Mac: File handling has been re-written, with the following benefits:
- SavePicture no longer mangles Unicode characters or truncates long file names on HFS+ volumes.
- Mac OS X targets no longer use file manager routines marked deprecated in Mac OS X 10.4.
- Win32: SavePicture and GetData no longer crash when given pictures with depths other than 32 bit.
- Linux: OpenAsPicture and GetPicture no longer leak a Picture and/or Graphics object under certain conditions.
- Linux: SavePicture and GetData no longer apply alpha channels destructively to the RGB pixels when the Picture contains a Mask
- Linux: SavePicture properly handles paths that contain Unicode characters
- All: SavePicture and GetData fail gracefully rather than crash if you pass an invalid Picture object (e.g. a Picture with zero/negative dimensions or null data storage).
- All: GetPicture methods no longer work on a copy of the PNG data (use less memory).
- Mac: SavePicture and GetData use Quartz 2D on Mac OS X rather than Quickdraw.
- NOTE: Mach-O targets always use Quartz and require Mac OS 10.2 or better. CFM Carbon targets will fall back to Quickdraw if the required Quartz functions are not available (i.e. on OS X versions prior to 10.2 and in Classic).
- All: Passing a gamma value of -1 to SavePicture or GetData now omits the PNG gAMA chunk entirely rather than embedding the default system gamma.
- All: Omitting the gamma parameter in the OpenAsPicture or GetPicture methods will now apply the native system gamma if no embedded gamma value is found. Previously these methods returned unmodified RGB values in this case, but that was not the intended behaviour. Always ask for a gamma value of -1 to get raw RGB colours.
- All: Updated libpng to version 1.2.12.
- NOTE: Linux targets dynamically link with the installed libpng. Version 1.2.12 or better is recommended however.
- Linux: No longer complains it can't find libpng3 when only libpng12 is installed (will now use the most recent version available).
- Mac OS X: Mach-O segments have significantly reduced in size.
- All: Fixed a typedef mismatch when using Boolean values as parameters vs return values (this normally didn't cause any problems previously however).
v1.7 - August 12 2005
- Updated to zlib 1.2.3 (security patch)
- PNGu.OpenAsPicture* methods now work on Win32 with double-byte characters in the file path.
- Native Mac OS X Mach-O (PPC) build (Xcode project included).
- Added a couple more sanity checks for out-of-memory situations when loading an image.
- Documentation now included in the plugin (available from REALbasic's "Help" menu).
- NOTE: Linux build remains unchanged from version 1.6.1
v1.6.1 - October 25 2004
- Linux support (Jonathan Johnson).
v1.5.2 - Septmenber 17 2004
- Updated to libpng version 1.2.7 which fixes a save bug that causes some programs to incorrectly read in the resulting image (i.e. any application that uses Microsoft's PNG loader on Win32).
- Updated zlib to version 1.2.1 (minor memory savings, and possible speed ups).
- Renamed the Win32 DLL to avoid potential conflicts with other plugins.
v1.5.1 - August 18 2004
- Updated libpng to version 1.2.6 which addresses several vulnerabilities found in libpng 1.2.5.
v1.5 - July 9 2004
- Added a "GetData" method (Will Leshner).
- Fixed several potential memory leaks if a save or load function bails due to a library or file/buffer error.
- PNG files saved on Mac OS X now set their creator to "????" allowing Launch Services to resolve the application.
- More and better error checking, plus other minor code clean-ups.
v1.4 - July 6 2004
- The external module is no longer needed. The plugin now contains all functionality internally.
- The "*AndMask" methods have been removed as a result of the change above (redundant).
- All methods renamed for better integration with RB 5.5 namespace features.
- Fixed a potential object leak in the Win32 save routines.
- Using a gamma of -1.0 in the loading methods will force the current system gamma. This can be used to get raw RGB colour on any system without requiring specific knowledge about the native gamma values.
- Changed name to "PNG Utilities" since the plugin is incompatible with projects built with the old LoadSavePNG plugin.
v1.3 (LoadSavePNG) - October 14 2003
- Indexed-colour PNGs with 1bit transparency now load properly.
v1.2 (LoadSavePNG) - September 15 2003
- Added methods to generate a picture object from PNG data stored in a string.
- Files are properly closed after loading.
v1.1 (LoadSavePNG) - August 28 2003
- grayscale PNGs with a depth of less than 8 bits now load properly.
v1.0 (LoadSavePNG) - July 24 2003
- Initial release.
|
|