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(
79  const char *filename,
80  const IMG_Stat *stat = nullptr,
81  const UT_Array<const IMG_Format*> *image_formats = nullptr);
82  static void findFormatWritable(
84  const char *filename,
85  const IMG_Stat *stat = nullptr,
86  const UT_Array<const IMG_Format*> *image_formats = nullptr);
87 
88  /// @}
89  static const IMG_Format *findFormatByName(const char *format_name);
90  static const IMG_Format *findFormatByLabel(const char *format_label);
91  // Find a format given a seekable istream.
92  static const IMG_Format *findFormatSeekable(UT_IStream &is);
93  static const IMG_Format *findFormatNonSeekable(UT_IStream &is);
94  static const IMG_Format *findFormatByExtension(const char *filename);
95  static const IMG_Format *getStdoutFormat();
96  IMG_File *allocValidFile() const;
97 
98  /// @{
99  /// All formats must have a unique name (like "JPEG").
100  virtual const char *getFormatName() const = 0;
101  /// If getFormatLabel() is not overridden, the label will be the same as
102  /// the name.
103  virtual const char *getFormatLabel() const;
104  /// @}
105 
106  /// This can be optionally overridden to return a short description of the
107  /// format. By default, no description is given.
108  virtual const char *getFormatDescription() const;
109 
110  /// Flags whether the format is a pass through format like Flip or Scale.
111  /// Specific image formats (like JPEG) are never pass-through.
112  virtual bool isPassThrough() const { return false; }
113 
114  /// The default extension is used to determine whether the format should
115  /// appear in the device/format menus. It should not contain the '.'
116  /// (i.e. "tif" not ".tif")
117  virtual const char *getDefaultExtension() const;
118 
119  /// Describes how the format was loaded (i.e. DSO or internal formats)
120  virtual const char *getFormatLocation() const { return myLocation; }
121 
122  /// @{
123  /// Methods to determine if this is one of our recognized files.
124  /// The extension is the first try. If there are multiple matches,
125  /// then we resort to the magic number (when reading)
126  virtual int checkExtension(const char *filename) const = 0;
127  /// If possible, this magic numver checker will be called. This is
128  /// used if the file is "seekable" (i.e. that we can rewind after checking)
129  virtual int checkMagic(unsigned int) const;
130  /// If possible, this second magic number checker will be called. This is
131  /// used if the file is "seekable" (i.e. that we can rewind after checking)
132  virtual int checkMagicSeekable(UT_IStream &is) const;
133  /// @}
134 
135  /// The device method gives a higher priority to device checks. By default,
136  /// this method returns 0 (no match). This is used to allow things like
137  /// a60:3.pic (which uses the abekas device).
138  virtual int checkDevice(const char *) const;
139 
140  // ------------------------------------------------------------------
141  // Image Format features
142 
143  /// Returns a bitfield of image types supported by this format. By default
144  /// IMG_TYPE_2D is returned.
145  virtual IMG_ImageType getSupportedImageTypes() const;
146 
147  /// Returns a bitfield of data types supported by this format.
148  virtual IMG_DataType getSupportedTypes() const = 0;
149 
150  /// Returns a bitfield of supported color models. If IMG_CM_REVERSED is
151  /// set, this format stores data in BGR/ABGR format.
152  virtual IMG_ColorModel getSupportedColorModels() const = 0;
153 
154  /// Maximum allowable resolution for the file. If a user attempts to write
155  /// an image larger than this, the image will be scaled to this resolution.
156  virtual void getMaxResolution(unsigned &x,
157  unsigned &y) const = 0;
158 
159  /// @{
160  /// Some formats can be read and written in random order. Others require
161  /// strict sequential order. If these methods return false, you should
162  /// read and write scanlines in ascending order. When writing, they will
163  /// be cached until they can be written sequentially.
164  virtual int isReadRandomAccess() const;
165  /// If 0 is returned, the scanlines must be written in sequential order or
166  /// they will be cached until all scanlines can be written sequentially.
167  virtual int isWriteRandomAccess() const;
168  /// @}
169 
170  /// vertical data orientation. Where (0,0) lies in the image
171  /// (top-left by default).
172  virtual int isTopFirst() const;
173 
174  /// horizontal data orientation. Where (0,0) lies in the image
175  /// (top-left by default).
176  virtual int isLeftFirst() const;
177 
178  /// @{
179  /// Specifies if this format can read an image file. One of isReadable()
180  /// or isWritable() (or both) must return true.
181  virtual bool isReadable() const;
182  /// Specifies if this format can write an image file. One of isReadable()
183  /// or isWritable() (or both) must return true.
184  virtual bool isWritable() const;
185  //// @}
186 
187  // data organization.
188 
189  /// does this format support a data window or sub-area.
190  virtual bool isDataWindowSupported() const;
191 
192  /// if true, this format only supports data windows contained within
193  /// the image resolution (a crop region).
194  virtual bool isDataWindowCropOnly() const;
195 
196  /// does this format support saving whether the data outside the window
197  /// is streaked from the window edges?
198  virtual bool isDataWindowStreakSupported() const;
199 
200  /// does this format support deep rasters or multiple images?
201  /// If not, only one plane of the color models that this format supports
202  /// is allowed.
203  virtual bool isDeepRasterSupported() const;
204 
205  /// does this deep raster allow RGBA in one plane (true) or split into
206  /// 2 planes (RGB, A). (default false)
207  virtual IMG_DeepRasterColor getDeepRasterRGBASupport() const;
208 
209  /// Specifies whether this format stores its data interleaved (RGBRGBRGB)
210  /// or non-interleaved (RRRGGGBBB). If your format supports both, pick one.
211  virtual bool isDataInterleaved() const;
212 
213  /// if true, planes can have different data formats & components. Otherwise,
214  /// all planes must have the same data type and number of components.
215  virtual bool canPlaneTypesDiffer() const;
216 
217  /// Returns a list of options that can be set on the format when reading or
218  /// writing (like 'compression' or 'comment').
219  virtual const IMG_FileOptionList *getOptions() const;
220 
221  /// @private
222  // Allocate default tags and their values
223  void defaultTags(IMG_FileTagList &tags) const;
224 
225  /// Set an option globally for all formats. Use with extreme care.
226  static void setGlobalOption(const char *name, const char *value);
227  /// Read the value of a global option. May return a NULL string.
228  static void getGlobalOption(const char *name, UT_String &value);
229 
230  /// Allows you to change an option on a specific format. This will change
231  /// the option for all formats from this point on, whereas setGlobalOption
232  /// would not. Returns false if the format or the option couldn't be found.
233  static bool setFormatOptionDefault(const char *format_name,
234  const char *format_option,
235  const char *defvalue);
236  /// Returns the value of a format-specific option. Returns false if the
237  /// format or option does not exist.
238  static bool getFormatOptionDefault(const char *format_name,
239  const char *format_option,
240  UT_String &defvalue);
241 
242  /// Matches a filename against a single extension
243  static int matchExtension(const char *filename, const char *ext);
244 
245  /// Matches a filename against a list of extensions (the last entry must be
246  /// NULL)
247  static int matchExtensions(const char *filename, const char *ext[]);
248 
249  /// Between these two formats, which should be preferred? returns either
250  /// this or the format parameter. This method is used to resolve
251  /// conflicts between formats when files are being created.
252  virtual const IMG_Format *resolvePriority(const IMG_Format *format)
253  const;
254 
255  /// Some image formats have fixed color spaces, like JPEG (sRGB). The
256  /// default is PXL_CS_UNKNOWN. For formats that can have colorspaces per
257  /// plane, return PXL_CS_UNKNOWN and query the colorspace from IMG_Plane.
258  /// formatColorSpaceGamma() is ignored unless the color space is
259  /// PXL_CS_CUSTOM_GAMMA.
260  /// @{
261  virtual PXL_ColorSpace formatColorSpace() const;
262  virtual fpreal formatColorSpaceGamma() const;
263 
264  /// @}
265 
266  /// Return true if the image format can store the colorspace
267  virtual bool formatStoresColorSpace() const;
268 
269  /// Returns a gamma correction factor when converting from a given color
270  /// space to this image format's space. 'src_data_is_8bit' indicates whether
271  /// data is fixed 8b, in which case it will often be converted to 2.2 gamma.
272  /// If the dest_data_is_8bit is provided, it will use that flag for
273  /// the destination 8bit type instead of the src_data_is_8bit.
274  fpreal adjustGammaForFormat(PXL_ColorSpace src_color_space,
275  fpreal src_color_space_gamma,
276  bool src_data_is_8bit,
277  bool *dest_data_is_8bit = NULL) const;
278 
279  /// @private
280  static void installBasics();
281 
282 protected:
283  // Returns 1 if the stat's are ok for the format specified. For example,
284  // if there's a fixed resolution for a format, the format can nullify the
285  // validity of the format in the determination stage. By default, we
286  // simply check the image depth (i.e. number of images) and compare the max
287  // resolution.
288  virtual IMG_File *createFile() const = 0;
289  virtual int isFormatOk(const IMG_Stat &stat) const;
290  void removeFormatFromList();
291 
292  static const IMG_Format *findFormat(const char *filename,
293  const IMG_Stat *stat,
294  AccessType access);
295  static void findFormat(
297  const char *filename,
298  const IMG_Stat *stat,
299  AccessType access,
300  const UT_Array<const IMG_Format*> *image_formats = nullptr);
301 
302  const IMG_FileTagList *getGlobalTags();
303 
304 private:
305  static const IMG_Format *lookupFormatByName(const char *name,
306  const UT_Array<const IMG_Format *> *list);
307  static void loadGlobalOptions(const char *filename);
308  static bool emptyFormats();
309  static void adjustPriorities();
310  UT_StringHolder myLocation;
311 };
312 
313 #endif
314 
GT_API const UT_StringHolder filename
IMG_ImageType
Type of image we want to create or have opened.
#define SYS_VISIBILITY_EXPORT
IMG_DeepRasterColor
GLuint const GLchar * name
Definition: glcorearb.h:786
virtual const char * getFormatLocation() const
Describes how the format was loaded (i.e. DSO or internal formats)
Definition: IMG_Format.h:120
GLint GLenum GLint x
Definition: glcorearb.h:409
#define IMG_API
Definition: IMG_API.h:10
IMG_DataType
Definition: IMG_FileTypes.h:17
SYS_VISIBILITY_EXPORT void newIMGFormat(void *)
Definition: IMG_Sample.C:322
GLuint GLint GLboolean GLint GLenum access
Definition: glcorearb.h:2222
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
fpreal64 fpreal
Definition: SYS_Types.h:277
PXL_ColorSpace
Definition: PXL_Common.h:68
IMG_ColorModel
Definition: IMG_FileTypes.h:53
virtual bool isPassThrough() const
Definition: IMG_Format.h:112
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:40
Definition: core.h:1131
GLint y
Definition: glcorearb.h:103