SnapshotUtils.h

//========================================================================================
// 
// $File$
// 
// Owner: Seoras Ashby
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 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. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
// 
// SnapshotUtils draws items into a memory based graphics context creating a bitmap,
// or "snapshot", that can be exported to a stream in a variety of formats. Drawing
// is performed internally by SnapshotUtils via the draw manager IDrawMgr.
// 
// Overloaded constructors assist in the creation of snapshots of:
// complete spreads, pages and page items or;
// selected areas of these items or;
// items drawn later by the caller via the Draw() method.
// 
// The constructors allow the caller to control the scale of the snapshot, the amount
// of bleed, the drawing flags passed to IDrawMgr, whether graphics and images
// are rendered in full resolution or by proxy, whether a grayscale or RGB bitmap is 
// made and whether an alpha channel for pixel transparency should be generated.
// 
// After constructing a SnapshotUtils() object the caller must call GetStatus() to 
// check the snapshot was created successfully.
// 
// If successful the caller can access the snapshot by exporting it to a stream
// via the ExportImage() method. The snapshot bitmap is filtered by the image write format 
// service specified by the caller and written to the stream. A variety of filters are
// available (e.g. JPEG, TIFF, GIF).
// 
// Notes:
// 
// The default resolution of the snapshot bitmap is 72 dpi.
// 
// The maximum size of bitmap frame buffer allocated by SnapshotUtils is 2MB. 
// 
// Downsampling will be applied if the area to be drawn could not be rendered at the requested
// scale within the limits of the frame buffer.
// 
// GetStatus() will return kFailure if memory could not be allocated for any reason or if
// the area to be drawn still could not be rendered within the limited size of frame buffer 
// after downsampling.
// 
// Sample:
// 
// void ItemSnapshot(const UIDRef& itemUIDRef, IPMStream* stream)
// 
// SnapshotUtils snapshot(itemUIDRef);
// if (snapshot.GetStatus() == kSuccess)
// snapshot.ExportImage(kJPEGImageWriteFormatBoss, stream);
// 
//========================================================================================

#ifndef __SnapshotUtils_h__
#define __SnapshotUtils_h__

class IPMStream;
class IDataBase;

#include "IShape.h"
#include "AGMGraphicsContext.h"
#include "AGMImageAccessor.h"

class SnapshotUtilsImpl;

#ifdef ID_DEPRECATED

class SnapshotUtils
{
public:

 typedef enum
 {
 kSSJPEGBaseline,
 kSSJPEGProgressive
 } SSJPEGEncoding; 

 typedef enum
 {
 kSSJPEGLowQuality,
 kSSJPEGGoodQuality,
 kSSJPEGExcellentQuality,
 kSSJPEGGreatQuality
 } SSJPEGQuality;

 typedef enum
 {
 kNoPalette, // Indicates that the image should not be indexed
 kTryExactThenAdaptivePalette, // attempts to create an Exact Color Table. If it can't then an Adaptive Palette will be created.
 kMacPalette, // Use the Macintosh 256 entry system palette from Photoshop
 kWebPalette, // Use a 216 entry web safe color palette
 kWinPalette // Use the Windows 256 entry system palette from Photoshop
 } PaletteType;
 
 typedef enum
 {
 kXPOff = 0,
 kXPLow, // Crude approximations of transparency effects, blends honored
 kXPMedium, // Low quality transparency effects, no page isolation set
 kXPHigh, // Normal
 kXPMaximum // Resolution independent transparency effects (may not be implemented)
 } Transparencies;

 SnapshotUtils
 (
 const UIDRef& itemUIDRef, 
 const PMReal& xScaleFactor = 1.0,
 const PMReal& yScaleFactor = 1.0,
 const PMReal& desiredRes = 72.0,
 const PMReal& minRes = 72.0,
 const PMReal& bleedAmount = 0.0,
 int32 flags = IShape::kPreviewMode,
 bool8 fullResolutionGraphics = kFalse,
 bool8 drawGray = kFalse, 
 bool8 addTransparencyAlpha = kFalse,
 Transparencies transparencyQuality = kXPHigh,
 const PMReal& greekBelowPtSize = 7.0,
 bool8 antiAliasing = kTrue,
 bool8 overprintPreview = kFalse
 );
 

 SnapshotUtils
 (
 const PMRect& clippingBounds, 
 const PMMatrix& boundsToSpreadMatrix, 
 const UIDRef& itemUIDRef, 
 const PMReal& xScaleFactor = 1.0,
 const PMReal& yScaleFactor = 1.0,
 const PMReal& desiredRes = 72.0,
 const PMReal& minRes = 72.0,
 const PMReal& bleedAmount = 0.0, 
 int32 flags = IShape::kPreviewMode, 
 bool8 fullResolutionGraphics = kFalse, 
 bool8 drawGray = kFalse, 
 bool8 addTransparencyAlpha = kFalse,
 Transparencies transparencyQuality = kXPHigh,
 const PMReal& greekBelowPtSize = 7.0,
 bool8 antiAliasing = kTrue,
 bool8 overprintPreview = kFalse
 );
 

 SnapshotUtils
 (
 const PMRect& clippingBounds, 
 const PMMatrix& boundsToSpreadMatrix, 
 IDataBase* database, 
 const PMReal& xScaleFactor = 1.0,
 const PMReal& yScaleFactor = 1.0, 
 const PMReal& desiredRes = 72.0,
 const PMReal& minRes = 72.0, 
 const PMReal& bleedAmount = 0.0, 
 int32 flags = IShape::kPreviewMode,
 bool8 fullResolutionGraphics = kFalse,
 bool8 drawGray = kFalse, 
 bool8 addTransparencyAlpha = kFalse,
 Transparencies transparencyQuality = kXPHigh,
 const PMReal& greekBelowPtSize = 7.0,
 bool8 antiAliasing = kTrue,
 bool8 overprintPreview = kFalse
 );
 
 virtual ~SnapshotUtils();

 ErrorCode GetStatus() const;
 
 void Draw(const UID& itemUID);
 
 ErrorCode ExportImage
 (
 ClassID formatClass,
 IPMStream* writeStream,
 bool8 colorMapped = kFalse
 ); 
 
 ErrorCode ExportImageToJPEG
 (
 IPMStream* writeStream, 
 SSJPEGEncoding encoding = kSSJPEGBaseline,
 SSJPEGQuality quality = kSSJPEGExcellentQuality
 );
 
 ErrorCode ExportImageToTIFF
 (
 IPMStream* writeStream,
 PaletteType paletteType = kNoPalette
 );

 ErrorCode ExportImageToGIF
 (
 IPMStream* writeStream, 
 PaletteType paletteType = kTryExactThenAdaptivePalette,
 bool8 interlaced = kFalse
 );

 AGMGraphicsContext * GetGraphicsContext(void) const;

 AGMImageAccessor * CreateAGMImageAccessor(void) const;

 AGMImageAccessor * CreateAlphaAGMImageAccessor(void) const;

private:
 SnapshotUtilsImpl *fImpl;
};
#endif

#endif

// End, SnapshotUtils.h