HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
IMG_File.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_File.h ( IMG Library, C++)
7  *
8  * COMMENTS:
9  * Generic interface for loading and saving image files.
10  */
11 
12 #pragma once
13 
14 #ifndef __IMG_File__
15 #define __IMG_File__
16 
17 #include "IMG_API.h"
18 #include "IMG_Error.h"
19 #include "IMG_FileParms.h"
20 #include "IMG_FileTypes.h"
21 #include "IMG_Stat.h"
22 #include "IMG_Metadata.h"
23 
24 #include <PXL/PXL_Forward.h>
25 #include <UT/UT_BitArray.h>
26 #include <UT/UT_Functor.h>
27 #include <UT/UT_Matrix4.h>
28 #include <UT/UT_NonCopyable.h>
29 #include <UT/UT_Rect.h>
30 #include <UT/UT_SharedPtr.h>
31 #include <UT/UT_UniquePtr.h>
32 #include <UT/UT_ValArray.h>
33 #include <SYS/SYS_Deprecated.h>
34 #include <SYS/SYS_Types.h>
35 #include <iosfwd>
36 
37 class IMG_File;
38 class IMG_Metadata;
39 class IMG_Format;
40 class IMG_Plane;
42 class PXL_DeepSampleList;
43 class PXL_Raster;
44 class FS_Reader;
45 class FS_Writer;
46 template <typename T> class UT_Array;
47 class UT_IStream;
48 class UT_Options;
49 class UT_String;
50 class UT_StringHolder;
51 class UT_StringRef;
52 class UT_WorkBuffer;
53 
55 
58 
59 /// @brief Generic interface for reading and writing image files.
60 /// This class handles the reading and writing of all image formats that Houdini
61 /// supports. Use the static open() or create() methods to get an IMG_File
62 /// instance to read to or write from. Deleting this instance will close the
63 /// file.
64 class IMG_API IMG_File
65 {
66 public:
67  virtual ~IMG_File();
68  UT_NON_COPYABLE(IMG_File)
69 
70  virtual int64 getMemoryUsage(bool inclusive) const;
71 
72  // The following methods are a public interface which is not dependent on
73  // the format of the image. Users of the library should use these methods
74  // to do the loading and saving of the data.
75 
76  /// @brief Open an image file using a filename
77  /// Open an image file for reading by specifying the filename and path of
78  /// the file. An optional IMG_FileParms class may be passed to convert it
79  /// into a specific image type (8bit, specific resolution, etc). An optional
80  /// format may also be passed, which forces the library to assume the image
81  /// file is of that particular format.
82  /// This method returns a new IMG_File object which you read the image data
83  /// from, or NULL if an error occurred.
84  static IMG_FilePtr open(const char *filename,
85  const IMG_FileParms *options = nullptr,
86  const IMG_Format *fmt = nullptr);
87 
88  /// @brief Open an image file using a filename
89  /// Open an image file for reading by specifying the filename and path of
90  /// the file. A list of formats is also given, allowing the caller
91  /// customization of the types and order of formats.
92  /// An optional IMG_FileParms class may be passed to convert it
93  /// into a specific image type (8bit, specific resolution, etc).
94  /// This method returns a new IMG_File object which you read the image data
95  /// from, or NULL if an error occurred.
96  static IMG_FilePtr open(const char *filename,
97  const UT_Array<const IMG_Format*> &image_formats,
98  const IMG_FileParms *options = nullptr);
99 
100  /// @brief Open an image file from a stream
101  /// Open an image file for reading given a stream. This is useful for
102  /// embedded images in a file. An optional IMG_FileParms class may be
103  /// passed to convert it into a specific image type (8bit, specific
104  /// resolution, etc). An optional format may also be passed, which forces
105  /// the library to assume the image file is of that particular format.
106  /// If 'steal_stream' is true, the image library assumes ownership of the
107  /// stream and closes it when it's finished reading the file. If the stream
108  /// is not seekable (cannot jump around in the file, such as with a pipe),
109  /// set 'streamIsSeekable' to false.
110  /// This method returns a new IMG_File object which you read the image data
111  /// from, or NULL if an error occurred.
112  static IMG_FilePtr open(UT_IStream &is,
113  const IMG_FileParms *options = nullptr,
114  const IMG_Format *fmt=nullptr,
115  int steal_stream = 0,
116  bool streamIsSeekable = true);
117 
118  /// @brief Create a new image file
119  /// Create a new image file with the pathname 'filename' according to the
120  /// parameters specified in 'stat'. You can supply an optional 'options'
121  /// class to translate the image before being written (scale, flip, etc).
122  /// You can also specify an optional 'format' parameter to force the file
123  /// to be written as a specific image format (regardless of the extension
124  /// found in 'filename').
125  /// NULL may be returned if the file could not be created for any reason.
126  static IMG_FilePtr create(const char *filename,
127  const IMG_Stat &stat,
128  const IMG_FileParms *options = nullptr,
129  const IMG_Format *fmt = nullptr);
130 
131 
132  /// @brief Write an image file to an existing stream
133  /// Writes a new image file to the stream 'os' according to the
134  /// parameters specified in 'stat'. You can supply an optional 'options'
135  /// class to translate the image before being written (scale, flip, etc).
136  /// You can also specify an optional 'format' parameter to force the file
137  /// to be written as a specific image format (regardless of the extension
138  /// found in 'filename').
139  /// If 'steal_stream' is true, the image library assumes ownership of the
140  /// stream and closes it when it's finished writing the file. If the stream
141  /// is not seekable (cannot jump around in the file, such as with a pipe),
142  /// set 'streamIsSeekable' to false.
143  /// NULL may be returned if the file could not be created in the stream.
144  static IMG_FilePtr create(std::ostream &os,
145  const IMG_Stat &stat,
146  const IMG_FileParms *options = nullptr,
147  const IMG_Format *fmt = nullptr,
148  int steal_stream = 0,
149  bool streamIsSeekable = true);
150 
151  /// @{
152  /// @brief Writes a PXL_Raster to an image file.
153  /// Convenience method to write an image stored in a PXL_Raster to a disk
154  /// file.
155  static bool saveRasterAsFile(const char *filename,
156  const PXL_Raster *raster,
157  const IMG_SaveRastersToFilesParms &parms);
158  static bool saveRasterAsFile(const char *filename,
159  const PXL_Raster *raster,
160  const IMG_FileParms *fparms = nullptr,
161  const IMG_Format *format = nullptr);
162  /// @}
163 
164  /// @brief Writes PXL_Raster's to image files.
165  /// Convenience method to write images stored in PXL_Raster's to disk
166  /// files. The @c linear_planes parameter specifies a pattern of planes
167  /// which should be written to in linear space.
168  static bool saveRastersAsFiles(const char *filename,
169  const IMG_SaveRastersToFilesParms &parms);
170 
171  /// @brief Copies an existing image file to another image file.
172  /// Convenience method to copy an image file from one file to another.
173  /// The image date may be altered if the formats of the two files are
174  /// not the same (based on filename extension), or if an optional 'options'
175  /// class is passed.
176  static bool copyToFile(const char *sourcename,
177  const char *destname,
178  const IMG_FileParms *options = nullptr);
179 
180  static bool copyToFileFormat(const char *sourcename,
181  const char *formatname,
182  UT_String *destname = nullptr,
183  const IMG_FileParms *options = nullptr);
184 
185  /// @brief Copies an existing image file to a stream
186  /// Convenience method to copy an image file to a stream. The image data
187  /// may be altered if an optional 'options' class is passed, or if the
188  /// optional image 'format' parameter does not match the format of the
189  /// source image file.
190  static bool copyToStream(const char *sourcename,
191  std::ostream &deststream,
192  const IMG_FileParms *options = nullptr,
193  const IMG_Format *format = nullptr);
194 
195  /// Check whether image integrity by reading all scanlines of image
196  static bool checkIntegrity(const char *filename, UT_StringHolder &error);
197 
198  /// Check whether image integrity by reading all scanlines of image.
199  /// @note You cannot have read from the IMG_File, nor will you be able to
200  /// read from the IMG_File after calling this method.
201  ///
202  /// To work properly, there shoud be no filtering on the IMG_File, so it
203  /// should be opened using: @code
204  /// IMG_FileParms parms;
205  /// parms.readAsIs();
206  /// parms.orientImage(IMG_ORIENT_X_NONE, IMG_ORIENT_Y_NONE);
207  /// IMG_FilePtr fp = IMG_File::open(filename, &parms);
208  /// @endcode;
209  static bool checkIntegrity(IMG_File *fp, UT_StringHolder &error);
210 
211  virtual const char *className() const { return "IMG_File"; }
212 
213  /// Closes the file. Called by the destructor if needed , so 'delete file'
214  /// will often take the place of this call. However, you won't receive any
215  /// error information in that case, so you can call it directly.
216  int close();
217 
218  /// Returns 1 if we are reading, 0 if writing.
219  int getReadMode() const;
220 
221  /// @{
222  /// Returns the image type of the format we just opened.
223  IMG_ImageType getImageType() const;
224  /// @}
225 
226  /// @{
227  /// Retrieve the file format description of the file. The format contains
228  /// all information that is general to all files of this format type.
229  const IMG_Format *getFormat() const { return myFormat; }
230  void setFormat(const IMG_Format *f) { myFormat = f; }
231  /// @}
232 
233  /// Get the image description of the current image file (resolution, data
234  /// format, etc). The returned class can be queried for all of the current
235  /// image file's statistics.
236  /// @{
237  const IMG_Stat &getStat() const;
238  IMG_Stat &getStat();
239 
240  const IMG_Stat &unfilteredStat() const
241  { return getUnfilteredFile()->myStat; }
242  /// @}
243 
244  /// Get additional image information about the file that is specific
245  /// to a particular format. Some formats do not have additional information.
246  /// The information returned is human-readable in 'text'.
247  virtual void getAdditionalInfo(UT_String &text);
248 
249  /// Returns the option passed through IMG_FileParms. This searches for
250  /// format specific options (i.e. OpenEXR::compression). It's possible to
251  /// override the format name by passing the @c format_override argument.
252  UT_StringHolder getFileOption(const UT_StringRef &name) const;
253 
254  /// Access to the list of file options this file was saved with.
255  /// @{
256  int SYS_DEPRECATED(20.0) getNumOptions() const;
257  UT_StringHolder SYS_DEPRECATED(20.0) getOptionName(int i) const;
258  UT_StringHolder SYS_DEPRECATED(20.0) getOptionValue(int i) const;
259  /// @}
260 
261  /// When reading or writing a file, the metadata will contain all the
262  /// metadata options defined by the file (and values that the user has
263  /// passed through the IMG_FileParms).
264  ///
265  /// When reading a file, the driver will also populate the metadata from
266  /// any data stored in the file.
267  const IMG_Metadata &metadata() const { return unfilteredStat().metadata(); }
268 
269  /// @{
270  /// Iterate over the file's metdata
271  IMG_Metadata::const_iterator beginMetadata() const
272  { return metadata().begin(); }
273  IMG_Metadata::const_iterator endMetadata() const
274  { return metadata().end(); }
275  /// @}
276 
277  /// Search for specific metadata
278  bool findMetadata(const UT_StringRef &name,
279  IMG_MetadataItem &value) const
280  {
281  return unfilteredStat().findMetadata(name, value);
282  }
283 
284  /// @{
285  /// Import metadata
286  bool importMetadata(const UT_StringRef &name, bool &value) const
287  { return unfilteredStat().importMetadata(name, value); }
288  bool importMetadata(const UT_StringRef &name, UT_StringHolder &value) const
289  { return unfilteredStat().importMetadata(name, value); }
290  bool importMetadata(const UT_StringRef &name, int32 &value) const
291  { return unfilteredStat().importMetadata(name, value); }
292  bool importMetadata(const UT_StringRef &name, int64 &value) const
293  { return unfilteredStat().importMetadata(name, value); }
294  bool importMetadata(const UT_StringRef &name, fpreal32 &value) const
295  { return unfilteredStat().importMetadata(name, value); }
296  bool importMetadata(const UT_StringRef &name, fpreal64 &value) const
297  { return unfilteredStat().importMetadata(name, value); }
298  bool importMetadata(const UT_StringRef &name, UT_Matrix4F &m) const
299  { return unfilteredStat().importMetadata(name, m); }
300  bool importMetadata(const UT_StringRef &name, UT_Matrix4D &m) const
301  { return unfilteredStat().importMetadata(name, m); }
302  /// @}
303 
304  /// Convert metadata to a string value. When @c pretty_print is @c true:
305  /// - If there's a menu, the corresponding label will be returned
306  /// - If there's type information, it will be used (i.e. printing a time or
307  /// memory)
308  bool metadataAsString(const UT_StringRef &name,
309  UT_StringHolder &value,
310  bool pretty_print = true) const
311  {
312  return unfilteredStat().metadataAsString(name, value, pretty_print);
313  }
314 
315  /// @brief read a single scanline.
316  /// read() returns a pointer to the scanline data
317  /// in an internal buffer. Do not delete it.
318  const void *read(int scan, const IMG_Plane *from_plane = nullptr);
319 
320  /// @brief Reads the scanline into a buffer that you supply.
321  /// The buffer passed must be big enough to fit the plane passed.
322  /// getStat().bytesPerPlaneScan() will return the proper size.
323  /// Returns 0 on failure.
324  bool readIntoBuffer(int scan, void *buffer,
325  const IMG_Plane *from_plane = nullptr);
326 
327  /// @brief Write a scanline to the file.
328  /// You don't need to write scanlines in order, nor do you need to write
329  /// planes in order; the data may be cached however. Returns 0 if
330  /// there was an error during the write. You should immediately stop
331  /// writing if a failure occurred (many formats will behave unpredictably
332  /// otherwise).
333  bool write(int scan, const void *data,
334  const IMG_Plane *to_plane = nullptr);
335 
336  /// allocates a buffer large enough to hold the biggest plane's scanline
337  /// in the file. Free this buffer with free(). (This will not hold all
338  /// the planes' scanlines, only one at a time!)
339  void * allocScanlineBuffer() const;
340 
341  /// The size in bytes of the buffer allocated for a scanline.
342  exint getScanlineBufferSizeB() const;
343 
344  /// @deprecated
345  /// The following methods read/write a whole raster. Unless the scanline
346  /// increment is passed in, the stat structure will be used to determine the
347  /// scanline size. Beware if you're using translators...
348  /// Use readImages() and writeImages() instead.
349  ///@{
350  bool readImage(void *data, int flip=0, int scaninc=0);
351  /// @deprecated
352  bool writeImage(void *data, int flip=0, int scaninc=0);
353  ///@}
354 
355  // Convenience method to write a single raster to a file.
356  static bool writeImage(const UT_StringRef &filepath,
357  const PXL_Raster &image,
358  const IMG_FileParms *options = nullptr,
359  const IMG_Format *fmt = nullptr);
360 
361  /// @brief Reads all the image data into a list of PXL_Rasters.
362  /// reads the image data into a a series of rasters. The array should be
363  /// empty, as this method creates and fills the rasters for you.
364  bool readImages(UT_Array<UT_UniquePtr<PXL_Raster>> &images,
365  const char *scope = nullptr);
366 
367  /// @{
368  /// @brief Writes all PXL_Rasters to the image format.
369  /// This method takes a raster per IMG_Plane in the stat. The
370  /// data format, color model and res of the raster must match the
371  /// corresponding IMG_Plane. If the format is not a deep raster format,
372  /// not all images may be written.
373  /// if 'freerasters' is true, it will free the rasters for you.
374  bool writeImages(const UT_Array<const PXL_Raster *> &imgs);
375  bool writeImages(UT_Array<UT_UniquePtr<PXL_Raster>> &images,
376  bool freerasters = false);
377  /// @}
378 
379  /// @deprecated
380  /// For image files that contain more than one image, such as a
381  /// movie file, jump to a particular frame in the movie and reset
382  /// for reading the scanlines of the new frame
383  virtual bool jumpToFrame(int frame);
384 
385  /// When writing an image, call if interrupted or you encounter an
386  /// non-image-file error and cannot complete the file write.
387  virtual void abortWrite();
388 
389  ///@{
390  /// orientation of the current file or format. Some formats support multiple
391  /// orientations specified in the image files themselves, others simply
392  /// have a fixed orientation. Call these methods rather than querying the
393  /// orientation from the format, in case the format supports multiple
394  /// orientations.
395  virtual int isTopFirst() const;
396  /// If 0, scanlines are right-to-left. Default is 1 (left-to-right).
397  virtual int isLeftFirst() const;
398  ///@}
399 
400  /// call this if you won't be reading the scanlines in order, or if
401  /// you'll be reading all the scanlines for a single plane first.
402  virtual void randomReadAccessRequired();
403 
404  /// @{
405  /// @private
406  bool randomReadsForced() const { return myForceRandomReads; }
407  /// @}
408 
409  /// @{
410  /// This is a tile interface for reading files. To use it, you must pass an
411  /// IMG_FileParms object to open() with IMG_FileParms::useTileInterface()
412  /// called. Otherwise, this will just return false. The x-y coords of the
413  ///tile is in pixels.
414  virtual bool readTile(const UT_InclusiveRect &tile, void *data,
415  const IMG_Plane *plane=0);
416 
417  /// this is a tile interface for writing files. To use it, you must pass an
418  /// IMG_FileParms object to open() with IMG_FileParms::useTileInterface()
419  /// called. Otherwise, this will just return false. The x-y coords of the
420  ///tile is in pixels.
421  virtual bool writeTile(const UT_InclusiveRect &tile,
422  const void *data,
423  const IMG_Plane *plane=0);
424  /// @}
425 
426  /// When writing an image, the checkpoint() method can be used to
427  /// checkpoint data (see TIFFCheckpointDirectory() for an example).
428  /// Generally, this writes the image data currently passed and this results
429  /// in a usable, partially written file.
430  /// By default, nothing is done.
431  virtual void checkpoint();
432 
433  /// This method converts the "standard" bit depth option to an IMG_DataType.
434  /// This is used by the -b option in mantra as well as many other places.
435  /// When dealing with floating point arguments, there's an optional flag to
436  /// "denormalize" the floating point values when writing. This basically
437  /// removes tiny precision errors. It's up to the user to deal with the
438  /// denormalization.
439  /// - char, byte, 8 = uint8
440  /// - short, 16 = uint16
441  /// - int = uint32
442  /// - FLOAT = fpreal32 (denormalize=true)
443  /// - HALF = fpreal16 (denormalize=true)
444  /// - float, 32 = fpreal32
445  /// - half = fpreal16
446  static IMG_DataType mapStorageOption(const char *option,
447  bool *denormalize_flag = nullptr);
448 
449  /// Turns error reporting on or off. Returns the previous setting.
450  /// Errors are reported to the error manager, which will either show up
451  /// in the node information or the Houdini status bar (if not loaded within
452  /// a node).
453  ///
454  static int doErrors(int newDoErrors);
455  static void imgError(IMG_ErrorCodes code,
456  const char *msg = nullptr);
457  static void imgWarning(IMG_ErrorCodes code,
458  const char *msg = nullptr);
459 
460  bool hasError() const
461  { return getBaseFile() ? (getBaseFile()->hasError() ||
462  myErrorFlag) :myErrorFlag; }
463 
464  /// Returns information about the alpha channel if the IMG_FileParms passed
465  /// to open() had detectAlphaDetails() specified.
466  virtual IMG_FileAlphaInfo getAlphaInfo(float &) const
467  { return IMG_ALPHA_VARYING; }
468 
469  /// returns the raw file at the top of the filter stack.
470  IMG_File *getUnfilteredFile();
471  const IMG_File *getUnfilteredFile() const;
472  virtual IMG_File *getBaseFile() const { return 0; }
473 
474  /// Copy the texture image options from another IMG_File
475  bool copyImageTextureOptions(const IMG_File &src,
476  bool clear_existing);
477 
478  /// Some image formats support "texture" options. Formats which do not
479  /// support options should return a NULL pointer.
480  /// This method calls @c getImageTextureOptions() by default
481  virtual UT_SharedPtr<UT_Options> imageTextureOptions() const;
482 
483  /// This method is deprecated. Please implement @c imageTextureOptions()
484  SYS_DEPRECATED(12.0) virtual const UT_Options *getImageTextureOptions() const;
485 
486  /// For image formats which support texture options, this will clear out
487  /// all texture options.
488  virtual void clearImageTextureOptions();
489 
490  /// For image formats which support texture options, merge the UT_Options
491  /// into the current options.
492  virtual bool setImageTextureOptions(const UT_Options &options);
493 
494  /// When being created through a tile device (i.e. rendering, etc.), the
495  /// writer may send additional information to the file writer after the
496  /// image has been created.
497  virtual void setWriteTag(const char *tagname,
498  int num_values,
499  const char *const *values);
500 
501  /// Read the image options (@see getOption()) to extract the world to
502  /// camera transform. If the data isn't available, this method returns
503  /// false. This will likely only work when the image is being created from
504  /// mantra.
505  bool getWorldToCamera(UT_Matrix4D &xform) const;
506 
507  /// Read the image options (@see getOption()) to extract the camera to NDC
508  /// transform. If the data isn't available in the options, this method
509  /// returns false. This will likely only work when the image is being
510  /// created from mantra.
511  /// If the @c fit_z option is true, the near/far range will be set to
512  /// (0,1). This will not be possible if the "camera:clip" setting wasn't
513  /// passed in the options.
514  bool getCameraToNDC(UT_Matrix4D &xform, int xres, int yres, bool
515  fit_z = true) const;
516  /// Read the image options (@see getOption()) to extract the world to NDC
517  /// transform. If the data isn't available in the options, this method
518  /// returns false. This will likely only work when the image is being
519  /// created from mantra.
520  /// If the @c fit_z option is true, the near/far range will be set to
521  /// (0,1). This will not be possible if the "camera:clip" setting wasn't
522  /// passed in the options.
523  bool getWorldToNDC(UT_Matrix4D &xform, int xres, int yres, bool
524  fit_z = true) const;
525 
526 
527  // API for raw deep pixel access. Methods will fail if the image is not
528  // a deep pixel image. The deep pixel functions can be accessed from
529  // multiple threads simultaneously.
530 
531  // Returns the number of deep pixel samples for the given pixel location.
532  // Returns -1 if the sample count cannot be read, or if the image is not
533  // a deep pixel image.
534  virtual int getDeepPixelSamples(int x, int y);
535 
536  // Read the deep pixel samples for the given plane. The size of the data
537  // array should be at least the same size as the number of samples returned
538  // by getDeepPixelSamples multiplied by the component count of the plane
539  // given by IMG_Plane::getComponentCount.
540  // Returns false if the data cannot be read, or if the image is not a deep
541  // pixel image.
542  virtual bool getDeepPixelPlaneData(int x, int y,
543  const IMG_Plane &plane,
544  float *data);
545 
546  // Read the deep pixel samples for all components at a given pixel location.
547  // The length of the pointer array should at least be the same as the
548  // number of samples returned from getDeepPixelSamples(). The size of
549  // each array pointed to should be at least the same size as the number
550  // of components returned from getDeepPixelComponentCount().
551  // Returns false if the data cannot be read, of if the image is not a deep
552  // pixel image.
553  virtual bool getDeepPixelData(int x, int y, float * const *data);
554 
555  /// Read a deep pixel
556  virtual bool readDeepPixelData(int x, int y,
557  PXL_DeepSampleList &pixel);
558 
559  /// @{
560  /// A method to write deep pixel data for all channels, at a given pixel
561  /// location. The function should be given an array of pointers to float
562  /// arrays, where each float array contains the value of all image
563  /// components for a given sample level.
564  ///
565  /// Returns false if the data cannot be written, or if the image is not
566  /// a deep pixel image.
567  virtual bool writeDeepPixelData(int x, int y,
568  const PXL_DeepSampleListPtr &pixel);
569  /// @}
570 
571 
572  /// users of IMG_File can select only certain planes to read using
573  /// IMG_FileParms::selectPlane..(). Call selectPlanesToRead() first,
574  /// usually at the end of open(), and then call isPlaneSelected() to
575  /// determine if the plane was selected for read.
576  /// @{
577  void selectPlanesToRead();
578  bool isPlaneSelected(const IMG_Plane &plane) const;
579  /// @}
580 
581  static void setFileCreateCB(
583  static void setFileHooks(IMG_FileOpenHook openhook,
584  IMG_FileCloseHook closehook);
585  static IMG_FileOpenHook &getOpenHook();
586  static IMG_FileCloseHook &getCloseHook();
587 
588 protected:
589  IMG_File(); /// Only called by format class
590 
591  // If the check_magic flag is 0, then the first 4 bytes of the file have
592  // alread. They are passed in as the magic number for verification.
593  virtual int open();
594  virtual int openPostMagic();
595  virtual int openFile(const char *filename);
596 
597  virtual int readScanline(int scanline, void *data) = 0;
598  virtual const void *readPlaneScanline(int y, const IMG_Plane &pi);
599 
600  // Create an image
601  virtual int createFile(const char *filename,const IMG_Stat &stat);
602  virtual int create(const IMG_Stat &stat);
603 
604  virtual int writeScanline(int scanline, const void *data) = 0;
605  virtual int writePlaneScanline(const void *data, int y,
606  const IMG_Plane &pi);
607 
608  virtual int closeFile() = 0;
609 
610  /// Run after the output stream has been closed.
611  /// Be careful, since some things have been destructed.
612  virtual void postCloseAction();
613 
614  // add any image flips, scales, data translations, etc. Returns the
615  // end of the filter chain.
616  //
617  virtual bool isPassThrough() const { return false; }
618 
619  // if you override this, you must call this class's version.
620  virtual void computeCommonData();
621 
622  void *getScanlineBuffer(int y);
623  void *getPlaneBuffer(int y, const IMG_Plane &pi);
624 
625  virtual void finishedScanline(int scan);
626 
627  static void setOptions(const IMG_FileParms *options,
628  IMG_File *file);
629 
630  /// @{
631  /// Set option to control behaviour of the file. For example, the
632  /// compression level when creating the image.
633  bool setOption(const UT_StringHolder &token, const char *value);
634  bool setOption(const UT_StringHolder &token, fpreal64 val);
635  bool setOption(const UT_StringHolder &token, int64 val);
636  bool setOption(const UT_StringHolder &option, int value)
637  { return setOption(option, (int64)value); }
638 
639  bool addMetadata(const UT_StringHolder &key,
640  const IMG_MetadataItem &item);
641  bool addMetadata(const UT_StringHolder &key,
642  const UT_JSONValue &value,
643  IMG_Metadata::Storage store =
645  IMG_Metadata::TypeInfo type_info =
647  /// @}
648 
649  bool canWriteStatWithoutConversion() const;
650 
651  // Access to input and output streams
652  // peekByte() will peek at the next input byte. -1 returned on EOF
653  // readSomeBytes() will read data into the buffer specified. The number
654  // of bytes actually read is returned.
655  // writeSomeBytes() will write data from the buffer. The number
656  // of bytes actually written is returned.
657  // flushBytes() will flush the output stream
658  // readBytes() is a convenience method when all data needs to be read
659  // writeBytes() is a convenience method when all data needs to be written
660  //
661  int peekByte();
662  int readSomeBytes(void *buffer, int size);
663  int writeSomeBytes(const void *buffer, int size);
664  bool flushBytes();
665 
666  bool readBytes(void *buffer, int size)
667  { return readSomeBytes(buffer, size) == size; }
668  bool writeBytes(const void *buffer, int size)
669  { return writeSomeBytes(buffer, size) == size; }
670 
671 
672  // For the odd format which requires data to be read as ASCII lines, this
673  // method exists.
674  bool readAsciiLine(UT_WorkBuffer &wbuf);
675 
676  // Seeks the stream to the start + offset. Returns true if successful
677  // and false otherwise.
678  bool seekFromBeginning(int64 offset);
679  bool seekFromCurrent(int64 offset);
680  bool seekFromEnd(int64 offset);
681  int64 tellCurrentPosition();
682 
683  // Copies our input stream to the given stream.
684  void copyInputToStream(std::ostream &os);
685 
686  // Deletes our input stream.
687  void deleteStream();
688 
689  /////////////////////////////////////////////////////////////////////////
690  // Do not use these methods. They are for special cases only.
691  UT_IStream *getUTIStream() { return myIStream; }
692  void setIStream(UT_IStream *is) { myIStream = is; }
693  /////////////////////////////////////////////////////////////////////////
694 
695  // Image description.
696  IMG_Stat myStat;
697  bool myReadMode;
698  std::ostream *myOS;
699  int64 myStreamStartPos;
700  int64 myStreamLength;
701  unsigned myCreateIStream:1,
702  myCreateOStream:1,
703  myForceRandomReads:1,
704  myHasRandomReads:1,
705  myFileOpen:1,
706  myErrorFlag:1,
707  myContinueOnErrorFlag:1,
708  myIStreamFromHook:1,
709  myExplicitFormat:1;
710 
711 private:
712  class img_ScanProgress
713  {
714  public:
715  img_ScanProgress()
716  : myNumPlanes(0)
717  {
718  }
719  void init(const IMG_Stat &stat);
720  int64 getMemoryUsage(bool inclusive) const;
721  void processed(int scan, const IMG_Plane *plane);
722  void processAll(int scan);
723  bool isComplete(int scan, const IMG_Plane *plane) const;
724  bool isComplete(int scan) const;
725  int remaining(int scan) const;
726  int numScans() const { return myCounts.entries(); }
727  private:
728  int bitIndex(int scan, int plane) const;
729  private:
730  int myNumPlanes;
731  UT_BitArray myProcessed;
732  UT_ValArray<int> myCounts;
733  };
734 
735  // Initialize tags to default values
736  void initializeTags();
737  void makeScanlineBuffers();
738  void deallocScanlineBuffer(int scan);
739  const void *returnErrorScan(int scan, const IMG_Plane &pi);
740  const char *metadataKey() const;
741 
742  static IMG_FilePtr makeReadFilters(IMG_FilePtr src, const IMG_FileParms &parms);
743  static IMG_FilePtr makeWriteFilters(IMG_FilePtr src, const IMG_FileParms &parms);
744  IMG_File *makeDataConversion(const IMG_FileParms &parms,
745  IMG_File *file);
746  IMG_File *makeFlip(const IMG_FileParms &parms,
747  IMG_File *file);
748 
749  static IMG_FilePtr open(const char *filename,
750  const IMG_FileParms *options,
751  const IMG_Format *fmt,
752  const UT_Array<const IMG_Format*> *image_formats);
753 
754  const IMG_Format *myFormat;
755  void *myScanlineBuffer;
756  int myCurrentImageScanline;
757 
758  img_ScanProgress myScanProgress;
759  UT_ValArray<void *> myImageScanline;
760  UT_BitArray mySelectPlane;
761 
762  UT_UniquePtr<FS_Reader> myReader;
763  UT_UniquePtr<FS_Writer> myWriter;
764  UT_IStream *myIStream;
765 
766  // only IMG_Format can call initializeTags().
767  friend class IMG_Format;
768  friend class IMG_FileFilter;
769  friend class IMG_GZip;
770  friend class IMG_FileBuffer;
771  friend class IMG_MemoryFileBuffer;
772  friend class MV_ReadPRISMS;
773 };
774 
775 /// Auto-scope class mainly to disable file errors temporarily
776 class IMG_API IMG_AutoFileError
777 {
778 public:
779  IMG_AutoFileError(bool report_errors = false)
780  { myReport = IMG_File::doErrors(report_errors?1:0); }
781  ~IMG_AutoFileError()
782  { IMG_File::doErrors(myReport); }
783  UT_NON_COPYABLE(IMG_AutoFileError);
784 private:
785  int myReport = 1;
786 };
787 
788 #endif
789 
Class for reading files.
Definition: FS_Reader.h:33
GT_API const UT_StringHolder filename
IMG_ErrorCodes
Definition: IMG_Error.h:16
int int32
Definition: SYS_Types.h:39
#define SYS_DEPRECATED(__V__)
IMG_ImageType
Type of image we want to create or have opened.
UT_Functor1< void, UT_IStream * > IMG_FileCloseHook
Definition: IMG_File.h:57
int64 exint
Definition: SYS_Types.h:125
GLenum GLenum GLsizei void * image
Definition: glad.h:5132
GLint y
Definition: glcorearb.h:103
void close() override
Describes the format and layout of a single plane in an image The plane specifies the format and name...
Definition: IMG_Plane.h:48
float fpreal32
Definition: SYS_Types.h:200
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:39
< returns > If no error
Definition: snippets.dox:2
double fpreal64
Definition: SYS_Types.h:201
#define IMG_API
Definition: IMG_API.h:10
UT_StringMap< IMG_MetadataItem >::const_iterator const_iterator
Definition: IMG_Metadata.h:325
GLfloat f
Definition: glcorearb.h:1926
GLintptr offset
Definition: glcorearb.h:665
Definition: core.h:760
int open(float queuesize) override
const_iterator begin() const
Definition: IMG_Metadata.h:326
std::shared_ptr< T > UT_SharedPtr
Wrapper around std::shared_ptr.
Definition: UT_SharedPtr.h:36
IMG_DataType
Definition: IMG_FileTypes.h:17
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
#define UT_NON_COPYABLE(CLASS)
Define deleted copy constructor and assignment operator inside a class.
Class for writing files.
Definition: FS_Writer.h:32
HUSD_API const char * raster()
long long int64
Definition: SYS_Types.h:116
GLuint const GLchar * name
Definition: glcorearb.h:786
GLint GLenum GLint x
Definition: glcorearb.h:409
UT_Functor1< UT_IStream *, const UT_StringRef & > IMG_FileOpenHook
Definition: IMG_File.h:56
ImageBuf OIIO_API flip(const ImageBuf &src, ROI roi={}, int nthreads=0)
IMG_FileAlphaInfo
GLsizeiptr size
Definition: glcorearb.h:664
A map of string to various well defined value types.
Definition: UT_Options.h:84
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1602
Base Integer Rectangle class.
__hostdev__ constexpr T pi()
Pi constant taken from Boost to match old behaviour.
Definition: NanoVDB.h:976
File options for manipulating image data on load or save. This class allows you to modify the incomin...
Definition: IMG_FileParms.h:38
GLuint GLfloat * val
Definition: glcorearb.h:1608
Class to store JSON objects as C++ objects.
Definition: UT_JSONValue.h:99
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:38
Parameters for the saveRaster[s]AsFile[s]() methods of IMG_File.
Map of metadata items.
Definition: IMG_Metadata.h:208
Definition: core.h:1131
UT_UniquePtr< IMG_File > IMG_FilePtr
Definition: IMG_File.h:54
Definition: format.h:895
GLenum src
Definition: glcorearb.h:1793