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 
SetSniffer(dng_abort_sniffer * sniffer)141 		void SetSniffer (dng_abort_sniffer *sniffer)
142 			{
143 			fSniffer = sniffer;
144 			}
145 
146 		/// Getter for host's abort sniffer.
147 
Sniffer()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 
SetNeedsMeta(bool needs)163 		void SetNeedsMeta (bool needs)
164 			{
165 			fNeedsMeta = needs;
166 			}
167 
168 		/// Getter for flag determining whether all XMP metadata should be parsed.
169 
NeedsMeta()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 
SetNeedsImage(bool needs)180 		void SetNeedsImage (bool needs)
181 			{
182 			fNeedsImage = needs;
183 			}
184 
185 		/// Setter for flag determining whether DNG image data is needed.
186 
NeedsImage()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 
SetForPreview(bool preview)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 
ForPreview()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 
SetMinimumSize(uint32 size)216 		void SetMinimumSize (uint32 size)
217 			{
218 			fMinimumSize = size;
219 			}
220 
221 		/// Getter for the minimum preview size.
222 
MinimumSize()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 
SetPreferredSize(uint32 size)231 		void SetPreferredSize (uint32 size)
232 			{
233 			fPreferredSize = size;
234 			}
235 
236 		/// Getter for the preferred preview size.
237 
PreferredSize()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 
SetMaximumSize(uint32 size)246 		void SetMaximumSize (uint32 size)
247 			{
248 			fMaximumSize = size;
249 			}
250 
251 		/// Getter for the maximum preview size.
252 
MaximumSize()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 
SetCropFactor(real64 cropFactor)261 		void SetCropFactor (real64 cropFactor)
262 			{
263 			fCropFactor = cropFactor;
264 			}
265 
266 		/// Getter for the cropping factor.
267 
CropFactor()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 
SetSaveDNGVersion(uint32 version)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 
SetSaveLinearDNG(bool linear)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 
SetKeepOriginalFile(bool keep)304 		void SetKeepOriginalFile (bool keep)
305 			{
306 			fKeepOriginalFile = keep;
307 			}
308 
309 		/// Getter for flag determining whether to keep original RAW file data.
310 
KeepOriginalFile()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