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