/*****************************************************************************/

// 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

/*****************************************************************************/