Debian Codegraph @

core/libs/dngwriter/extra/dng_sdk/dng_host.h

raw
1 /*****************************************************************************/
2 // Copyright 2006-2019 Adobe Systems Incorporated
3 // All Rights Reserved.
4 //
5 // NOTICE: Adobe permits you to use, modify, and distribute this file in
6 // accordance with the terms of the Adobe license agreement accompanying it.
7 /*****************************************************************************/
8
9 /** \file
10 * Class definition for dng_host, initial point of contact and control between
11 * host application and DNG SDK.
12 */
13
14 /*****************************************************************************/
15
16 #ifndef __dng_host__
17 #define __dng_host__
18
19 /*****************************************************************************/
20
21 #include "dng_auto_ptr.h"
22 #include "dng_classes.h"
23 #include "dng_errors.h"
24 #include "dng_flags.h"
25 #include "dng_types.h"
26 #include "dng_uncopyable.h"
27
28 /*****************************************************************************/
29
30 /// @brief The main class for communication between the application and the
31 /// DNG SDK. Used to customize memory allocation and other behaviors.
32 ///
33 /// dng_host allows setting parameters for the DNG conversion, mediates callback
34 /// style interactions between the host application and the DNG SDK, and allows
35 /// controlling certain internal behavior of the SDK such as memory allocation.
36 /// Many applications will be able to use the default implementation of dng_host
37 /// by just setting the dng_memory_allocator and dng_abort_sniffer in the
38 /// constructor. More complex interactions will require deriving a class from
39 /// dng_host.
40 ///
41 /// Multiple dng_host objects can be allocated in a single process. This may
42 /// be useful for DNG processing on separate threads. (Distinct dng_host objects
43 /// are completely threadsafe for read/write. The application is responsible for
44 /// establishing mutual exclusion for read/write access to a single dng_host
45 /// object if it is used in multiple threads.)
46
47 class dng_host: private dng_uncopyable
48 {
49
50 private:
51
52 dng_memory_allocator *fAllocator;
53
54 dng_abort_sniffer *fSniffer;
55
56 // Does the host require all the image metadata (vs. just checking
57 // to see if the file is readable)?
58
59 bool fNeedsMeta;
60
61 // Does the host require actual image data (vs. just getting metadata
62 // or just checking to see if the file is readable)?
63
64 bool fNeedsImage;
65
66 // If we need the image data, can it be read at preview quality?
67
68 bool fForPreview;
69
70 // If non-zero, the minimum size (longer of the two pixel dimensions)
71 // image to read. If zero, or if the full size image is smaller than
72 // this, read the full size image.
73
74 uint32 fMinimumSize;
75
76 // What is the preferred size for a preview image? This can
77 // be slightly larger than the minimum size. Zero if we want
78 // the full resolution image.
79
80 uint32 fPreferredSize;
81
82 // What is the maximum size for a preview image? Zero if there
83 // is no maximum size limit.
84
85 uint32 fMaximumSize;
86
87 // The fraction of the image kept after a crop. This is used to
88 // adjust the sizes to take into account the cropping that
89 // will be peformed.
90
91 real64 fCropFactor;
92
93 // What DNG version should we keep enough data to save?
94
95 uint32 fSaveDNGVersion;
96
97 // Do we want to force saving to a linear DNG?
98
99 bool fSaveLinearDNG;
100
101 // Do we want to create JXL compressed in saved DNGs?
102
103 bool fLossyMosaicJXL = false;
104 bool fLosslessJXL = false;
105
106 // Keep the original raw file data block?
107
108 bool fKeepOriginalFile;
109
110 // Should we ignore the enhanced IFD when reading DNGs?
111
112 bool fIgnoreEnhanced;
113
114 // Is this host being used to perform a negative read for fast
115 // conversion to DNG?
116
117 bool fForFastSaveToDNG;
118
119 uint32 fFastSaveToDNGSize;
120
121 bool fPreserveStage2;
122
123 std::shared_ptr<const dng_jxl_encode_settings> fJXLEncodeSettings;
124
125 std::shared_ptr<const dng_jxl_color_space_info> fJXLColorSpaceInfo;
126
127 public:
128
129 /// Allocate a dng_host object, possiblly with custom allocator and sniffer.
130 /// \param allocator Allows controlling all memory allocation done via this
131 /// dng_host. Defaults to singleton global dng_memory_allocator, which calls
132 /// new/delete dng_malloc_block for appropriate size.
133 /// \param sniffer Used to periodically check if pending DNG conversions
134 /// should be aborted and to communicate progress updates. Defaults to singleton
135 /// global dng_abort_sniffer, which never aborts and ignores progress updated.
136
137 dng_host (dng_memory_allocator *allocator = NULL,
138 dng_abort_sniffer *sniffer = NULL);
139
140 /// Clean up direct memory for dng_host. Memory allocator and abort sniffer
141 /// are not deleted. Objects such as dng_image and others returned from
142 /// host can still be used after host is deleted.
143
144 virtual ~dng_host ();
145
146 /// Getter for host's memory allocator.
147
148 dng_memory_allocator & Allocator ();
149
150 /// Alocate a new dng_memory_block using the host's memory allocator.
151 /// Uses the Allocator() property of host to allocate a new block of memory.
152 /// Will call ThrowMemoryFull if block cannot be allocated.
153 /// \param logicalSize Number of usable bytes returned dng_memory_block
154 /// must contain.
155
156 virtual dng_memory_block * Allocate (uint32 logicalSize);
157
158 /// Setter for host's abort sniffer.
159
160 void SetSniffer (dng_abort_sniffer *sniffer)
161 {
162 fSniffer = sniffer;
163 }
164
165 /// Getter for host's abort sniffer.
166
167 dng_abort_sniffer * Sniffer ()
168 {
169 return fSniffer;
170 }
171
172 /// Check for pending abort. Should call ThrowUserCanceled if an abort
173 /// is pending.
174
175 virtual void SniffForAbort ();
176
177 /// Setter for flag determining whether all XMP metadata should be parsed.
178 /// Defaults to true. One might not want metadata when doing a quick check
179 /// to see if a file is readable.
180 /// \param needs If true, metadata is needed.
181
182 void SetNeedsMeta (bool needs)
183 {
184 fNeedsMeta = needs;
185 }
186
187 /// Getter for flag determining whether all XMP metadata should be parsed.
188
189 bool NeedsMeta () const
190 {
191 return fNeedsMeta;
192 }
193
194 /// Setter for flag determining whether DNG image data is needed. Defaults
195 /// to true. Image data might not be needed for applications which only
196 /// manipulate metadata.
197 /// \param needs If true, image data is needed.
198
199 void SetNeedsImage (bool needs)
200 {
201 fNeedsImage = needs;
202 }
203
204 /// Setter for flag determining whether DNG image data is needed.
205
206 bool NeedsImage () const
207 {
208 return fNeedsImage;
209 }
210
211 /// Setter for flag determining whether image should be preview quality,
212 /// or full quality.
213 /// \param preview If true, rendered images are for preview.
214
215 void SetForPreview (bool preview)
216 {
217 fForPreview = preview;
218 }
219
220 /// Getter for flag determining whether image should be preview quality.
221 /// Preview quality images may be rendered more quickly. Current DNG SDK
222 /// does not change rendering behavior based on this flag, but derived
223 /// versions may use this getter to choose between a slower more accurate path
224 /// and a faster "good enough for preview" one. Data produce with ForPreview set
225 /// to true should not be written back to a DNG file, except as a preview image.
226
227 bool ForPreview () const
228 {
229 return fForPreview;
230 }
231
232 /// Setter for the minimum preview size.
233 /// \param size Minimum pixel size (long side of image).
234
235 void SetMinimumSize (uint32 size)
236 {
237 fMinimumSize = size;
238 }
239
240 /// Getter for the minimum preview size.
241
242 uint32 MinimumSize () const
243 {
244 return fMinimumSize;
245 }
246
247 /// Setter for the preferred preview size.
248 /// \param size Preferred pixel size (long side of image).
249
250 void SetPreferredSize (uint32 size)
251 {
252 fPreferredSize = size;
253 }
254
255 /// Getter for the preferred preview size.
256
257 uint32 PreferredSize () const
258 {
259 return fPreferredSize;
260 }
261
262 /// Setter for the maximum preview size.
263 /// \param size Maximum pixel size (long side of image).
264
265 void SetMaximumSize (uint32 size)
266 {
267 fMaximumSize = size;
268 }
269
270 /// Getter for the maximum preview size.
271
272 uint32 MaximumSize () const
273 {
274 return fMaximumSize;
275 }
276
277 /// Setter for the perform fast save to DNG.
278 /// \param flag True if the host is being used to perform a negative
279 /// read for fast conversion to DNG, false otherwise.
280
281 void SetForFastSaveToDNG (bool flag,
282 uint32 size)
283 {
284 fForFastSaveToDNG = flag;
285 fFastSaveToDNGSize = size;
286 }
287
288 /// Getter for the Boolean value that indicates whether this host is
289 /// being used to perform a negative read for fast conversion to DNG.
290
291 bool ForFastSaveToDNG () const
292 {
293 return fForFastSaveToDNG;
294 }
295
296 uint32 FastSaveToDNGSize () const
297 {
298 return fFastSaveToDNGSize;
299 }
300
301 /// Setter for the cropping factor.
302 /// \param cropFactor Fraction of image to be used after crop.
303
304 void SetCropFactor (real64 cropFactor)
305 {
306 fCropFactor = cropFactor;
307 }
308
309 /// Getter for the cropping factor.
310
311 real64 CropFactor () const
312 {
313 return fCropFactor;
314 }
315
316 /// Makes sures minimum, preferred, and maximum sizes are reasonable.
317
318 void ValidateSizes ();
319
320 /// Setter for what version to save DNG file compatible with.
321 /// \param version What version to save DNG file compatible with.
322
323 void SetSaveDNGVersion (uint32 version)
324 {
325 fSaveDNGVersion = version;
326 }
327
328 /// Getter for what version to save DNG file compatible with.
329
330 virtual uint32 SaveDNGVersion () const;
331
332 /// Setter for flag determining whether to force saving a linear DNG file.
333 /// \param linear If true, we should force saving a linear DNG file.
334
335 void SetSaveLinearDNG (bool linear)
336 {
337 fSaveLinearDNG = linear;
338 }
339
340 /// Getter for flag determining whether to save a linear DNG file.
341
342 virtual bool SaveLinearDNG (const dng_negative &negative) const;
343
344 /// Getter for flag determining whether to save DNG with lossy
345 /// compressed mosaic if possible.
346
347 bool LossyMosaicJXL () const
348 {
349 return fLossyMosaicJXL;
350 }
351
352 /// Setter for flag determining whether to save DNG with lossy
353 /// compressed mosaic if possible.
354 /// \param want If true, attempt to save lossy compressed mosaic.
355
356 bool SetLossyMosaicJXL (bool want)
357 {
358 return fLossyMosaicJXL = want;
359 }
360
361 /// Getter for flag determining whether to save DNG with lossless
362 /// compression if possible.
363
364 bool LosslessJXL () const
365 {
366 return fLosslessJXL;
367 }
368
369 /// Setter for flag determining whether to save DNG with lossless
370 /// compression if possible.
371 /// \param want If true, attempt to save using lossless JXL.
372
373 bool SetLosslessJXL (bool want)
374 {
375 return fLosslessJXL = want;
376 }
377
378 /// Setter for flag determining whether to keep original raw file data.
379 /// \param keep If true, original raw data will be kept.
380
381 void SetKeepOriginalFile (bool keep)
382 {
383 fKeepOriginalFile = keep;
384 }
385
386 /// Getter for flag determining whether to keep original raw file data.
387
388 bool KeepOriginalFile ()
389 {
390 return fKeepOriginalFile;
391 }
392
393 /// Getter for ignored enhanced IFD flag.
394
395 bool IgnoreEnhanced () const
396 {
397 return fIgnoreEnhanced;
398 }
399
400 /// Setter for ignored enhanced IFD flag.
401
402 void SetIgnoreEnhanced (bool state)
403 {
404 fIgnoreEnhanced = state;
405 }
406
407 /// Determine if an error is the result of a temporary, but planned-for
408 /// occurence such as user cancellation or memory exhaustion. This method is
409 /// sometimes used to determine whether to try and continue processing a DNG
410 /// file despite errors in the file format, etc. In such cases, processing will
411 /// be continued if IsTransientError returns false. This is so that user cancellation
412 /// and memory exhaustion always terminate processing.
413 /// \param code Error to test for transience.
414
415 virtual bool IsTransientError (dng_error_code code);
416
417 /// General top-level botttleneck for image processing tasks.
418 /// Default implementation calls dng_area_task::PerformAreaTask method on
419 /// task. Can be overridden in derived classes to support multiprocessing,
420 /// for example.
421 /// \param task Image processing task to perform on area.
422 /// \param area Rectangle over which to perform image processing task.
423
424 virtual void PerformAreaTask (dng_area_task &task,
425 const dng_rect &area,
426 dng_area_task_progress *progress = NULL);
427
428 /// How many multiprocessing threads does PerformAreaTask use?
429 /// Default implementation always returns 1 since it is single threaded.
430
431 virtual uint32 PerformAreaTaskThreads ();
432
433 /// Factory method for dng_exif class. Can be used to customize allocation or
434 /// to ensure a derived class is used instead of dng_exif.
435
436 virtual dng_exif * Make_dng_exif ();
437
438 /// Factory method for dng_xmp class. Can be used to customize allocation or
439 /// to ensure a derived class is used instead of dng_xmp.
440
441 #if qDNGUseXMP
442 virtual dng_xmp * Make_dng_xmp ();
443 #endif
444
445 /// Factory method for dng_shared class. Can be used to customize allocation
446 /// or to ensure a derived class is used instead of dng_shared.
447
448 virtual dng_shared * Make_dng_shared ();
449
450 /// Factory method for dng_ifd class. Can be used to customize allocation or
451 /// to ensure a derived class is used instead of dng_ifd.
452
453 virtual dng_ifd * Make_dng_ifd ();
454
455 /// Factory method for dng_negative class. Can be used to customize allocation
456 /// or to ensure a derived class is used instead of dng_negative.
457
458 virtual dng_negative * Make_dng_negative ();
459
460 /// Factory method for dng_image class. Can be used to customize allocation
461 /// or to ensure a derived class is used instead of dng_simple_image.
462
463 virtual dng_image * Make_dng_image (const dng_rect &bounds,
464 uint32 planes,
465 uint32 pixelType);
466
467 /// Factory method for parsing dng_opcode based class. Can be used to
468 /// override opcode implementations.
469
470 virtual dng_opcode * Make_dng_opcode (uint32 opcodeID,
471 dng_stream &stream);
472
473 /// Factory method for making a dng_rgb_to_rgb_table_data based class.
474
475 virtual dng_rgb_to_rgb_table_data *
476 Make_dng_rgb_to_rgb_table_data (const dng_rgb_table &table);
477
478 /// Factory method to apply a dng_opcode_list. Can be used to override
479 /// opcode list applications.
480
481 virtual void ApplyOpcodeList (dng_opcode_list &list,
482 dng_negative &negative,
483 AutoPtr<dng_image> &image);
484
485 /// Factory method to resample an image. Can be used to override
486 /// image method used to resample images.
487
488 virtual void ResampleImage (const dng_image &srcImage,
489 dng_image &dstImage);
490
491 /// Getter for flag determining whether we should preserve the stage 2
492 /// image after building the stage 3 image.
493
494 bool WantsPreserveStage2 () const
495 {
496 return fPreserveStage2;
497 }
498
499 /// Setter for flag determining whether we should preserve the stage 2
500 /// image after building the stage 3 image.
501
502 void SetWantsPreserveStage2 (bool flag)
503 {
504 fPreserveStage2 = flag;
505 }
506
507 /// JXL compression API.
508
509 void SetJXLEncodeSettings (const dng_jxl_encode_settings &settings);
510
511 const dng_jxl_encode_settings * JXLEncodeSettings () const
512 {
513 return fJXLEncodeSettings.get ();
514 }
515
516 void SetJXLColorSpaceInfo (std::shared_ptr<const dng_jxl_color_space_info> info)
517 {
518 fJXLColorSpaceInfo = info;
519 }
520
521 const dng_jxl_color_space_info * JXLColorSpaceInfo () const
522 {
523 return fJXLColorSpaceInfo.get ();
524 }
525
526 std::shared_ptr<const dng_jxl_color_space_info> ShareJXLColorSpaceInfo () const
527 {
528 return fJXLColorSpaceInfo;
529 }
530
531 enum use_case_enum
532 {
533 use_case_LossyMosaic,
534 use_case_LosslessMosaic,
535 use_case_MainImage,
536 use_case_LosslessMainImage,
537 use_case_EncodedMainImage,
538 use_case_ProxyImage,
539 use_case_EnhancedImage,
540 use_case_LosslessEnhancedImage,
541 use_case_MergeResults,
542 use_case_Transparency,
543 use_case_LosslessTransparency,
544 use_case_Depth,
545 use_case_LosslessDepth,
546 use_case_SemanticMask,
547 use_case_LosslessSemanticMask,
548 use_case_RenderedPreview,
549 use_case_GainMap,
550 use_case_LosslessGainMap
551 };
552
553 virtual dng_jxl_encode_settings *
554 MakeJXLEncodeSettings (use_case_enum useCase,
555 const dng_image &image,
556 const dng_negative *negative = nullptr) const;
557
558 };
559
560 /*****************************************************************************/
561
562 #endif // __dng_host__
563
564 /*****************************************************************************/