Tekkotsu Homepage | Demos | Overview | Downloads | Dev. Resources | Reference | Credits |
ImageUtil.hGo 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 |