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