HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
IMG_Format.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: IMG_Format.h ( IMG Library, C++)
7  *
8  * COMMENTS: Declaration of a file format. This class is responsible
9  */
10 
11 #ifndef __IMG_Format__
12 #define __IMG_Format__
13 
14 #include "IMG_API.h"
15 #include "IMG_FileTypes.h"
16 #include <SYS/SYS_Types.h>
17 #include <UT/UT_StringHolder.h>
18 #include <UT/UT_Array.h>
19 
20 class UT_IStream;
21 class UT_String;
22 class IMG_File;
23 class IMG_Stat;
24 class IMG_FileTag;
25 class IMG_FileOptionList;
26 class IMG_FileTagList;
27 
28 extern "C" {
29  // DSO's should have this function declared. All it has to do is create a
30  // format of the new type. This will automatically install the format.
31  // The argument passed in will be a null pointer and can be ignored.
33 };
34 
35 /// Description of a specific image file format, describing the
36 /// characteristics and capabilities of a specific image file format.
37 /// It can be used to query the capabilities of that format (resolution limits,
38 /// data formats supported, image orientation, etc). Image file-specific data
39 /// (such as resolution of a given file) can be found in IMG_Stat. @n
40 /// When writing a new data format, many of the virtuals will need to be
41 /// overridden to properly describe its capabilities.
43 {
44 public:
45  IMG_Format();
46  /// This is a version of the constructor that lets you avoid adding
47  /// oneself to the list. This is used by the pass throug filter and
48  /// must be used if you are in multithreaded code as the underlying
49  /// list is not locked.
50  explicit IMG_Format(bool addtolist);
51  virtual ~IMG_Format();
52 
53  // Types of access for image formats.
55  {
57  WRITE_ACCESS
58  };
59 
60  /// @{
61  /// number of currently installed image formats
62  static int getNFormats();
63  /// Access to the list of currently installed image formats
64  static const IMG_Format *getFormat(int idx);
65  /// @}
66 
67  /// @{
68  /// Find a format given a filename and a stat - only extension matching.
69  /// Will only return formats that can read files (isReadable()).
70  static const IMG_Format *findFormatReadable(const char *filename,
71  const IMG_Stat *stat = 0);
72  /// Find a format given a filename and a stat - only extension matching.
73  /// Will only return formats that can write files (isWritable()).
74  static const IMG_Format *findFormatWritable(const char *filename,
75  const IMG_Stat *stat = 0);
76 
77  static void findFormatReadable(UT_Array<const IMG_Format *> &formats,
78  const char *filename,
79  const IMG_Stat *stat = nullptr);
80  static void findFormatWritable(UT_Array<const IMG_Format *> &formats,
81  const char *filename,
82  const IMG_Stat *stat = nullptr);
83  /// @}
84  static const IMG_Format *findFormatByName(const char *format_name);
85  static const IMG_Format *findFormatByLabel(const char *format_label);
86  // Find a format given a seekable istream.
87  static const IMG_Format *findFormatSeekable(UT_IStream &is);
88  static const IMG_Format *findFormatNonSeekable(UT_IStream &is);
89  static const IMG_Format *findFormatByExtension(const char *filename);
90  static const IMG_Format *getStdoutFormat();
91  IMG_File *allocValidFile() const;
92 
93  /// @{
94  /// All formats must have a unique name (like "JPEG").
95  virtual const char *getFormatName() const = 0;
96  /// If getFormatLabel() is not overridden, the label will be the same as
97  /// the name.
98  virtual const char *getFormatLabel() const;
99  /// @}
100 
101  /// This can be optionally overridden to return a short description of the
102  /// format. By default, no description is given.
103  virtual const char *getFormatDescription() const;
104 
105  /// Flags whether the format is a pass through format like Flip or Scale.
106  /// Specific image formats (like JPEG) are never pass-through.
107  virtual bool isPassThrough() const { return false; }
108 
109  /// The default extension is used to determine whether the format should
110  /// appear in the device/format menus. It should not contain the '.'
111  /// (i.e. "tif" not ".tif")
112  virtual const char *getDefaultExtension() const;
113 
114  /// Describes how the format was loaded (i.e. DSO or internal formats)
115  virtual const char *getFormatLocation() const { return myLocation; }
116 
117  /// @{
118  /// Methods to determine if this is one of our recognized files.
119  /// The extension is the first try. If there are multiple matches,
120  /// then we resort to the magic number (when reading)
121  virtual int checkExtension(const char *filename) const = 0;
122  /// If possible, this magic numver checker will be called. This is
123  /// used if the file is "seekable" (i.e. that we can rewind after checking)
124  virtual int checkMagic(unsigned int) const;
125  /// If possible, this second magic number checker will be called. This is
126  /// used if the file is "seekable" (i.e. that we can rewind after checking)
127  virtual int checkMagicSeekable(UT_IStream &is) const;
128  /// @}
129 
130  /// The device method gives a higher priority to device checks. By default,
131  /// this method returns 0 (no match). This is used to allow things like
132  /// a60:3.pic (which uses the abekas device).
133  virtual int checkDevice(const char *) const;
134 
135  // ------------------------------------------------------------------
136  // Image Format features
137 
138  /// Returns a bitfield of image types supported by this format. By default
139  /// IMG_TYPE_2D is returned.
140  virtual IMG_ImageType getSupportedImageTypes() const;
141 
142  /// Returns a bitfield of data types supported by this format.
143  virtual IMG_DataType getSupportedTypes() const = 0;
144 
145  /// Returns a bitfield of supported color models. If IMG_CM_REVERSED is
146  /// set, this format stores data in BGR/ABGR format.
147  virtual IMG_ColorModel getSupportedColorModels() const = 0;
148 
149  /// Maximum allowable resolution for the file. If a user attempts to write
150  /// an image larger than this, the image will be scaled to this resolution.
151  virtual void getMaxResolution(unsigned &x,
152  unsigned &y) const = 0;
153 
154  /// @{
155  /// Some formats can be read and written in random order. Others require
156  /// strict sequential order. If these methods return false, you should
157  /// read and write scanlines in ascending order. When writing, they will
158  /// be cached until they can be written sequentially.
159  virtual int isReadRandomAccess() const;
160  /// If 0 is returned, the scanlines must be written in sequential order or
161  /// they will be cached until all scanlines can be written sequentially.
162  virtual int isWriteRandomAccess() const;
163  /// @}
164 
165  /// vertical data orientation. Where (0,0) lies in the image
166  /// (top-left by default).
167  virtual int isTopFirst() const;
168 
169  /// horizontal data orientation. Where (0,0) lies in the image
170  /// (top-left by default).
171  virtual int isLeftFirst() const;
172 
173  /// @{
174  /// Specifies if this format can read an image file. One of isReadable()
175  /// or isWritable() (or both) must return true.
176  virtual bool isReadable() const;
177  /// Specifies if this format can write an image file. One of isReadable()
178  /// or isWritable() (or both) must return true.
179  virtual bool isWritable() const;
180  //// @}
181 
182  // data organization.
183 
184  /// does this format support a data window or sub-area.
185  virtual bool isDataWindowSupported() const;
186 
187  /// if true, this format only supports data windows contained within
188  /// the image resolution (a crop region).
189  virtual bool isDataWindowCropOnly() const;
190 
191  /// does this format support saving whether the data outside the window
192  /// is streaked from the window edges?
193  virtual bool isDataWindowStreakSupported() const;
194 
195  /// does this format support deep rasters or multiple images?
196  /// If not, only one plane of the color models that this format supports
197  /// is allowed.
198  virtual bool isDeepRasterSupported() const;
199 
200  /// does this deep raster allow RGBA in one plane (true) or split into
201  /// 2 planes (RGB, A). (default false)
202  virtual IMG_DeepRasterColor getDeepRasterRGBASupport() const;
203 
204  /// Specifies whether this format stores its data interleaved (RGBRGBRGB)
205  /// or non-interleaved (RRRGGGBBB). If your format supports both, pick one.
206  virtual bool isDataInterleaved() const;
207 
208  /// if true, planes can have different data formats & components. Otherwise,
209  /// all planes must have the same data type and number of components.
210  virtual bool canPlaneTypesDiffer() const;
211 
212  /// Returns a list of options that can be set on the format when reading or
213  /// writing (like 'compression' or 'comment').
214  virtual const IMG_FileOptionList *getOptions() const;
215 
216  /// @private
217  // Allocate default tags and their values
218  void defaultTags(IMG_FileTagList &tags) const;
219 
220  /// Set an option globally for all formats. Use with extreme care.
221  static void setGlobalOption(const char *name, const char *value);
222  /// Read the value of a global option. May return a NULL string.
223  static void getGlobalOption(const char *name, UT_String &value);
224 
225  /// Allows you to change an option on a specific format. This will change
226  /// the option for all formats from this point on, whereas setGlobalOption
227  /// would not. Returns false if the format or the option couldn't be found.
228  static bool setFormatOptionDefault(const char *format_name,
229  const char *format_option,
230  const char *defvalue);
231  /// Returns the value of a format-specific option. Returns false if the
232  /// format or option does not exist.
233  static bool getFormatOptionDefault(const char *format_name,
234  const char *format_option,
235  UT_String &defvalue);
236 
237  /// Matches a filename against a single extension
238  static int matchExtension(const char *filename, const char *ext);
239 
240  /// Matches a filename against a list of extensions (the last entry must be
241  /// NULL)
242  static int matchExtensions(const char *filename, const char *ext[]);
243 
244  /// Between these two formats, which should be preferred? returns either
245  /// this or the format parameter. This method is used to resolve
246  /// conflicts between formats when files are being created.
247  virtual const IMG_Format *resolvePriority(const IMG_Format *format)
248  const;
249 
250  /// Some image formats have fixed color spaces, like JPEG (sRGB). The
251  /// default is PXL_CS_UNKNOWN. For formats that can have colorspaces per
252  /// plane, return PXL_CS_UNKNOWN and query the colorspace from IMG_Plane.
253  /// formatColorSpaceGamma() is ignored unless the color space is
254  /// PXL_CS_CUSTOM_GAMMA.
255  /// @{
256  virtual PXL_ColorSpace formatColorSpace() const;
257  virtual fpreal formatColorSpaceGamma() const;
258 
259  /// @}
260 
261  /// Return true if the image format can store the colorspace
262  virtual bool formatStoresColorSpace() const;
263 
264  /// Returns a gamma correction factor when converting from a given color
265  /// space to this image format's space. 'src_data_is_8bit' indicates whether
266  /// data is fixed 8b, in which case it will often be converted to 2.2 gamma.
267  /// If the dest_data_is_8bit is provided, it will use that flag for
268  /// the destination 8bit type instead of the src_data_is_8bit.
269  fpreal adjustGammaForFormat(PXL_ColorSpace src_color_space,
270  fpreal src_color_space_gamma,
271  bool src_data_is_8bit,
272  bool *dest_data_is_8bit = NULL) const;
273 
274  /// @private
275  static void installBasics();
276 
277 protected:
278  // Returns 1 if the stat's are ok for the format specified. For example,
279  // if there's a fixed resolution for a format, the format can nullify the
280  // validity of the format in the determination stage. By default, we
281  // simply check the image depth (i.e. number of images) and compare the max
282  // resolution.
283  virtual IMG_File *createFile() const = 0;
284  virtual int isFormatOk(const IMG_Stat &stat) const;
285  void removeFormatFromList();
286 
287  static const IMG_Format *findFormat(const char *filename,
288  const IMG_Stat *stat,
289  AccessType access);
290  static void findFormat(UT_Array<const IMG_Format *> &list,
291  const char *filename,
292  const IMG_Stat *stat,
293  AccessType access);
294 
295  const IMG_FileTagList *getGlobalTags();
296 
297 private:
298  static const IMG_Format *lookupFormatByName(const char *name,
299  const UT_Array<IMG_Format *> *list);
300  static void loadGlobalOptions(const char *filename);
301  static bool emptyFormats();
302  static void adjustPriorities();
303  UT_StringHolder myLocation;
304 };
305 
306 #endif
307 
GT_API const UT_StringHolder filename
GLuint const GLchar * name
Definition: glew.h:1814
IMG_ImageType
Type of image we want to create or have opened.
#define SYS_VISIBILITY_EXPORT
IMG_DeepRasterColor
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: glew.h:1254
virtual const char * getFormatLocation() const
Describes how the format was loaded (i.e. DSO or internal formats)
Definition: IMG_Format.h:115
#define IMG_API
Definition: IMG_API.h:10
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
GLint GLint GLint GLint GLint GLint y
Definition: glew.h:1252
IMG_DataType
Definition: IMG_FileTypes.h:17
SYS_VISIBILITY_EXPORT void newIMGFormat(void *)
Definition: IMG_Sample.C:322
Generic interface for reading and writing image files. This class handles the reading and writing of ...
Definition: IMG_File.h:55
fpreal64 fpreal
Definition: SYS_Types.h:277
PXL_ColorSpace
Definition: PXL_Common.h:68
IMG_ColorModel
Definition: IMG_FileTypes.h:53
GLenum access
Definition: glew.h:3608
virtual bool isPassThrough() const
Definition: IMG_Format.h:107
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:40
GLsizei const GLfloat * value
Definition: glew.h:1849