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