1/*****************************************************************************/
2// Copyright 2006-2012 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/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_host.h#2 $ */
10/* $DateTime: 2012/06/14 20:24:41 $ */
11/* $Change: 835078 $ */
12/* $Author: tknoll $ */
13
14/** \file
15 * Class definition for dng_host, initial point of contact and control between
16 * host application and DNG SDK.
17 */
18
19/*****************************************************************************/
20
21#ifndef __dng_host__
22#define __dng_host__
23
24/*****************************************************************************/
25
26#include "dng_auto_ptr.h"
27#include "dng_classes.h"
28#include "dng_errors.h"
29#include "dng_types.h"
30
31/*****************************************************************************/
32
33/// \brief The main class for communication between the application and the
34/// DNG SDK. Used to customize memory allocation and other behaviors.
35///
36/// dng_host allows setting parameters for the DNG conversion, mediates callback
37/// style interactions between the host application and the DNG SDK, and allows
38/// controlling certain internal behavior of the SDK such as memory allocation.
39/// Many applications will be able to use the default implementation of dng_host
40/// by just setting the dng_memory_allocator and dng_abort_sniffer in the
41/// constructor. More complex interactions will require deriving a class from
42/// dng_host.
43///
44/// Multiple dng_host objects can be allocated in a single process. This may
45/// be useful for DNG processing on separate threads. (Distinct dng_host objects
46/// are completely threadsafe for read/write. The application is responsible for
47/// establishing mutual exclusion for read/write access to a single dng_host
48/// object if it is used in multiple threads.)
49
50class dng_host
51 {
52
53 private:
54
55 dng_memory_allocator *fAllocator;
56
57 dng_abort_sniffer *fSniffer;
58
59 // Does the host require all the image metadata (vs. just checking
60 // to see if the file is readable)?
61
62 bool fNeedsMeta;
63
64 // Does the host require actual image data (vs. just getting metadata
65 // or just checking to see if the file is readable)?
66
67 bool fNeedsImage;
68
69 // If we need the image data, can it be read at preview quality?
70
71 bool fForPreview;
72
73 // If non-zero, the minimum size (longer of the two pixel dimensions)
74 // image to read. If zero, or if the full size image is smaller than
75 // this, read the full size image.
76
77 uint32 fMinimumSize;
78
79 // What is the preferred size for a preview image? This can
80 // be slightly larger than the minimum size. Zero if we want
81 // the full resolution image.
82
83 uint32 fPreferredSize;
84
85 // What is the maximum size for a preview image? Zero if there
86 // is no maximum size limit.
87
88 uint32 fMaximumSize;
89
90 // The fraction of the image kept after a crop. This is used to
91 // adjust the sizes to take into account the cropping that
92 // will be peformed.
93
94 real64 fCropFactor;
95
96 // What DNG version should we keep enough data to save?
97
98 uint32 fSaveDNGVersion;
99
100 // Do we want to force saving to a linear DNG?
101
102 bool fSaveLinearDNG;
103
104 // Keep the original raw file data block?
105
106 bool fKeepOriginalFile;
107
108 public:
109
110 /// Allocate a dng_host object, possiblly with custom allocator and sniffer.
111 /// \param allocator Allows controlling all memory allocation done via this
112 /// dng_host. Defaults to singleton global dng_memory_allocator, which calls
113 /// new/delete dng_malloc_block for appropriate size.
114 /// \param sniffer Used to periodically check if pending DNG conversions
115 /// should be aborted and to communicate progress updates. Defaults to singleton
116 /// global dng_abort_sniffer, which never aborts and ignores progress updated.
117
118 dng_host (dng_memory_allocator *allocator = NULL,
119 dng_abort_sniffer *sniffer = NULL);
120
121 /// Clean up direct memory for dng_host. Memory allocator and abort sniffer
122 /// are not deleted. Objects such as dng_image and others returned from
123 /// host can still be used after host is deleted.
124
125 virtual ~dng_host ();
126
127 /// Getter for host's memory allocator.
128
129 dng_memory_allocator & Allocator ();
130
131 /// Alocate a new dng_memory_block using the host's memory allocator.
132 /// Uses the Allocator() property of host to allocate a new block of memory.
133 /// Will call ThrowMemoryFull if block cannot be allocated.
134 /// \param logicalSize Number of usable bytes returned dng_memory_block
135 /// must contain.
136
137 virtual dng_memory_block * Allocate (uint32 logicalSize);
138
139 /// Setter for host's abort sniffer.
140
141 void SetSniffer (dng_abort_sniffer *sniffer)
142 {
143 fSniffer = sniffer;
144 }
145
146 /// Getter for host's abort sniffer.
147
148 dng_abort_sniffer * Sniffer ()
149 {
150 return fSniffer;
151 }
152
153 /// Check for pending abort. Should call ThrowUserCanceled if an abort
154 /// is pending.
155
156 virtual void SniffForAbort ();
157
158 /// Setter for flag determining whether all XMP metadata should be parsed.
159 /// Defaults to true. One might not want metadata when doing a quick check
160 /// to see if a file is readable.
161 /// \param needs If true, metadata is needed.
162
163 void SetNeedsMeta (bool needs)
164 {
165 fNeedsMeta = needs;
166 }
167
168 /// Getter for flag determining whether all XMP metadata should be parsed.
169
170 bool NeedsMeta () const
171 {
172 return fNeedsMeta;
173 }
174
175 /// Setter for flag determining whether DNG image data is needed. Defaults
176 /// to true. Image data might not be needed for applications which only
177 /// manipulate metadata.
178 /// \param needs If true, image data is needed.
179
180 void SetNeedsImage (bool needs)
181 {
182 fNeedsImage = needs;
183 }
184
185 /// Setter for flag determining whether DNG image data is needed.
186
187 bool NeedsImage () const
188 {
189 return fNeedsImage;
190 }
191
192 /// Setter for flag determining whether image should be preview quality,
193 /// or full quality.
194 /// \param preview If true, rendered images are for preview.
195
196 void SetForPreview (bool preview)
197 {
198 fForPreview = preview;
199 }
200
201 /// Getter for flag determining whether image should be preview quality.
202 /// Preview quality images may be rendered more quickly. Current DNG SDK
203 /// does not change rendering behavior based on this flag, but derived
204 /// versions may use this getter to choose between a slower more accurate path
205 /// and a faster "good enough for preview" one. Data produce with ForPreview set
206 /// to true should not be written back to a DNG file, except as a preview image.
207
208 bool ForPreview () const
209 {
210 return fForPreview;
211 }
212
213 /// Setter for the minimum preview size.
214 /// \param size Minimum pixel size (long side of image).
215
216 void SetMinimumSize (uint32 size)
217 {
218 fMinimumSize = size;
219 }
220
221 /// Getter for the minimum preview size.
222
223 uint32 MinimumSize () const
224 {
225 return fMinimumSize;
226 }
227
228 /// Setter for the preferred preview size.
229 /// \param size Preferred pixel size (long side of image).
230
231 void SetPreferredSize (uint32 size)
232 {
233 fPreferredSize = size;
234 }
235
236 /// Getter for the preferred preview size.
237
238 uint32 PreferredSize () const
239 {
240 return fPreferredSize;
241 }
242
243 /// Setter for the maximum preview size.
244 /// \param size Maximum pixel size (long side of image).
245
246 void SetMaximumSize (uint32 size)
247 {
248 fMaximumSize = size;
249 }
250
251 /// Getter for the maximum preview size.
252
253 uint32 MaximumSize () const
254 {
255 return fMaximumSize;
256 }
257
258 /// Setter for the cropping factor.
259 /// \param cropFactor Fraction of image to be used after crop.
260
261 void SetCropFactor (real64 cropFactor)
262 {
263 fCropFactor = cropFactor;
264 }
265
266 /// Getter for the cropping factor.
267
268 real64 CropFactor () const
269 {
270 return fCropFactor;
271 }
272
273 /// Makes sures minimum, preferred, and maximum sizes are reasonable.
274
275 void ValidateSizes ();
276
277 /// Setter for what version to save DNG file compatible with.
278 /// \param version What version to save DNG file compatible with.
279
280 void SetSaveDNGVersion (uint32 version)
281 {
282 fSaveDNGVersion = version;
283 }
284
285 /// Getter for what version to save DNG file compatible with.
286
287 virtual uint32 SaveDNGVersion () const;
288
289 /// Setter for flag determining whether to force saving a linear DNG file.
290 /// \param linear If true, we should force saving a linear DNG file.
291
292 void SetSaveLinearDNG (bool linear)
293 {
294 fSaveLinearDNG = linear;
295 }
296
297 /// Getter for flag determining whether to save a linear DNG file.
298
299 virtual bool SaveLinearDNG (const dng_negative &negative) const;
300
301 /// Setter for flag determining whether to keep original RAW file data.
302 /// \param keep If true, origianl RAW data will be kept.
303
304 void SetKeepOriginalFile (bool keep)
305 {
306 fKeepOriginalFile = keep;
307 }
308
309 /// Getter for flag determining whether to keep original RAW file data.
310
311 bool KeepOriginalFile ()
312 {
313 return fKeepOriginalFile;
314 }
315
316 /// Determine if an error is the result of a temporary, but planned-for
317 /// occurence such as user cancellation or memory exhaustion. This method is
318 /// sometimes used to determine whether to try and continue processing a DNG
319 /// file despite errors in the file format, etc. In such cases, processing will
320 /// be continued if IsTransientError returns false. This is so that user cancellation
321 /// and memory exhaustion always terminate processing.
322 /// \param code Error to test for transience.
323
324 virtual bool IsTransientError (dng_error_code code);
325
326 /// General top-level botttleneck for image processing tasks.
327 /// Default implementation calls dng_area_task::PerformAreaTask method on
328 /// task. Can be overridden in derived classes to support multiprocessing,
329 /// for example.
330 /// \param task Image processing task to perform on area.
331 /// \param area Rectangle over which to perform image processing task.
332
333 virtual void PerformAreaTask (dng_area_task &task,
334 const dng_rect &area);
335
336 /// How many multiprocessing threads does PerformAreaTask use?
337 /// Default implementation always returns 1 since it is single threaded.
338
339 virtual uint32 PerformAreaTaskThreads ();
340
341 /// Factory method for dng_exif class. Can be used to customize allocation or
342 /// to ensure a derived class is used instead of dng_exif.
343
344 virtual dng_exif * Make_dng_exif ();
345
346 /// Factory method for dng_xmp class. Can be used to customize allocation or
347 /// to ensure a derived class is used instead of dng_xmp.
348
349 #if qDNGUseXMP
350
351 virtual dng_xmp * Make_dng_xmp ();
352
353 #endif
354
355 /// Factory method for dng_shared class. Can be used to customize allocation
356 /// or to ensure a derived class is used instead of dng_shared.
357
358 virtual dng_shared * Make_dng_shared ();
359
360 /// Factory method for dng_ifd class. Can be used to customize allocation or
361 /// to ensure a derived class is used instead of dng_ifd.
362
363 virtual dng_ifd * Make_dng_ifd ();
364
365 /// Factory method for dng_negative class. Can be used to customize allocation
366 /// or to ensure a derived class is used instead of dng_negative.
367
368 virtual dng_negative * Make_dng_negative ();
369
370 /// Factory method for dng_image class. Can be used to customize allocation
371 /// or to ensure a derived class is used instead of dng_simple_image.
372
373 virtual dng_image * Make_dng_image (const dng_rect &bounds,
374 uint32 planes,
375 uint32 pixelType);
376
377 /// Factory method for parsing dng_opcode based classs. Can be used to
378 /// override opcode implementations.
379
380 virtual dng_opcode * Make_dng_opcode (uint32 opcodeID,
381 dng_stream &stream);
382
383 /// Factory method to apply a dng_opcode_list. Can be used to override
384 /// opcode list applications.
385
386 virtual void ApplyOpcodeList (dng_opcode_list &list,
387 dng_negative &negative,
388 AutoPtr<dng_image> &image);
389
390 /// Factory method to resample an image. Can be used to override
391 /// image method used to resample images.
392
393 virtual void ResampleImage (const dng_image &srcImage,
394 dng_image &dstImage);
395
396 private:
397
398 // Hidden copy constructor and assignment operator.
399
400 dng_host (const dng_host &host);
401
402 dng_host & operator= (const dng_host &host);
403
404 };
405
406/*****************************************************************************/
407
408#endif
409
410/*****************************************************************************/
411