SnapshotUtilsEx Class Reference

#include <SnapshotUtilsEx.h>

Public Types
enum	SSColorSpaceFamily { kCsGray, kCsRGB, kCsCMYK, kCsLab }

Public Member Functions
	SnapshotUtilsEx (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, SSColorSpaceFamily colorSpace=kCsRGB, bool8 addTransparencyAlpha=kFalse, bool8 simulateOverprint=kFalse)
	SnapshotUtilsEx (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, SSColorSpaceFamily colorSpace=kCsRGB, bool8 addTransparencyAlpha=kFalse, bool8 simulateOverprint=kFalse)
	SnapshotUtilsEx (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, SSColorSpaceFamily colorSpace=kCsRGB, bool8 addTransparencyAlpha=kFalse, bool8 simulateOverprint=kFalse)
virtual	~SnapshotUtilsEx ()
ErrorCode	Draw (int32 flags=IShape::kPreviewMode, bool32 fullResolutionGraphics=kFalse, const PMReal &greekBelowPtSize=7.0, bool32 enableAntiAliasing=kTrue, SnapshotUtils::Transparencies transparencyQuality=SnapshotUtils::kXPHigh, IdleTimer *abortCheck=nil, VPAttrMap *pVPAttrMap=nil, bool32 bDrawNonPrintingObjects=kTrue)
ErrorCode	Draw (UID pageItem, int32 flags, bool32 fullResolutionGraphics, const PMReal &greekBelowPtSize, bool32 enableAntiAliasing, SnapshotUtils::Transparencies transparencyQuality, IdleTimer *abortCheck=nil, VPAttrMap *pVPAttrMap=nil, bool32 bDrawNonPrintingObjects=kTrue)
ErrorCode	ExportImage (ClassID formatClass, IPMStream *writeStream, bool8 colorMapped)
ErrorCode	ExportImageToJPEG (IPMStream *writeStream, SnapshotUtils::SSJPEGEncoding encoding=SnapshotUtils::kSSJPEGBaseline, SnapshotUtils::SSJPEGQuality quality=SnapshotUtils::kSSJPEGExcellentQuality, bool embedColorProfile=false)
ErrorCode	ExportImageToTIFF (IPMStream *writeStream, SnapshotUtils::PaletteType paletteType=SnapshotUtils::kNoPalette, bool embedColorProfile=false)
ErrorCode	ExportImageToGIF (IPMStream *writeStream, SnapshotUtils::PaletteType paletteType=SnapshotUtils::kTryExactThenAdaptivePalette, bool8 interlaced=kFalse)
ErrorCode	ExportImageToPNG (IPMStream *writeStream, uint32 compression=5)
AGMGraphicsContext *	GetGraphicsContext (void) const
AGMImageAccessor *	CreateAGMImageAccessor (void) const
AGMImageAccessor *	CreateAlphaAGMImageAccessor (void) const

Protected Attributes
SnapshotUtilsExImpl *	fImpl

Detailed Description

SnapshotUtilsEx is a utility class of routines designed to create an offscreen of a pageitem, page or spread and export it as a JPEG, GIF or TIFF. The client has options for colorspace, whether or not to include a transparency alpha, and options for bleed, image quality, and scaling.

Member Enumeration Documentation

enum SnapshotUtilsEx::SSColorSpaceFamily

ColorSpace options

Constructor & Destructor Documentation

SnapshotUtilsEx::SnapshotUtilsEx	(	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,
		SSColorSpaceFamily	colorSpace = kCsRGB,
		bool8	addTransparencyAlpha = kFalse,
		bool8	simulateOverprint = kFalse
	)

Calculates the bounds of the given item and creates a snapshot. This constructor is used to create an image of a complete spread, page or page item. Note that when itemUIDRef references a page (kPageBoss) a snapshot is made of the items on the spread that intersect the page bounds.

Parameters

itemUIDRef	- IN - The spread, page or page item to draw
xScaleFactor	- IN - X Scale
yScaleFactor	- IN - Y Scale
desiredRes	- IN - desired resolution of resulting snapshot
minRes	- IN - minimum resolution of resulting snapshot
bleedAmount	- IN - Extend the bounds of the area to be drawn by the given amount of bleed
colorSpace	- IN - The colorspace of the snapshot.
addTransparencyAlpha	- IN - kTrue to store transparency as an alpha channel, kFalse no alpha channel The alpha is a mask which identifies the non-transparent portions of the snapshot area – that is, the areas where page items are not. This alpha is usefull if for example this snapshot is to be used as a TIFF preview for an EPS. If you were to place the resulting EPS into InDesign, or even QuarkXPress, the transparent areas would be preserved when drawing in Proxy mode.
simulateOverprint	- IN - kTrue to simulate overprint, ie the equivalent of turning on overprint preview. Uses more memory and somewhat slower.

