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