Cinder  0.8.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
ImageIo.h
Go to the documentation of this file.
1 /*
2  Copyright (c) 2010, The Barbarian Group
3  All rights reserved.
4 
5  Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.
6 
7 
8  Redistribution and use in source and binary forms, with or without modification, are permitted provided that
9  the following conditions are met:
10 
11  * Redistributions of source code must retain the above copyright notice, this list of conditions and
12  the following disclaimer.
13  * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
14  the following disclaimer in the documentation and/or other materials provided with the distribution.
15 
16  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
17  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
18  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
19  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
20  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
22  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
23  POSSIBILITY OF SUCH DAMAGE.
24 */
25 
26 #pragma once
27 
28 #include "cinder/Cinder.h"
29 #include "cinder/DataSource.h"
30 #include "cinder/DataTarget.h"
31 #include "cinder/Surface.h"
32 #include "cinder/Exception.h"
33 
34 #include <vector>
35 #include <map>
36 #include <utility>
37 
38 namespace cinder {
39 
40 typedef std::shared_ptr<class ImageSource> ImageSourceRef;
41 typedef std::shared_ptr<class ImageLoader> ImageLoaderRef;
42 typedef std::shared_ptr<class ImageTarget> ImageTargetRef;
43 typedef std::shared_ptr<class ImageTargetFile> ImageTargetFileRef;
44 
45 class ImageIo {
46  public:
52  typedef enum ChannelOrder { RGBA, BGRA, ARGB, ABGR, RGBX, BGRX, XRGB, XBGR, RGB, BGR, Y, YA, CUSTOM } ChannelOrder; // Y = Gray/Luminance, X = ignored
53 
54  int32_t getWidth() const { return mWidth; }
55  int32_t getHeight() const { return mHeight; }
56  ColorModel getColorModel() const { return mColorModel; }
57  DataType getDataType() const { return mDataType; }
59  virtual bool hasAlpha() const { return channelOrderHasAlpha( mChannelOrder ); }
60 
61  static void translateRgbColorModelToOffsets( ChannelOrder channelOrder, int8_t *red, int8_t *green, int8_t *blue, int8_t *alpha, int8_t *inc );
62  static void translateGrayColorModelToOffsets( ChannelOrder channelOrder, int8_t *gray, int8_t *alpha, int8_t *inc );
63  static bool channelOrderHasAlpha( ChannelOrder channelOrder );
64  static int8_t channelOrderNumChannels( ChannelOrder channelOrder );
65  static uint8_t dataTypeBytes( DataType dataType );
66 
68  static std::vector<std::string> getLoadExtensions();
70  static std::vector<std::string> getWriteExtensions();
71 
72  protected:
73  ImageIo();
74 
75  void setSize( int32_t width, int32_t height ) { mWidth = width; mHeight = height; }
76  void setColorModel( ColorModel colorModel ) { mColorModel = colorModel; }
77  void setDataType( DataType aDataType ) { mDataType = aDataType; }
78  void setChannelOrder( ChannelOrder aChannelOrder ) { mChannelOrder = aChannelOrder; }
79 
80  int32_t mWidth, mHeight;
84 };
85 
86 class ImageSource : public ImageIo {
87  public:
89  virtual ~ImageSource() {}
90 
92  class Options {
93  public:
94  Options() : mIndex( 0 ), mThrowOnFirstException( false ) {}
95 
97  Options& index( int32_t index ) { mIndex = index; return *this; }
99  Options& throwOnFirstException( bool b = true ) { mThrowOnFirstException = b; return *this; }
100 
102  int32_t getIndex() const { return mIndex; }
105 
106  protected:
107  int32_t mIndex;
109  };
110 
112  float getPixelAspectRatio() const;
114  bool isPremultiplied() const;
115 
116  virtual void load( ImageTargetRef target ) = 0;
117 
118  typedef void (ImageSource::*RowFunc)(ImageTargetRef, int32_t, const void*);
119 
120  protected:
121  void setPixelAspectRatio( float pixelAspectRatio ) { mPixelAspectRatio = pixelAspectRatio; }
122  void setPremultiplied( bool premult = true ) { mIsPremultiplied = premult; }
124  void setCustomPixelInc( int8_t customPixelInc ) { mCustomPixelInc = customPixelInc; }
125 
129  template<typename SD, typename TD, ColorModel TCS>
131  template<typename SD, typename TD>
133  template<typename SD>
135 
136  template<typename SD, typename TD, ImageIo::ColorModel TCM, bool ALPHA>
137  void rowFuncSourceRgb( ImageTargetRef target, int32_t row, const void *data );
138  template<typename SD, typename TD, ColorModel TCM, bool ALPHA>
139  void rowFuncSourceGray( ImageTargetRef target, int32_t row, const void *data );
140 
144 
149 };
150 
151 class ImageTarget : public ImageIo {
152  public:
153  virtual ~ImageTarget() {};
154 
155  virtual void* getRowPointer( int32_t row ) = 0;
156  virtual void setRow( int32_t row, const void *data ) { throw; }
157  virtual void finalize() { }
158 
159  class Options {
160  public:
161  Options() : mQuality( 0.9f ), mColorModelDefault( true ) {}
162 
163  Options& quality( float quality ) { mQuality = quality; return *this; }
164  Options& colorModel( ImageIo::ColorModel cm ) { mColorModelDefault = false; mColorModel = cm; return *this; }
165 
167 
168  float getQuality() const { return mQuality; }
169  bool isColorModelDefault() const { return mColorModelDefault; }
171 
172  protected:
173  float mQuality;
176  };
177 
178  protected:
180 };
181 
182 #if defined( CINDER_WINRT )
183 
185 void loadImageAsync(const fs::path path, std::function<void (ImageSourceRef)> callback, ImageSource::Options options = ImageSource::Options(), std::string extension = "" );
186 #endif
187 
188 
190 ImageSourceRef loadImage( const fs::path &path, ImageSource::Options options = ImageSource::Options(), std::string extension = "" );
192 ImageSourceRef loadImage( DataSourceRef dataSource, ImageSource::Options options = ImageSource::Options(), std::string extension = "" );
194 void writeImage( DataTargetRef dataTarget, const ImageSourceRef &imageSource, ImageTarget::Options options = ImageTarget::Options(), std::string extension = "" );
197 void writeImage( const fs::path &path, const ImageSourceRef &imageSource, ImageTarget::Options options = ImageTarget::Options(), std::string extension = "" );
199 void writeImage( ImageTargetRef imageTarget, const ImageSourceRef &imageSource );
200 
201 class ImageIoException : public Exception {
202  public:
203  ImageIoException( const std::string &description = "" ) : mDescription( description ) {}
204  virtual const char* what() const throw() { return mDescription.c_str(); }
205  protected:
207 };
208 
210  public:
211  ImageIoExceptionFailedLoad( const std::string &description = "" ) : ImageIoException( description ) {}
212 };
213 
215  public:
216  ImageIoExceptionFailedWrite( const std::string &description = "" ) : ImageIoException( description ) {}
217 };
218 
220  public:
221  ImageIoExceptionUnknownExtension( const std::string &description = "" ) : ImageIoException( description ) {}
222 };
223 
225  public:
226  ImageIoExceptionIllegalColorModel( const std::string &description = "" ) : ImageIoException( description ) {}
227 };
228 
230  public:
231  ImageIoExceptionIllegalDataType( const std::string &description = "" ) : ImageIoException( description ) {}
232 };
233 
235  public:
236  ImageIoExceptionIllegalChannelOrder( const std::string &description = "" ) : ImageIoException( description ) {}
237 };
238 
239 
243 
244  static ImageSourceRef createSource( DataSourceRef dataSource, ImageSource::Options options, std::string extension );
245  static ImageTargetRef createTarget( DataTargetRef dataTarget, ImageSourceRef imageSource, ImageTarget::Options options, std::string extension );
246 
247  static void registerSourceType( std::string extension, SourceCreationFunc func, int32_t priority = 2 );
248  static void registerSourceGeneric( SourceCreationFunc func, int32_t priority = 2 );
249 
250  static void registerTargetType( std::string extension, TargetCreationFunc func, int32_t priority, const std::string &extensionData );
251 
252  private:
253 
254  struct Inst {
255  void registerSourceType( std::string extension, SourceCreationFunc func, int32_t priority );
256  void registerSourceGeneric( SourceCreationFunc func, int32_t priority );
257  void registerTargetType( std::string extension, TargetCreationFunc func, int32_t priority, const std::string &extensionData );
258 
260  ImageTargetRef createTarget( DataTargetRef dataTarget, ImageSourceRef imageSource, ImageTarget::Options options, std::string extension );
261 
262  std::map<std::string, std::multimap<int32_t,SourceCreationFunc> > mSources;
263  std::map<int32_t, SourceCreationFunc> mGenericSources;
264  std::map<std::string, std::multimap<int32_t,std::pair<TargetCreationFunc,std::string> > > mTargets;
265  };
266 
267  static ImageIoRegistrar::Inst* instance();
268 
269  friend class ImageIo;
270 };
271 
272 template<typename T>
275  (void) register_object;
276  }
277  private:
278  struct exec_register {
279  exec_register() {
280  T::registerSelf();
281  }
282  };
283 
284  static exec_register register_object;
285 };
286 
287 template<typename D> typename ImageIoRegistrant<D>::exec_register ImageIoRegistrant<D>::register_object;
288 
289 #define REGISTER_IMAGE_IO_FILE_HANDLER( TYPE ) \
290 struct ImageIoRegisterT##TYPE : public ImageIoRegistrant<TYPE> { \
291  ImageIoRegisterT##TYPE() : ImageIoRegistrant<TYPE>() {} \
292 };
293 
294 } // namespace cinder
ImageIoException(const std::string &description="")
Definition: ImageIo.h:203
int8_t mRowFuncSourceGray
Definition: ImageIo.h:147
float mPixelAspectRatio
Definition: ImageIo.h:141
void writeImage(DataTargetRef dataTarget, const ImageSourceRef &imageSource, ImageTarget::Options options=ImageTarget::Options(), std::string extension="")
Writes imageSource to dataTarget. Optional extension parameter allows specification of a file type...
Definition: ImageIo.cpp:430
ImageIoExceptionUnknownExtension(const std::string &description="")
Definition: ImageIo.h:221
ChannelOrder
Definition: ImageIo.h:52
static void translateRgbColorModelToOffsets(ChannelOrder channelOrder, int8_t *red, int8_t *green, int8_t *blue, int8_t *alpha, int8_t *inc)
Definition: ImageIo.cpp:59
Options & throwOnFirstException(bool b=true)
If an exception occurs, enabling this will prevent any attempts at using other handlers to load the i...
Definition: ImageIo.h:99
Definition: ImageIo.h:240
int8_t mRowFuncTargetGreen
Definition: ImageIo.h:146
GLclampf green
Definition: GLee.h:951
ColorModel getColorModel() const
Definition: ImageIo.h:56
static int8_t channelOrderNumChannels(ChannelOrder channelOrder)
Definition: ImageIo.cpp:87
RowFunc setupRowFuncForTypes(ImageTargetRef target)
Definition: ImageIo.cpp:320
Definition: ImageIo.h:52
Definition: ImageIo.h:48
int8_t mRowFuncTargetRed
Definition: ImageIo.h:146
Definition: ImageIo.h:50
static void registerTargetType(std::string extension, TargetCreationFunc func, int32_t priority, const std::string &extensionData)
Definition: ImageIo.cpp:553
int8_t mRowFuncSourceBlue
Definition: ImageIo.h:145
Options & quality(float quality)
Definition: ImageIo.h:163
int32_t getWidth() const
Definition: ImageIo.h:54
int8_t mRowFuncSourceRed
Definition: ImageIo.h:145
GLsizei const GLchar ** string
Definition: GLee.h:2427
Definition: ImageIo.h:49
static void translateGrayColorModelToOffsets(ChannelOrder channelOrder, int8_t *gray, int8_t *alpha, int8_t *inc)
Definition: ImageIo.cpp:77
float getQuality() const
Definition: ImageIo.h:168
Definition: ImageIo.h:49
ImageIoExceptionIllegalChannelOrder(const std::string &description="")
Definition: ImageIo.h:236
Definition: ImageIo.h:49
ImageSourceRef loadImage(const fs::path &path, ImageSource::Options options=ImageSource::Options(), std::string extension="")
Loads an image from the file path path. Optional extension parameter allows specification of a file t...
Definition: ImageIo.cpp:405
int8_t mRowFuncTargetInc
Definition: ImageIo.h:148
bool mThrowOnFirstException
Definition: ImageIo.h:108
virtual ~ImageTarget()
Definition: ImageIo.h:153
GLenum GLsizei width
Definition: GLee.h:969
Definition: ImageIo.h:52
Definition: ImageIo.h:47
Definition: ImageIo.h:52
Definition: ImageIo.h:52
GLuint index
Definition: GLee.h:2259
GLsizei GLsizei GLenum GLenum const GLvoid * data
Definition: GLee.h:1011
Options()
Definition: ImageIo.h:94
bool mIsPremultiplied
Definition: ImageIo.h:142
ChannelOrder getChannelOrder() const
Definition: ImageIo.h:58
void setChannelOrder(ChannelOrder aChannelOrder)
Definition: ImageIo.h:78
GLenum target
Definition: GLee.h:13607
typedef void(APIENTRYP GLEEPFNGLBLENDCOLORPROC)(GLclampf red
Definition: ImageIo.h:50
int32_t getHeight() const
Definition: ImageIo.h:55
Definition: ImageIo.h:151
std::shared_ptr< class ImageLoader > ImageLoaderRef
Definition: ImageIo.h:41
Definition: ImageIo.h:47
DataType getDataType() const
Definition: ImageIo.h:57
void setupRowFuncRgbSource(ImageTargetRef target)
Definition: ImageIo.cpp:269
Definition: ImageIo.h:50
Definition: ImageIo.h:48
bool mColorModelDefault
Definition: ImageIo.h:174
Definition: ImageIo.h:209
std::shared_ptr< class ImageTarget > ImageTargetRef
Definition: ImageIo.h:42
ImageIo()
Definition: ImageIo.cpp:54
ImageIo::ColorModel getColorModel() const
Definition: ImageIo.h:170
Definition: ImageIo.h:49
Definition: ImageIo.h:273
RowFunc setupRowFuncForSourceType(ImageTargetRef target)
Definition: ImageIo.cpp:336
Definition: ImageIo.h:50
RowFunc setupRowFunc(ImageTargetRef target)
Definition: ImageIo.cpp:354
Definition: ImageIo.h:50
int32_t mHeight
Definition: ImageIo.h:80
GLenum GLenum GLvoid * row
Definition: GLee.h:1089
void rowFuncSourceGray(ImageTargetRef target, int32_t row, const void *data)
Definition: ImageIo.cpp:218
virtual void setRow(int32_t row, const void *data)
Definition: ImageIo.h:156
DataType
Definition: ImageIo.h:48
static bool channelOrderHasAlpha(ChannelOrder channelOrder)
Definition: ImageIo.cpp:107
Definition: ImageIo.h:201
int8_t mRowFuncTargetBlue
Definition: ImageIo.h:146
virtual const char * what() const
Definition: ImageIo.h:204
ColorModel
Definition: ImageIo.h:47
GLclampf GLclampf blue
Definition: GLee.h:951
Definition: ImageIo.h:159
void setDataType(DataType aDataType)
Definition: ImageIo.h:77
ImageIo::ColorModel mColorModel
Definition: ImageIo.h:175
ImageSourceRef(* SourceCreationFunc)(DataSourceRef, ImageSource::Options options)
Definition: ImageIo.h:241
DataType mDataType
Definition: ImageIo.h:82
void setCustomPixelInc(int8_t customPixelInc)
Allows declaration of a pixel increment different from what its ColorModel would imply. For example a non-planar Channel.
Definition: ImageIo.h:124
int8_t mRowFuncSourceAlpha
Definition: ImageIo.h:145
virtual bool hasAlpha() const
Definition: ImageIo.h:59
GLenum GLsizei GLsizei height
Definition: GLee.h:1029
GLclampf GLclampf GLclampf alpha
Definition: GLee.h:951
Definition: ImageIo.h:49
std::shared_ptr< class ImageTargetFile > ImageTargetFileRef
Definition: ImageIo.h:43
Definition: ImageIo.h:52
int8_t mRowFuncSourceInc
Definition: ImageIo.h:148
float getPixelAspectRatio() const
Returns the aspect ratio of individual pixels to accommodate non-square pixels.
Definition: ImageIo.cpp:155
static void registerSourceType(std::string extension, SourceCreationFunc func, int32_t priority=2)
Definition: ImageIo.cpp:527
Options & colorModel(ImageIo::ColorModel cm)
Definition: ImageIo.h:164
static ImageTargetRef createTarget(DataTargetRef dataTarget, ImageSourceRef imageSource, ImageTarget::Options options, std::string extension)
Definition: ImageIo.cpp:467
int32_t mWidth
Definition: ImageIo.h:80
Definition: ImageIo.h:49
int8_t mRowFuncTargetGray
Definition: ImageIo.h:147
Definition: ImageIo.h:49
bool isPremultiplied() const
Returns whether the ImageSource's color data has been premultiplied by its alpha channel.
Definition: ImageIo.cpp:160
ColorModel mColorModel
Definition: ImageIo.h:81
Definition: ImageIo.h:50
ChannelOrder mChannelOrder
Definition: ImageIo.h:83
void rowFuncSourceRgb(ImageTargetRef target, int32_t row, const void *data)
Definition: ImageIo.cpp:167
void setupRowFuncGraySource(ImageTargetRef target)
Definition: ImageIo.cpp:278
Definition: ImageIo.h:47
ChannelType
Definition: ImageIo.h:49
std::string mDescription
Definition: ImageIo.h:206
static ImageSourceRef createSource(DataSourceRef dataSource, ImageSource::Options options, std::string extension)
Definition: ImageIo.cpp:486
Optional parameters passed when creating an Image.
Definition: ImageIo.h:92
virtual void finalize()
Definition: ImageIo.h:157
GLboolean GLboolean GLboolean b
Definition: GLee.h:2964
static void registerSourceGeneric(SourceCreationFunc func, int32_t priority=2)
Definition: ImageIo.cpp:574
int8_t mRowFuncSourceGreen
Definition: ImageIo.h:145
Definition: ImageIo.h:52
bool isColorModelDefault() const
Definition: ImageIo.h:169
virtual void load(ImageTargetRef target)=0
Definition: ImageIo.h:52
void(ImageSource::* RowFunc)(ImageTargetRef, int32_t, const void *)
Definition: ImageIo.h:118
Definition: ImageIo.h:49
Definition: ImageIo.h:52
Definition: ImageIo.h:214
void setPixelAspectRatio(float pixelAspectRatio)
Definition: ImageIo.h:121
Definition: ImageIo.h:52
Definition: ImageIo.h:49
Definition: ImageIo.h:52
ImageTargetRef(* TargetCreationFunc)(DataTargetRef, ImageSourceRef, ImageTarget::Options options, const std::string &)
Definition: ImageIo.h:242
void setColorModel(ColorModel colorModel)
Definition: ImageIo.h:76
virtual void * getRowPointer(int32_t row)=0
static uint8_t dataTypeBytes(DataType dataType)
Definition: ImageIo.cpp:121
std::shared_ptr< class DataTarget > DataTargetRef
Definition: DataTarget.h:33
RowFunc setupRowFuncForTypesAndTargetColorModel(ImageTargetRef target)
Definition: ImageIo.cpp:288
Definition: ImageIo.h:50
int32_t mIndex
Definition: ImageIo.h:107
Definition: ImageIo.h:52
ImageIoExceptionFailedLoad(const std::string &description="")
Definition: ImageIo.h:211
Definition: ImageIo.h:48
int8_t mRowFuncTargetAlpha
Definition: ImageIo.h:146
virtual ~ImageSource()
Definition: ImageIo.h:89
bool getThrowOnFirstException()
Returns whether throwOnFirstException() is enabled or not.
Definition: ImageIo.h:104
Definition: ImageIo.h:52
Definition: ImageIo.h:45
Definition: Exception.h:32
static std::vector< std::string > getLoadExtensions()
Definition: ImageIo.cpp:132
Definition: ImageIo.h:51
void setPremultiplied(bool premult=true)
Definition: ImageIo.h:122
ImageSource()
Definition: ImageIo.h:88
Options & index(int32_t index)
Specifies an image index for multi-part images, like animated GIFs.
Definition: ImageIo.h:97
int32_t getIndex() const
Returns image index.
Definition: ImageIo.h:102
ImageIoRegistrant()
Definition: ImageIo.h:274
std::shared_ptr< class ImageSource > ImageSourceRef
Definition: Channel.h:33
Definition: ImageIo.h:52
void setSize(int32_t width, int32_t height)
Definition: ImageIo.h:75
ImageIoExceptionFailedWrite(const std::string &description="")
Definition: ImageIo.h:216
std::shared_ptr< class DataSource > DataSourceRef
Definition: DataSource.h:35
static std::vector< std::string > getWriteExtensions()
Definition: ImageIo.cpp:142
GLclampf f
Definition: GLee.h:15307
Options()
Definition: ImageIo.h:161
int8_t mCustomPixelInc
Definition: ImageIo.h:143
float mQuality
Definition: ImageIo.h:173
Definition: ImageIo.h:86
ImageIoExceptionIllegalColorModel(const std::string &description="")
Definition: ImageIo.h:226
ImageTarget()
Definition: ImageIo.h:179
void setColorModelDefault()
Definition: ImageIo.h:166
Definition: ImageIo.h:48
ImageIoExceptionIllegalDataType(const std::string &description="")
Definition: ImageIo.h:231