SnapshotUtilsEx::SnapshotUtilsEx	(	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,
		SSColorSpaceFamily	colorSpace = kCsRGB,
		bool8	addTransparencyAlpha = kFalse,
		bool8	simulateOverprint = kFalse
	)

Creates a snapshot of the parts of the given item that intersect the area specified by clippingBounds. This constructor is used to draw part of a spread, page or page item.

Parameters

clippingBounds	- IN - Bounding box in spread co-ordinates of the area to be drawn
itemUIDRef	- IN - The spread, page or page item to draw
xScaleFactor	- IN - X Scale
yScaleFactor	- IN - Y Scale
desiredRes	- IN - desired resolution of resulting snapshot
minRes	- IN - minimum resolution of resulting snapshot
bleedAmount	- IN - Extend the bounds of the area to be drawn by the given amount of bleed
colorSpace	- IN - The colorspace of the snapshot.
addTransparencyAlpha	- IN - kTrue to store transparency as an alpha channel, kFalse no alpha channel The alpha is a mask which identifies the non-transparent portions of the snapshot area – that is, the areas where page items are not. This alpha is usefull if for example this snapshot is to be used as a TIFF preview for an EPS. If you were to place the resulting EPS into InDesign, or even QuarkXPress, the transparent areas would be preserved when drawing in Proxy mode.
simulateOverprint	- IN - kTrue to simulate overprint, ie the equivalent of turning on overprint preview. Uses more memory and somewhat slower.

SnapshotUtilsEx::SnapshotUtilsEx	(	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,
		SSColorSpaceFamily	colorSpace = kCsRGB,
		bool8	addTransparencyAlpha = kFalse,
		bool8	simulateOverprint = kFalse
	)

Create a graphics context for the area specified by clippingBounds into which items from the given database will later be drawn by the caller. Only items that intersect the clippingBounds will be drawn.

Parameters

clippingBounds	- IN - Bounding box in spread co-ordinates of the area to be drawn
database	- IN - The database containing the items to be drawn
xScaleFactor	- IN - X Scale
yScaleFactor	- IN - Y Scale
desiredRes	- IN - desired resolution of resulting snapshot
minRes	- IN - minimum resolution of resulting snapshot
bleedAmount	- IN - Extend the bounds of the area to be drawn by the given amount of bleed
colorSpace	- IN - The colorspace of the snapshot.
addTransparencyAlpha	- IN - kTrue to store transparency as an alpha channel, kFalse no alpha channel The alpha is a mask which identifies the non-transparent portions of the snapshot area – that is, the areas where page items are not. This alpha is usefull if for example this snapshot is to be used as a TIFF preview for an EPS. If you were to place the resulting EPS into InDesign, or even QuarkXPress, the transparent areas would be preserved when drawing in Proxy mode.
simulateOverprint	- IN - kTrue to simulate overprint, ie the equivalent of turning on overprint preview. Uses more memory and somewhat slower.

virtual SnapshotUtilsEx::~SnapshotUtilsEx ( )

virtual

Destructor. Destroy the snapshot

Parameters

none

Returns

Member Function Documentation

AGMImageAccessor* SnapshotUtilsEx::CreateAGMImageAccessor

(

void

)

const

CreateAGMImageAccessor returns a pointer to an AGMImageAccessor which can be used to obtain information about the actual offscreen bitmap used to create the snapshot. The caller of this routine is responsible for calling 'delete' on the returned AGMImageAccessor. Note that this method will return nil if we are tiling due to not being able to hold an in-memory offscreen for the entire snapshot.

See Also

GetGraphicsContext.

AGMImageAccessor* SnapshotUtilsEx::CreateAlphaAGMImageAccessor

(

void

)

const

CreateAlphaAGMImageAccessor returns a greyscale representation of the transparency alpha generated during the snapshot. If the snapshot was constructed passing False for the 'addTransparencyAlpha' argument, then nil will be returned. If kXPOff is passed for the 'transparencyQuality' argument, then each pixel will be either 0 (black) or 255(white). The caller of this routine is responsible for calling 'delete' on the returned AGMImageAccessor. Note that this method will return nil if we are tiling due to not being able to hold an in-memory offscreen for the entire snapshot.

