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