HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
IMG_FileParms.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_FileParm.h ( IMG Library, C++)
7  *
8  * COMMENTS:
9  * Parameter class for options to IMG_File::open() and IMG_File::create()
10  */
11 #ifndef __IMG_FILE_PARMS_H__
12 #define __IMG_FILE_PARMS_H__
13 
14 #include "IMG_API.h"
15 
16 #include <SYS/SYS_Types.h>
17 #include <UT/UT_FilterType.h>
18 #include <UT/UT_StringArray.h>
19 #include <UT/UT_IntArray.h>
20 #include <UT/UT_Rect.h>
21 #include <UT/UT_SharedPtr.h>
22 #include <PXL/PXL_LumFuncs.h>
23 
24 #include "IMG_FileTypes.h"
25 #include "IMG_Metadata.h"
26 
27 class UT_Options;
28 class UT_OptionEntry;
29 class UT_JSONWriter;
30 class IMG_TileOptions;
31 class IMG_Stat;
32 class IMG_Format;
33 class img_MipCache;
34 
35 /// @brief File options for manipulating image data on load or save.
36 /// This class allows you to modify the incoming or outgoing image data by
37 /// scaling, flipping, converting or cropping the data. It can be optionally
38 /// passed to IMG_File::open() or IMG_File::create()
40 {
41 public:
42  IMG_FileParms();
43 
44  /// This method turns off any option that would result in image
45  /// translation.
46  void readAsIs();
47 
48  // DATA ORGANIZATION ----------------------------------------------------
49 
50  /// @brief Convert to a different data type
51  /// convert the image to this data type, if needed (default = use native)
52  void setDataType(IMG_DataType dt);
53 
54  /// @brief Convert to a different number of pixel components
55  /// convert to a standard color model, if needed (RGB, RGBA, single).
56  /// When moving from fewer components to more components, the
57  /// data is either duplicated (1chan->RGB) or generated (RGB-RGBA, A=1).
58  void setColorModel(IMG_ColorModel cm);
59 
60  /// @brief Convert to either an RGBA or ABGR ordering
61  /// converts the component ordering to RGBA or ABGR (or RGB/BGR, RG/GR)
62  /// without forcing the color model to a specific number of components.
63  void setComponentOrder(IMG_ComponentOrder order);
64 
65 
66  /// @brief Interleaves or deinterleaves pixel data
67  /// Determines how to format the data.
68  /// - IMG_INTERLEAVE_AS_IS - leave it interleaved or non, as in the file.
69  /// - IMG_INTERLEAVED - always interleave (rgbrgbrgb). Default.
70  /// - IMG_NON_INTERLEAVED - always non-interleaved (rrrgggbbb)
71  void setInterleaved(IMG_Interleave i);
72 
73  /// is RGB or higher, this method determines how to convert the vector
74  /// into a scalar. By default, the luminance is taken.
75  void setLuminanceFunc(PXL_LumFunction f);
76 
77  /// If true, alpha will be read into its own plane, instead of an RGBA
78  /// color plane. Color will be read as its own plane as well, RGB.
79  void readAlphaAsPlane();
80 
81  /// If demoting from a deep raster to an RGB(A) image, these methods
82  /// allow you to specify the plane(s) to copy to RGB(A), by name or index.
83  /// Selects a plane by index. Indices are specified from 1 to # planes.
84  void selectPlanes(const UT_IntArray &planeindices);
85 
86  /// If demoting from a deep raster to an RGB(A) image, these methods
87  /// allow you to specify the plane(s) to copy to RGB(A), by name or index.
88  /// Selects several planes by numeric pattern, ie. "1", "1 3 4", "[1-3] 5"
89  void selectPlanes(const char *pattern);
90 
91  /// If demoting from a deep raster to an RGB(A) image, these methods
92  /// allow you to specify the plane(s) to copy to RGB(A), by name or index.
93  /// Selects serveral planes by name pattern, such as "C", "C A Pz" "P? C*"
94  void selectPlaneNames(const char *name);
95 
96  /// Isolate mip level to load (0 being base resolution). IMG_File::open()
97  /// may return nullptr if invalid mip level is specified. If the file
98  /// doesn't have pre-generated mipmaps, IMG_File::open() will generate
99  /// mipmap level on the fly. This object holds the cache for intermediate
100  /// mip levels if they're being generated, so if you're opening the same
101  /// file multiple times with different mip level selected, it's recommended
102  /// that you reuse this parm object (as long as it's within the same
103  /// thread).
104  void selectMipLevel(int level);
105 
106  /// optimizes mipmap generation by caching level0
107  void setEnableMipLevel0Cache(bool val);
108 
109  /// mipmap rounding mode (ie how next resolution down is calculated)
110  void setMipRoundMode(IMG_MipRoundMode mode);
111 
112  /// @{
113  /// Accessors
114  IMG_DataType dataType() const { return myDataType; }
115  IMG_ColorModel colorModel() const { return myColorModel; }
116  IMG_ComponentOrder componentOrder() const { return myComponentOrder; }
117  IMG_Interleave interleaved() const { return myInterleaved; }
119  { return mySelectPlaneName; }
121  { return mySelectPlaneIndex; }
122  bool alphaSplit() const { return myAlphaSplit; }
123  bool alphaDetect() const { return myAlphaDetect; }
124  PXL_LumFunction lumFunc() const { return myLumFunc; }
125  IMG_XOrientation orientX() const { return myOrientX; }
126  IMG_YOrientation orientY() const { return myOrientY; }
127  bool flipVertical() const { return myFlipVertical; }
128  bool flipHorizontal() const { return myFlipHorizontal; }
129  bool flopImage() const { return myFlopImage; }
130  bool useTiles() const { return myUseTiles; }
131  exint xres() const {return myResX; }
132  exint yres() const {return myResY; }
133  fpreal xscale() const { return myScaleX; }
134  fpreal yscale() const { return myScaleY; }
135  bool preserveAspect() const { return myPreserveAspect; }
136  bool resLimit() const { return myResLimit; }
137  exint maxXres() const {return myMaxX; }
138  exint maxYres() const {return myMaxY; }
139  bool powerTwoRes() const { return myPowerTwoRes; }
140  UT_FilterType filterType() const { return myFilterType; }
141 
142  bool enableMipLevel0Cache() const
143  { return myEnableMipLevel0Cache; }
144  bool readDataWindowOnly() const
145  { return myReadDataWindowOnly; }
146  bool isReadArea() const
147  { return myReadAreaFlag; }
148  const UT_DimRect getReadArea() const { return myReadArea; }
149  bool isReadUVArea() const
150  { return myReadUVAreaFlag; }
151  const fpreal *getReadUVArea() const { return myReadUVArea; }
152  /// @}
153 
154  /// If the color model is set to IMG_1CHAN, and the actual color model
155 
156  /// RESOLUTION -----------------------------------------------------------
157  /// using these methods always scales. To crop, use the data window methods
158  /// Note that the filter is shared, so if more than one of these is called,
159  /// the last filter setting is used.
160 
161  /// Scale the image to resolution (x,y). (0 = use original dimension)
162  void scaleImageTo(int x, int y, UT_FilterType ft=UT_FILTER_BOX);
163 
164  /// scale the image by scaling factors (x,y).
165  void scaleImageBy(fpreal x, fpreal y, UT_FilterType ft=UT_FILTER_BOX);
166 
167  /// limit the image to a maximum resolution. Scale to this res, preserving
168  /// the aspect ratio if requested.
169  void limitImageRes(int x, int y, UT_FilterType ft=UT_FILTER_BOX,
170  bool preserve_aspect = true);
171 
172  /// images must be read as powers of two. Does not preserve aspect ratio.
173  void powerTwoOnly();
174 
175  // DATA WINDOW ---------------------------------------------------------
176 
177  /// Normally, a data window is expanded or cropped to the image resolution.
178  /// calling this will always read only the data window.
179  /// Used only for reading.
180  void setDataWindowOnly();
181 
182  /// read the image region in 'area' only (even if we need to crop or expand
183  /// the image to fill it). Used only for reading.
184  void setWindow(const UT_DimRect &area);
185 
186  /// read the image region in 'area' in UV coords. Used only for reading.
187  void setWindow(float u1, float v1, float u2, float v2);
188 
189  // ORIENTATION ----------------------------------------------------------
190 
191  /// options for orienting and flipping the image. Default orientation is
192  /// LEFT_FIRST, BOTTOM_FIRST. You can set each to 'none' if you don't care.
193  void orientImage(IMG_XOrientation x, IMG_YOrientation y);
194 
195  /// @brief Flip the image in either direction.
196  /// flip the images in either direction. May cancel out any orientation
197  /// flipping.
198  /// @{
199  void flipImageVertical();
200  void flipImageHorizontal();
201  /// @}
202 
203  /// rotate the image 90', flopping it on its side.
204  void flopImage();
205 
206 
207  // COLOR CORRECTION -----------------------------------------------------
208 
209  /// @brief Color correct an image using a LUT
210  /// apply a lookup table to the data, but only those planes that match the
211  /// scope (ie, "C spec diff", "C*", "*beauty*")
212  /// If no @c plane_scope is specified, "*" is used.
213  void applyLUT(const char *lut,
214  const UT_StringHolder &plane_scope = UT_StringHolder(),
215  bool ocio = false);
216 
217  /// @brief Color correct an image using a gamma setting
218  /// Apply gamma to the planes matching the scope (ie, "C spec diff", "C*",
219  /// "*beauty*") If no @c gamma_scope is specified, "*" is ued.
220  void applyGamma(fpreal gamma,
221  const UT_StringHolder &gamma_scope = UT_StringHolder());
222 
223  /// Set the gamma and scope to apply any needed gamma correction to planes
224  /// being written. This overwrites any applyGamma() changes.
225  void adjustGammaForFormat(IMG_Stat &stat,
226  const IMG_Format *format,
227  IMG_DataType override_type = IMG_DT_ANY);
228 
229  /// Specifies the destination colorspace when reading, and the source
230  /// colorspace when writing (ie, the colorspace the raster is in, not the
231  /// file contents). Default colorspace is the scene linear role.
232  /// Only active if an OCIO LUT is used.
233  void setOCIODestColorSpace(const UT_StringHolder &ocio_colorspace);
234 
235  /// One or more looks (color transforms) that are applied to the image
236  /// after reading or before writing, in order of specification (whitespace
237  /// separated list).
238  void setOCIOLooks(const UT_StringHolder &looks);
239 
240  /// Set OCIO Source display/view (if the image data already has tone
241  /// mapping baked in).
242  void setOCIOSourceDisplay(const UT_StringHolder &display,
243  const UT_StringHolder &view);
244 
245  /// @{
246  /// Set up OCIO information fully
247  void setOCIOTransform(const UT_StringHolder &sspace,
248  const UT_StringHolder &dspace,
249  const UT_StringHolder &looks,
250  const UT_StringHolder &lut_scope = UT_StringHolder());
251  void setOCIOTransformView(const UT_StringHolder &sspace,
252  const UT_StringHolder &display,
253  const UT_StringHolder &view,
254  bool forward,
255  const UT_StringHolder &lut_scope = UT_StringHolder());
256  /// @}
257 
258  // INFORMATION ----------------------------------------------------------
259 
260  /// @brief Returns information about the image's alpha channel
261  /// Checks to see if the alpha plane is constant 1, cutout 0/1,
262  /// constant valued, varying, out-of-range (>1 or <0) or absent. Load only.
263  void detectAlphaDetails();
264 
265  // FORMAT SPECIFIC OPTIONS ----------------------------------------------
266 
267  /// set an input/output tag option for the format.
268  void setOption(const char *option, const char *value);
269 
270  /// options are a list of argument pairs, such as "artist", "Tom Smith".
271  /// The options list is terminated by a NULL.
272  void setOptions(const char **options);
273 
274  /// options are in a whitespace separated string "Artist 'Tom Jones'"
275  void setOptionsString(const char *option_pair_string);
276 
277  /// options are specified in the IMG_TileOptions structure
278  void setOptions(const IMG_TileOptions &info_with_options);
279 
280  /// set options based on a UT_Options (this is similar to using
281  /// IMG_TileOptions)
282  void setOptions(const UT_Options &options);
283 
284  /// Set metadata option
285  void setOption(const UT_StringHolder &key,
286  const IMG_MetadataItem &item)
287  { myMetadata.add(key, item); }
288 
289  /// @{
290  /// Set metadata
291  void setFileParm(const UT_StringHolder &key, const UT_JSONValue &val)
292  { myMetadata.add(key, IMG_MetadataItem(val)); }
293  void setFileParm(const UT_StringHolder &key, bool val)
294  { myMetadata.add(key, UT_JSONValue(val)); }
295  void setFileParm(const UT_StringHolder &key, int64 val)
296  { myMetadata.add(key, UT_JSONValue(val)); }
297  void setFileParm(const UT_StringHolder &key, fpreal64 val)
298  { myMetadata.add(key, UT_JSONValue(val)); }
299  void setFileParm(const UT_StringHolder &key,
300  const UT_StringHolder &val)
301  { myMetadata.add(key, UT_JSONValue(val)); }
302  void setFileParm(const UT_StringHolder &key,
303  const UT_OptionEntry &val)
304  { myMetadata.add(key, val); }
305  /// @}
306 
307  /// @{
308  /// Access to options
309  UT_StringArray SYS_DEPRECATED(20.0) options() const;
310  UT_StringArray SYS_DEPRECATED(20.0) optionValues() const;
311  IMG_Metadata &metadata() { return myMetadata; }
312  const IMG_Metadata &metadata() const { return myMetadata; }
313  void merge(const IMG_Metadata &opts, bool overwrite=true)
314  { myMetadata.merge(opts, overwrite); }
315  /// @}
316 
317  /// @{
318  /// Import an option
319  bool import(const UT_StringRef &name, bool &val) const
320  { return myMetadata.import(name, val); }
321  bool import(const UT_StringRef &name, int32 &val) const
322  { return myMetadata.import(name, val); }
323  bool import(const UT_StringRef &name, int64 &val) const
324  { return myMetadata.import(name, val); }
325  bool import(const UT_StringRef &name, fpreal32 &val) const
326  { return myMetadata.import(name, val); }
327  bool import(const UT_StringRef &name, fpreal64 &val) const
328  { return myMetadata.import(name, val); }
329  bool import(const UT_StringRef &name, UT_StringHolder &val) const
330  { return myMetadata.import(name, val); }
331  /// @}
332 
333  /// @brief Enable the tile inteface for reading or writing
334  /// If called, we're reading or writing tiles using IMG_File::readTile
335  /// and IMG_File::writeTile. The scanline versions will not work.
336  void useTileInterface();
337 
338  /// If set, files will not report errors and subsequent scanlines
339  /// will be returned as black.
341  { myContinueOnError = true; }
343  { return myContinueOnError; }
344 
345  /// @{
346  /// @private
347  void setIsNormal(bool f=true) { myIsNormal = f; }
348  bool isNormal() const { return myIsNormal; }
349  const UT_SharedPtr<img_MipCache> &mipCache() const { return myMipCache; }
351  { myMipCache = c; }
352  /// @}
353 
354 
355  /// @{
356  /// Debug
357  void dump() const;
358  void dump(UT_JSONWriter &w) const;
359  /// @}
360 
361  /// @{
362  /// LUT Accessors
363  const UT_StringHolder &lutFilename() const { return myLUTFilename; }
364  const UT_StringHolder &lutScope() const { return myLUTScope; }
365  bool lutIsOCIO() const { return myLutIsOCIO; }
366  fpreal gamma() const { return myGamma; }
367  const UT_StringHolder &gammaScope() const { return myGammaScope; }
368  const UT_StringHolder &ocioDestSpace() const { return myOCIODestSpace; }
369  const UT_StringHolder &ocioLooks() const { return myOCIOLooks; }
370  const UT_StringHolder &ocioView() const { return myOCIOView; }
371  const UT_StringHolder &ocioSourceDisplay() const { return myOCIOSourceDisplay; }
372  const UT_StringHolder &ocioSourceView() const { return myOCIOSourceView; }
373  bool ocioForward() const { return myOCIOForward; }
374 
376  {
377  myGain = gain;
378  myOffset = offset;
379  }
380  fpreal gain() const { return myGain; }
381  fpreal offset() const { return myOffset; }
382  /// @}
383 
384 private:
385  IMG_ImageType myImageType;
386  IMG_DataType myDataType;
387  IMG_ColorModel myColorModel;
388  IMG_ComponentOrder myComponentOrder;
389  IMG_XOrientation myOrientX;
390  IMG_YOrientation myOrientY;
391  int myMaxX, myMaxY;
392  int myResX, myResY;
393  fpreal myScaleX, myScaleY;
394  UT_FilterType myFilterType;
395  fpreal myGamma;
396  IMG_Interleave myInterleaved;
397  PXL_LumFunction myLumFunc;
398  fpreal myGain;
399  fpreal myOffset;
400 
401  bool myFlipHorizontal : 1,
402  myFlipVertical : 1,
403  myFlopImage : 1,
404  myReadDataWindowOnly :1,
405  myReadAreaFlag :1,
406  myReadUVAreaFlag : 1,
407  myUseTiles :1,
408  myUseLUT : 1,
409  myPowerTwoRes :1,
410  myResLimit:1,
411  myPreserveAspect : 1,
412  myAlphaSplit : 1,
413  myContinueOnError : 1,
414  myAlphaDetect: 1,
415  myIsNormal: 1,
416  myLutIsOCIO : 1,
417  myEnableMipLevel0Cache : 1;
418 
419  UT_DimRect myReadArea;
420  fpreal myReadUVArea[4];
421  UT_StringHolder myLUTFilename;
422  UT_StringHolder myLUTScope;
423  UT_StringHolder myGammaScope;
424  UT_StringHolder mySelectPlaneName;
425  UT_IntArray mySelectPlaneIndex;
426  UT_StringHolder myOCIODestSpace; // Doubles as display for view xforms
427  UT_StringHolder myOCIOLooks;
428  UT_StringHolder myOCIOView;
429  UT_StringHolder myOCIOSourceDisplay; // Source display/view
430  UT_StringHolder myOCIOSourceView;
431  bool myOCIOForward;
432 
433  IMG_Metadata myMetadata;
434 
435  UT_SharedPtr<img_MipCache> myMipCache;
436 };
437 
438 #endif
IMG_Interleave interleaved() const
const UT_StringHolder & ocioSourceView() const
const UT_StringHolder & ocioLooks() const
bool isNormal() const
int int32
Definition: SYS_Types.h:39
bool flipVertical() const
bool readDataWindowOnly() const
bool isReadArea() const
#define SYS_DEPRECATED(__V__)
const UT_IntArray & selectPlaneIndex() const
void setGainOffset(fpreal gain, fpreal offset)
IMG_ImageType
Type of image we want to create or have opened.
IMG_XOrientation
exint maxYres() const
IMG_ComponentOrder componentOrder() const
const UT_StringHolder & selectPlaneName() const
exint yres() const
const UT_StringHolder & lutScope() const
fpreal gamma() const
fpreal offset() const
const UT_StringHolder & ocioView() const
GLsizei const GLfloat * value
Definition: glcorearb.h:824
bool flopImage() const
int64 exint
Definition: SYS_Types.h:125
GLint level
Definition: glcorearb.h:108
IMG_MipRoundMode
fpreal xscale() const
const fpreal * getReadUVArea() const
GLint y
Definition: glcorearb.h:103
Class which writes ASCII or binary JSON streams.
Definition: UT_JSONWriter.h:37
exint xres() const
IMG_ColorModel colorModel() const
GLfloat GLfloat GLfloat v2
Definition: glcorearb.h:818
UT_FilterType
Definition: UT_FilterType.h:16
float fpreal32
Definition: SYS_Types.h:200
GLdouble u1
Definition: glad.h:2676
void setFileParm(const UT_StringHolder &key, fpreal64 val)
void setFileParm(const UT_StringHolder &key, const UT_JSONValue &val)
IMG_DataType dataType() const
double fpreal64
Definition: SYS_Types.h:201
PXL_LumFunction
Definition: PXL_LumFuncs.h:18
#define IMG_API
Definition: IMG_API.h:10
const UT_SharedPtr< img_MipCache > & mipCache() const
fpreal yscale() const
void setMipCache(const UT_SharedPtr< img_MipCache > &c)
GLfloat f
Definition: glcorearb.h:1926
const UT_StringHolder & ocioDestSpace() const
GLintptr offset
Definition: glcorearb.h:665
void setFileParm(const UT_StringHolder &key, const UT_OptionEntry &val)
bool flipHorizontal() const
const UT_StringHolder & gammaScope() const
std::shared_ptr< T > UT_SharedPtr
Wrapper around std::shared_ptr.
Definition: UT_SharedPtr.h:36
void setFileParm(const UT_StringHolder &key, int64 val)
IMG_DataType
Definition: IMG_FileTypes.h:17
void merge(const IMG_Metadata &opts, bool overwrite=true)
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
IMG_XOrientation orientX() const
GLdouble GLdouble GLint GLint order
Definition: glad.h:2676
long long int64
Definition: SYS_Types.h:116
#define SYS_NO_DISCARD_RESULT
Definition: SYS_Compiler.h:93
bool enableMipLevel0Cache() const
GLuint const GLchar * name
Definition: glcorearb.h:786
GLdouble GLdouble u2
Definition: glad.h:2676
SYS_NO_DISCARD_RESULT bool continueOnError() const
GLushort pattern
Definition: glad.h:2583
bool useTiles() const
GLint GLenum GLint x
Definition: glcorearb.h:409
GLenum mode
Definition: glcorearb.h:99
const UT_DimRect getReadArea() const
IMG_YOrientation
A map of string to various well defined value types.
Definition: UT_Options.h:84
bool powerTwoRes() const
bool isReadUVArea() const
const UT_StringHolder & ocioSourceDisplay() const
IMG_YOrientation orientY() const
PXL_LumFunction lumFunc() const
const UT_StringHolder & lutFilename() const
fpreal64 fpreal
Definition: SYS_Types.h:278
IMG_Interleave
Definition: IMG_FileTypes.h:76
bool alphaSplit() const
void setContinueOnError()
File options for manipulating image data on load or save. This class allows you to modify the incomin...
Definition: IMG_FileParms.h:39
bool ocioForward() const
IMG_ColorModel
Definition: IMG_FileTypes.h:52
GLfloat GLfloat v1
Definition: glcorearb.h:817
GLuint GLfloat * val
Definition: glcorearb.h:1608
void setOption(const UT_StringHolder &key, const IMG_MetadataItem &item)
Set metadata option.
bool lutIsOCIO() const
void setFileParm(const UT_StringHolder &key, const UT_StringHolder &val)
Class to store JSON objects as C++ objects.
Definition: UT_JSONValue.h:99
IMG_ComponentOrder
Definition: IMG_FileTypes.h:94
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:38
bool alphaDetect() const
Map of metadata items.
Definition: IMG_Metadata.h:217
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
exint maxXres() const
fpreal gain() const
bool resLimit() const
bool preserveAspect() const
const IMG_Metadata & metadata() const
UT_FilterType filterType() const
GA_API const UT_StringHolder area
void setFileParm(const UT_StringHolder &key, bool val)