See Also

GetGraphicsContext.

ErrorCode SnapshotUtilsEx::Draw	(	int32	flags = IShape::kPreviewMode,
		bool32	fullResolutionGraphics = kFalse,
		const PMReal &	greekBelowPtSize = 7.0,
		bool32	enableAntiAliasing = kTrue,
		SnapshotUtils::Transparencies	transparencyQuality = SnapshotUtils::kXPHigh,
		IdleTimer *	abortCheck = nil,
		VPAttrMap *	pVPAttrMap = nil,
		bool32	bDrawNonPrintingObjects = kTrue
	)

Construct the bitmap using the arguments passed into the constructor and then draw using the drawing arguments passed to this routine. If a constructor containing a UIDRef was used, then the IShape implementation of that UIDRef will be asked to draw its hierarchy. That is, the UIDRef and its children will draw. If no UIDRef was used, then all page items intersecting the clippingBounds will be drawn.

Parameters

flags	- IN - Drawing flags (kPreviewMode suppresses drawing of margins and guides)
fullResolutionGraphics	- IN - kTrue forces images and graphics to draw at full resolution, kFalse to draw proxies
greekBelowPtSize	- IN - Point size at which text will be greeked if its points size multiplied by the scaling is less than the greek below value.
enableAntiAliasing	- IN - kTrue to anti-alias the drawing of all page items.
transparencyQuality	- IN - Controls the quality level of transparency effects such as drop shadows, feathers, and blending modes. Use kXPOff to disable transparency effects.
abortCheck	- IN - This argument is a callback which will be called before each page item is drawn. If you need to abort the generation of this snapshot because too much time has elapsed, there is a pending event that you want to handle, or any other reason, then pass in an IdleTimer. If the call to (*abortCheck)() equal zero, then the draw operation will be aborted and an error code of kCancel will be returned.

See Also

IIdleTask.h for the definition of IdleTimer.

Parameters

pVPAttrMap

- IN - This argument is a pointer to a map of view port attributes and values corresponding to them. If you want to control the content of the snapshot that gets drawn, you can pass a map of various viewport attributes class IDs (like kPrintBaselineGridsVPAttr, kPrintLayersVPAttr, or kXPFlattenerOffVPAttr) and their corresponding values. This function would iterate the various mappings and set the values corresponding to them in the view port attributes of the graphics port, before actually drawing on it.

bDrawNonPrintingObjects

- IN - If true, then page items marked as non-printing will draw. If false, non-printing page items will be ignored. This setting does not affect non-printing layers.

Returns

ErrorCode

ErrorCode SnapshotUtilsEx::Draw	(	UID	pageItem,
		int32	flags,
		bool32	fullResolutionGraphics,
		const PMReal &	greekBelowPtSize,
		bool32	enableAntiAliasing,
		SnapshotUtils::Transparencies	transparencyQuality,
		IdleTimer *	abortCheck = nil,
		VPAttrMap *	pVPAttrMap = nil,
		bool32	bDrawNonPrintingObjects = kTrue
	)

Construct the bitmap using the arguments passed into the constructor and then draw using the drawing arguments passed to this routine. Typically, this method is called when the constructor WITHOUT a UIDRef is used.

Parameters

pageItem	- IN - the page item to draw.
flags	- IN - Drawing flags (kPreviewMode suppresses drawing of margins and guides)
fullResolutionGraphics	- IN - kTrue forces images and graphics to draw at full resolution, kFalse to draw proxies
greekBelowPtSize	- IN - Point size at which text will be greeked if its points size multiplied by the scaling is less than the greek below value.
enableAntiAliasing	- IN - kTrue to anti-alias the drawing of all page items.
transparencyQuality	- IN - Controls the quality level of transparency effects such as drop shadows, feathers, and blending modes. Use kXPOff to disable transparency effects.
abortCheck	- IN - This argument is a callback which will be called before each page item is drawn. If you need to abort the generation of this snapshot because too much time has elapsed, there is a pending event that you want to handle, or any other reason, then pass in an IdleTimer. If the call to (*abortCheck)() equal zero, then the draw operation will be aborted and an error code of kCancel will be returned.

See Also

IIdleTask.h for the definition of IdleTimer.

