/*****************************************************************************/
// Copyright 2006-2012 Adobe Systems Incorporated
// All Rights Reserved.
//
// NOTICE: Adobe permits you to use, modify, and distribute this file in
// accordance with the terms of the Adobe license agreement accompanying it.
/*****************************************************************************/
/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_host.h#2 $ */
/* $DateTime: 2012/06/14 20:24:41 $ */
/* $Change: 835078 $ */
/* $Author: tknoll $ */
/** \file
* Class definition for dng_host, initial point of contact and control between
* host application and DNG SDK.
*/
/*****************************************************************************/
#ifndef __dng_host__
#define __dng_host__
/*****************************************************************************/
#include "dng_auto_ptr.h"
#include "dng_classes.h"
#include "dng_errors.h"
#include "dng_types.h"
/*****************************************************************************/
/// \brief The main class for communication between the application and the
/// DNG SDK. Used to customize memory allocation and other behaviors.
///
/// dng_host allows setting parameters for the DNG conversion, mediates callback
/// style interactions between the host application and the DNG SDK, and allows
/// controlling certain internal behavior of the SDK such as memory allocation.
/// Many applications will be able to use the default implementation of dng_host
/// by just setting the dng_memory_allocator and dng_abort_sniffer in the
/// constructor. More complex interactions will require deriving a class from
/// dng_host.
///
/// Multiple dng_host objects can be allocated in a single process. This may
/// be useful for DNG processing on separate threads. (Distinct dng_host objects
/// are completely threadsafe for read/write. The application is responsible for
/// establishing mutual exclusion for read/write access to a single dng_host
/// object if it is used in multiple threads.)
class dng_host
{
private:
dng_memory_allocator *fAllocator;
dng_abort_sniffer *fSniffer;
// Does the host require all the image metadata (vs. just checking
// to see if the file is readable)?
bool fNeedsMeta;
// Does the host require actual image data (vs. just getting metadata
// or just checking to see if the file is readable)?
bool fNeedsImage;
// If we need the image data, can it be read at preview quality?
bool fForPreview;
// If non-zero, the minimum size (longer of the two pixel dimensions)
// image to read. If zero, or if the full size image is smaller than
// this, read the full size image.
uint32 fMinimumSize;
// What is the preferred size for a preview image? This can
// be slightly larger than the minimum size. Zero if we want
// the full resolution image.
uint32 fPreferredSize;
// What is the maximum size for a preview image? Zero if there
// is no maximum size limit.
uint32 fMaximumSize;
// The fraction of the image kept after a crop. This is used to
// adjust the sizes to take into account the cropping that
// will be peformed.
real64 fCropFactor;
// What DNG version should we keep enough data to save?
uint32 fSaveDNGVersion;
// Do we want to force saving to a linear DNG?
bool fSaveLinearDNG;
// Keep the original raw file data block?
bool fKeepOriginalFile;
public:
/// Allocate a dng_host object, possiblly with custom allocator and sniffer.
/// \param allocator Allows controlling all memory allocation done via this
/// dng_host. Defaults to singleton global dng_memory_allocator, which calls
/// new/delete dng_malloc_block for appropriate size.
/// \param sniffer Used to periodically check if pending DNG conversions
/// should be aborted and to communicate progress updates. Defaults to singleton
/// global dng_abort_sniffer, which never aborts and ignores progress updated.
dng_host (dng_memory_allocator *allocator = NULL,
dng_abort_sniffer *sniffer = NULL);
/// Clean up direct memory for dng_host. Memory allocator and abort sniffer
/// are not deleted. Objects such as dng_image and others returned from
/// host can still be used after host is deleted.
virtual ~dng_host ();
/// Getter for host's memory allocator.
dng_memory_allocator & Allocator ();
/// Alocate a new dng_memory_block using the host's memory allocator.
/// Uses the Allocator() property of host to allocate a new block of memory.
/// Will call ThrowMemoryFull if block cannot be allocated.
/// \param logicalSize Number of usable bytes returned dng_memory_block
/// must contain.
virtual dng_memory_block * Allocate (uint32 logicalSize);
/// Setter for host's abort sniffer.
void SetSniffer (dng_abort_sniffer *sniffer)
{
fSniffer = sniffer;
}
/// Getter for host's abort sniffer.
dng_abort_sniffer * Sniffer ()
{
return fSniffer;
}
/// Check for pending abort. Should call ThrowUserCanceled if an abort
/// is pending.
virtual void SniffForAbort ();
/// Setter for flag determining whether all XMP metadata should be parsed.
/// Defaults to true. One might not want metadata when doing a quick check
/// to see if a file is readable.
/// \param needs If true, metadata is needed.
void SetNeedsMeta (bool needs)
{
fNeedsMeta = needs;
}
/// Getter for flag determining whether all XMP metadata should be parsed.
bool NeedsMeta () const
{
return fNeedsMeta;
}
/// Setter for flag determining whether DNG image data is needed. Defaults
/// to true. Image data might not be needed for applications which only
/// manipulate metadata.
/// \param needs If true, image data is needed.
void SetNeedsImage (bool needs)
{
fNeedsImage = needs;
}
/// Setter for flag determining whether DNG image data is needed.
bool NeedsImage () const
{
return fNeedsImage;
}
/// Setter for flag determining whether image should be preview quality,
/// or full quality.
/// \param preview If true, rendered images are for preview.
void SetForPreview (bool preview)
{
fForPreview = preview;
}
/// Getter for flag determining whether image should be preview quality.
/// Preview quality images may be rendered more quickly. Current DNG SDK
/// does not change rendering behavior based on this flag, but derived
/// versions may use this getter to choose between a slower more accurate path
/// and a faster "good enough for preview" one. Data produce with ForPreview set
/// to true should not be written back to a DNG file, except as a preview image.
bool ForPreview () const
{
return fForPreview;
}
/// Setter for the minimum preview size.
/// \param size Minimum pixel size (long side of image).
void SetMinimumSize (uint32 size)
{
fMinimumSize = size;
}
/// Getter for the minimum preview size.
uint32 MinimumSize () const
{
return fMinimumSize;
}
/// Setter for the preferred preview size.
/// \param size Preferred pixel size (long side of image).
void SetPreferredSize (uint32 size)
{
fPreferredSize = size;
}
/// Getter for the preferred preview size.
uint32 PreferredSize () const
{
return fPreferredSize;
}
/// Setter for the maximum preview size.
/// \param size Maximum pixel size (long side of image).
void SetMaximumSize (uint32 size)
{
fMaximumSize = size;
}
/// Getter for the maximum preview size.
uint32 MaximumSize () const
{
return fMaximumSize;
}
/// Setter for the cropping factor.
/// \param cropFactor Fraction of image to be used after crop.
void SetCropFactor (real64 cropFactor)
{
fCropFactor = cropFactor;
}
/// Getter for the cropping factor.
real64 CropFactor () const
{
return fCropFactor;
}
/// Makes sures minimum, preferred, and maximum sizes are reasonable.
void ValidateSizes ();
/// Setter for what version to save DNG file compatible with.
/// \param version What version to save DNG file compatible with.
void SetSaveDNGVersion (uint32 version)
{
fSaveDNGVersion = version;
}
/// Getter for what version to save DNG file compatible with.
virtual uint32 SaveDNGVersion () const;
/// Setter for flag determining whether to force saving a linear DNG file.
/// \param linear If true, we should force saving a linear DNG file.
void SetSaveLinearDNG (bool linear)
{
fSaveLinearDNG = linear;
}
/// Getter for flag determining whether to save a linear DNG file.
virtual bool SaveLinearDNG (const dng_negative &negative) const;
/// Setter for flag determining whether to keep original RAW file data.
/// \param keep If true, origianl RAW data will be kept.
void SetKeepOriginalFile (bool keep)
{
fKeepOriginalFile = keep;
}
/// Getter for flag determining whether to keep original RAW file data.
bool KeepOriginalFile ()
{
return fKeepOriginalFile;
}
/// Determine if an error is the result of a temporary, but planned-for
/// occurence such as user cancellation or memory exhaustion. This method is
/// sometimes used to determine whether to try and continue processing a DNG
/// file despite errors in the file format, etc. In such cases, processing will
/// be continued if IsTransientError returns false. This is so that user cancellation
/// and memory exhaustion always terminate processing.
/// \param code Error to test for transience.
virtual bool IsTransientError (dng_error_code code);
/// General top-level botttleneck for image processing tasks.
/// Default implementation calls dng_area_task::PerformAreaTask method on
/// task. Can be overridden in derived classes to support multiprocessing,
/// for example.
/// \param task Image processing task to perform on area.
/// \param area Rectangle over which to perform image processing task.
virtual void PerformAreaTask (dng_area_task &task,
const dng_rect &area);
/// How many multiprocessing threads does PerformAreaTask use?
/// Default implementation always returns 1 since it is single threaded.
virtual uint32 PerformAreaTaskThreads ();
/// Factory method for dng_exif class. Can be used to customize allocation or
/// to ensure a derived class is used instead of dng_exif.
virtual dng_exif * Make_dng_exif ();
/// Factory method for dng_xmp class. Can be used to customize allocation or
/// to ensure a derived class is used instead of dng_xmp.
#if qDNGUseXMP
virtual dng_xmp * Make_dng_xmp ();
#endif
/// Factory method for dng_shared class. Can be used to customize allocation
/// or to ensure a derived class is used instead of dng_shared.
virtual dng_shared * Make_dng_shared ();
/// Factory method for dng_ifd class. Can be used to customize allocation or
/// to ensure a derived class is used instead of dng_ifd.
virtual dng_ifd * Make_dng_ifd ();
/// Factory method for dng_negative class. Can be used to customize allocation
/// or to ensure a derived class is used instead of dng_negative.
virtual dng_negative * Make_dng_negative ();
/// Factory method for dng_image class. Can be used to customize allocation
/// or to ensure a derived class is used instead of dng_simple_image.
virtual dng_image * Make_dng_image (const dng_rect &bounds,
uint32 planes,
uint32 pixelType);
/// Factory method for parsing dng_opcode based classs. Can be used to
/// override opcode implementations.
virtual dng_opcode * Make_dng_opcode (uint32 opcodeID,
dng_stream &stream);
/// Factory method to apply a dng_opcode_list. Can be used to override
/// opcode list applications.
virtual void ApplyOpcodeList (dng_opcode_list &list,
dng_negative &negative,
AutoPtr<dng_image> &image);
/// Factory method to resample an image. Can be used to override
/// image method used to resample images.
virtual void ResampleImage (const dng_image &srcImage,
dng_image &dstImage);
private:
// Hidden copy constructor and assignment operator.
dng_host (const dng_host &host);
dng_host & operator= (const dng_host &host);
};
/*****************************************************************************/
#endif
/*****************************************************************************/