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 | |
50 | class 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 | |