Parameters

pVPAttrMap

- IN - This argument is a pointer to a map of view port attributes and values corresponding to them. If you want to control the content of the snapshot that gets drawn, you can pass a map of various viewport attributes class IDs (like kPrintBaselineGridsVPAttr, kPrintLayersVPAttr, or kXPFlattenerOffVPAttr) and their corresponding values. This function would iterate the various mappings and set the values corresponding to them in the view port attributes of the graphics port, before actually drawing on it.

bDrawNonPrintingObjects

- IN - If true, then page items marked as non-printing will draw. If false, non-printing page items will be ignored. This setting does not affect non-printing layers.

Returns

ErrorCode

ErrorCode SnapshotUtilsEx::ExportImage	(	ClassID	formatClass,
		IPMStream *	writeStream,
		bool8	colorMapped
	)

Exports the bitmap to a stream using the given image write format service (these filters are registered in the service registry under ServiceID==kImageWriteFormatService). USE ExportImageToJPEG, ExportImageToTIFF, ExportImageToPNG or ExportImageToGIF unless you have your own formatClass.

Parameters

formatClass	- IN - ClassID of the export format (e.g. kTIFFImageWriteFormatBoss, kJPEGImageWriteFormatBoss, kGIFImageWriteFormatBoss)
writeStream	- OUT - Stream to receive the bitmap data
colorMapped	- IN - kTrue to make the resulting image indexed, kFalse otherwise

Returns

ErrorCode

ErrorCode SnapshotUtilsEx::ExportImageToGIF	(	IPMStream *	writeStream,
		SnapshotUtils::PaletteType	paletteType = SnapshotUtils::kTryExactThenAdaptivePalette,
		bool8	interlaced = kFalse
	)

GIFs support transparency and are always indexed

Parameters

writeStream	- OUT - Stream to receive the bitmap data
paletteType	- IN - What kind of color palette do you want
interlaced	- IN - interlacing is usefull when an application needs to fade an image in while loading it but in general takes causes the reader to take longer to display the image.

Returns

ErrorCode

ErrorCode SnapshotUtilsEx::ExportImageToJPEG	(	IPMStream *	writeStream,
		SnapshotUtils::SSJPEGEncoding	encoding = SnapshotUtils::kSSJPEGBaseline,
		SnapshotUtils::SSJPEGQuality	quality = SnapshotUtils::kSSJPEGExcellentQuality,
		bool	embedColorProfile = false
	)

JPEG is very small and depending on the 'quality' setting can be very high quality. But it cannot be indexed and it does not support transparency.

Parameters

writeStream	- OUT - Stream to receive the bitmap data
encoding	- IN - JPEG encoding: kSSJPEGProgressive or kSSJPEGBaseline
quality	- IN - kSSJPEGLowQuality, kSSJPEGGoodQuality, kSSJPEGExcellentQuality, kSSJPEGGreatQuality
embedColorProfile	- IN - true to embed the color profile in the JPEG, false to strip it.

Returns

ErrorCode

ErrorCode SnapshotUtilsEx::ExportImageToPNG	(	IPMStream *	writeStream,
		uint32	compression = 5
	)

PNG supports transparency.

Parameters

writeStream	- OUT - Stream to receive the bitmap data
compression	- IN - Legal values are 0..9. Out of range values are (silently) clipped to a valid range.

Returns

ErrorCode

ErrorCode SnapshotUtilsEx::ExportImageToTIFF	(	IPMStream *	writeStream,
		SnapshotUtils::PaletteType	paletteType = SnapshotUtils::kNoPalette,
		bool	embedColorProfile = false
	)

Supports transparency

Parameters

writeStream	- OUT - Stream to receive the bitmap data
paletteType	- OUT - What kind of color palette do you want
embedColorProfile	- IN - true to embed the color profile in the JPEG, false to strip it.

Returns

ErrorCode

AGMGraphicsContext* SnapshotUtilsEx::GetGraphicsContext

(

void

)

const

The AGMGraphicsContext returned from GetGraphicsContext() can be used to obtain the Windows HDC or the Mac GrafPtr of the offscreen containing the offscreen bitmap. Note that this method will return nil if the offscreen will not fit into memory. SnapshotUtilsEx can still successfully create and export a snapshot even if it cannot hold the snapshot as an in-memory offscreen by tiling. That is, SnapshotUtilsEx will offscreen the snapshot in tiles and export each tile sequentially.