Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

ImageUtil.h

Go to the documentation of this file.
00001 //-*-c++-*-
00002 #ifndef INCLUDED_image_util_h_
00003 #define INCLUDED_image_util_h_
00004 
00005 #include <string>
00006 
00007 struct jpeg_compress_struct;
00008 
00009 //! Provides a variety of straightforward calls to compress or decompress images in JPEG or PNG formats
00010 namespace image_util {
00011   
00012   //! @name Generic File Utilities
00013   
00014   //! loads a file into memory, returns true if successful, storing resulting buffer information in @a buf and @a size
00015   /*! uses mmap unless LOADFILE_NO_MMAP is defined, in which case it uses 'new' and fread() */
00016   bool loadFile(const std::string& file, char*& buf, size_t& size);
00017   //! releases memory from a previous call to loadFile, triggering munmap() or 'delete' as appropriate
00018   void releaseFile(char* buf, size_t size);
00019   
00020   //@}
00021   
00022   
00023   
00024   //! @name Decode Header Information (from memory buffer)
00025   
00026   //! decodes an image header already in memory -- if it looks like a PNG decodePNG() will be called, otherwise decodeJPEG(); returns true if successful
00027   /*! @param inbuf input memory buffer containing compressed image
00028    *  @param inbufSize the size of @a inbuf allocation
00029    *  @param width the image width
00030    *  @param height the image height
00031    *  @param channels the number of color channels*/
00032   bool decodeImage(char* inbuf, size_t inbufSize, size_t& width, size_t& height, size_t& channels);
00033   
00034   //! decodes a JPEG header already in memory, returns true if successful
00035   /*! @param inbuf input memory buffer containing compressed image
00036    *  @param inbufSize the size of @a inbuf allocation
00037    *  @param width the image width
00038    *  @param height the image height
00039    *  @param channels the number of color channels */
00040   bool decodeJPEG(char* inbuf, size_t inbufSize, size_t& width, size_t& height, size_t& channels);
00041 
00042   //! decodes a PNG header already in memory, returns true if successful
00043   /*! @param inbuf input memory buffer containing compressed image
00044    *  @param inbufSize the size of @a inbuf allocation
00045    *  @param width the image width
00046    *  @param height the image height
00047    *  @param channels the number of color channels */
00048   bool decodePNG(char* inbuf, size_t inbufSize, size_t& width, size_t& height, size_t& channels);
00049   
00050   //@}
00051   
00052   
00053   
00054   //! @name Decompress From Memory Buffer
00055   
00056   //! decodes an image already in memory -- if it looks like a PNG decodePNG() will be called, otherwise decodeJPEG(); returns true if successful
00057   /*! @param inbuf input memory buffer containing compressed image
00058    *  @param inbufSize the size of @a inbuf allocation
00059    *  @param width the image width
00060    *  @param height the image height
00061    *  @param channels the number of color channels
00062    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00063    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00064    *
00065    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00066    * (This is a handy way to read the image header only -- pass ((char*)NULL)-1 as @a outbuf and 0 for @a outbufSize,
00067    * the function will return false after reading the header and filling in width, height, and channels)
00068    * The image will be written in row order, with channels interleaved. */
00069   bool decodeImage(char* inbuf, size_t inbufSize, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize);
00070   
00071   //! decodes a JPEG image already in memory, returns true if successful
00072   /*! @param inbuf input memory buffer containing compressed image
00073    *  @param inbufSize the size of @a inbuf allocation
00074    *  @param width the image width
00075    *  @param height the image height
00076    *  @param channels the number of color channels
00077    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00078    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00079    *  @param filename optional parameter, used if warnings are raised
00080    *
00081    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00082    * The image will be written in row order, with channels interleaved. */
00083   bool decodeJPEG(char* inbuf, size_t inbufSize, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize, const std::string& filename="");
00084 
00085   //! decodes a PNG image already in memory, returns true if successful
00086   /*! @param inbuf input memory buffer containing compressed image
00087    *  @param inbufSize the size of @a inbuf allocation
00088    *  @param width the image width
00089    *  @param height the image height
00090    *  @param channels the number of color channels
00091    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00092    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00093    *
00094    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00095    * The image will be written in row order, with channels interleaved. */
00096   bool decodePNG(char* inbuf, size_t inbufSize, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize);
00097   
00098   //@}
00099   
00100   
00101   
00102   //! @name Decompress From Input Stream
00103   
00104   //! decodes a JPEG image from a standard library input stream, returns true if successful
00105   /*! @param inStream input stream providing image
00106    *  @param width the image width
00107    *  @param height the image height
00108    *  @param channels the number of color channels
00109    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00110    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00111    *  @param filename optional parameter, used if warnings are raised
00112    *
00113    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00114    * The image will be written in row order, with channels interleaved. */
00115   bool decodeJPEG(std::istream& inStream, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize, const std::string& filename="");
00116 
00117   //! decodes a PNG image from a standard library input stream, returns true if successful
00118   /*! @param inStream input stream from which to read images
00119    *  @param width the image width
00120    *  @param height the image height
00121    *  @param channels the number of color channels
00122    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00123    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00124    *
00125    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00126    * The image will be written in row order, with channels interleaved. */
00127   bool decodePNG(std::istream& inStream, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize);
00128   
00129   //@}
00130   
00131   
00132   
00133   //! @name Decompress from File
00134   
00135   //! decodes an image from file on disk -- if it looks like a PNG decodePNG() will be called, otherwise decodeJPEG(); returns true if successful
00136   /*! @param file path to file to load
00137    *  @param width the image width
00138    *  @param height the image height
00139    *  @param channels the number of color channels
00140    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00141    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00142    *
00143    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00144    * The image will be written in row order, with channels interleaved. */
00145   bool loadImage(const std::string& file, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize);
00146   
00147   //! decodes a JPEG from disk, returns true if successful
00148   /*! @param file path to file to load
00149    *  @param width the image width
00150    *  @param height the image height
00151    *  @param channels the number of color channels
00152    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00153    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00154    *
00155    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00156    * The image will be written in row order, with channels interleaved. */
00157   bool loadJPEG(const std::string& file, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize);
00158   
00159   //! decodes a PNG from disk, returns true if successful
00160   /*! @param file path to file to load
00161    *  @param width the image width
00162    *  @param height the image height
00163    *  @param channels the number of color channels
00164    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00165    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00166    *
00167    * If @a outbuf is pre-allocated and outbufSize is less than width*height*channels, the function will return false.
00168    * The image will be written in row order, with channels interleaved. */
00169   bool loadPNG(const std::string& file, size_t& width, size_t& height, size_t& channels, char*& outbuf, size_t& outbufSize);
00170   
00171   //@}
00172   
00173   
00174   
00175   //! @name Compression (In-Memory only)
00176   
00177   //! encodes a JPEG from a pixel buffer into another memory buffer, returns number of bytes used, 0 if error
00178   /*! @param inbuf input memory buffer containing the image
00179    *  @param inbufSize the size of @a inbuf allocation
00180    *  @param width the image width
00181    *  @param height the image height
00182    *  @param inbufChannels the number of color channels in the source image; either 1 (grayscale), or 3 (color)
00183    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00184    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00185    *  @param outbufChannels the number of color channels desired in the destination image (only downsample from color to grayscale)
00186    *  @param quality how well to reproduce the image, 0-100
00187    *
00188    *  If @a outbuf is NULL, one of size @f$ width \cdot height \cdot outbufChannels \cdot (quality/2+25)/100+500 @f$ will be allocated for you.
00189    *  (just a heuristic size... note that this won't all be used, and can't entirely guarantee it'll be enough!)
00190    *
00191    *  If @a inbufChannels is 3, @a outbufChannels can be either 3 or 1.  If 1, the first channel of
00192    *  @a inbuf is used.  (pre-increment @a inbuf to use a different channel...)  If @a inbufChannels
00193    *  is 1, outbufChannels must also be 1. */
00194   size_t encodeJPEG(char* inbuf, size_t inbufSize, size_t width, size_t height, size_t inbufChannels, char*& outbuf, size_t& outbufSize, size_t outbufChannels, int quality);
00195   
00196   //! encodes a JPEG from a pixel buffer into another memory buffer, returns number of bytes used, 0 if error
00197   /*! @param inbuf input memory buffer containing the image
00198    *  @param inbufSize the size of @a inbuf allocation
00199    *  @param width the image width
00200    *  @param height the image height
00201    *  @param inbufChannels the number of color channels in the source image; either 1 (grayscale), or 3 (color)
00202    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00203    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00204    *  @param outbufChannels the number of color channels desired in the destination image (only downsample from color to grayscale)
00205    *  @param quality how well to reproduce the image, 0-100
00206    *  @param cinfo allows you to use a pre-allocated jpeg structure instead of having the function recreate it each time
00207    *
00208    *  If @a outbuf is NULL, one of size @f$ width \cdot height \cdot outbufChannels \cdot (quality/2+25)/100+500 @f$ will be allocated for you.
00209    *  (just a heuristic size... note that this won't all be used, and can't entirely guarantee it'll be enough!)
00210    *
00211    *  If @a inbufChannels is 3, @a outbufChannels can be either 3 or 1.  If 1, the first channel of
00212    *  @a inbuf is used.  (pre-increment @a inbuf to use a different channel...)  If @a inbufChannels
00213    *  is 1, outbufChannels must also be 1. */
00214   size_t encodeJPEG(char* inbuf, size_t inbufSize, size_t width, size_t height, size_t inbufChannels, char*& outbuf, size_t& outbufSize, size_t outbufChannels, int quality, jpeg_compress_struct& cinfo);
00215   
00216   //! encodes a JPEG from a pixel buffer into another memory buffer, returns number of bytes used, 0 if error
00217   /*! @param inbuf input memory buffer containing the image
00218    *  @param inbufSize the size of @a inbuf allocation
00219    *  @param width the image width
00220    *  @param height the image height
00221    *  @param inbufChannels the number of color channels in the source image; either 1 (grayscale), or 3 (color)
00222    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00223    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00224    *  @param outbufChannels the number of color channels desired in the destination image (only downsample from color to grayscale)
00225    *  @param quality how well to reproduce the image, 0-100
00226    *  @param yskip increment for the y channel
00227    *  @param uvskip increment for the u and v channels
00228    *  @param cinfo allows you to use a pre-allocated jpeg structure instead of having the function recreate it each time
00229    *
00230    *  If @a outbuf is NULL, one of size @f$ width \cdot height \cdot outbufChannels \cdot (quality/2+25)/100+500 @f$ will be allocated for you.
00231    *  (just a heuristic size... note that this won't all be used, and can't entirely guarantee it'll be enough!)
00232    *
00233    *  If @a inbufChannels is 3, @a outbufChannels can be either 3 or 1.  If 1, the first channel of
00234    *  @a inbuf is used.  (pre-increment @a inbuf to use a different channel...)  If @a inbufChannels
00235    *  is 1, outbufChannels must also be 1. */
00236   size_t encodeJPEG(char* inbuf, size_t inbufSize, size_t width, size_t height, size_t inbufChannels, char*& outbuf, size_t& outbufSize, size_t outbufChannels, int quality, unsigned int yskip, unsigned int uvskip, jpeg_compress_struct& cinfo);
00237 
00238   //! encodes a JPEG from a pixel buffer into another memory buffer, returns number of bytes used, 0 if error
00239   /*! @param inbuf input memory buffer containing the image
00240    *  @param inbufSize the size of @a inbuf allocation
00241    *  @param width the image width
00242    *  @param height the image height
00243    *  @param inbufChannels the number of color channels in the source image; either 1 (grayscale), or 3 (color); must match @a outbufChannels
00244    *  @param outbuf on input, a buffer to use for decompression; if NULL, a new buffer will be allocated and assigned
00245    *  @param outbufSize if @a outbuf is non-NULL, this should indicate the size of @a outbuf
00246    *  @param outbufChannels the number of color channels desired in the destination image; must match @a inbufChannels
00247    *
00248    *  If @a outbuf is NULL, one of size @f$ width \cdot height \cdot outbufChannels + 500 @f$ will be allocated for you.
00249    *  (just a heuristic size... note that this won't all be used, and can't entirely guarantee it'll be enough!)
00250    *
00251    *  Currently doesn't support changes in channels, so @a inbufChannels must match @a outbufChannels */
00252   size_t encodePNG(char* inbuf, size_t inbufSize, size_t width, size_t height, size_t inbufChannels, char*& outbuf, size_t& outbufSize, size_t outbufChannels);
00253   
00254   //@}
00255   
00256 };
00257 
00258 /*! @file
00259  * @brief 
00260  * @author Ethan Tira-Thompson (ejt) (Creator)
00261  *
00262  * $Author: ejt $
00263  * $Name: tekkotsu-4_0 $
00264  * $Revision: 1.9 $
00265  * $State: Exp $
00266  * $Date: 2007/11/13 23:32:29 $
00267  */
00268 
00269 #endif

Tekkotsu v4.0
Generated Thu Nov 22 00:54:53 2007 by Doxygen 1.5.4