Copyright ã1995 by Netsurfer, Inc., All Rights Reserved.  

SurfDecoder 

Inherits From:	Object
Declared In:	SurfDecoder

Class Description
 
This class is an abstract superclass for all image decoders.  An image decoder need only implement those methods marked as the responsibility of the subclass.

Instance Variables
 
unsigned char verboseMode:1;
unsigned char lastCorrupt:1;
id returnImage;
NXWindowDepth imageDepth;
id <SurfErrorDelegate> errorDelegate;

verboseMode:1 	YES if verbosity enabled

lastCorrupt:1 	YES if last image corrupt

returnImage 	image eventually returned to caller

imageDepth 	target decoding depth

errorDelegate 	Error Delegate

Method Types
 
 Shared Instance 	+ sharedInstance

Filterable Type Query 	+ imageUnfilteredFileTypes
+ canLoadFromStream:

Designated Initializer 	- init

Decoding an Image 	- _decodeFromStream:
- decodeFromFile:
- decodeFromFile:intoImage:
- decodeFromStream:
- decodeFromStream:intoImage:

Set / Query 	- setImageDepth:
- imageDepth
- setLastImageCorrupt:
- lastImageCorrupt
- verboseMode
- setVerboseMode:
- setErrorDelegate:
- errorDelegate

Error Handling 	- spewMessage:withSeverity:

Class Methods
 
canLoadFromStream:
+ (BOOL)canLoadFromStream:(NXStream *)stream

Returns YES if an instance of the decoder class can decode the iamge contained in stream.  An implementation of this method should read the minnimum number of bytes necessary to determine if it can decode the stream.  The seek position in the stream must be preserved.  It is the responsibility of the subclass to implement this method!

imageUnfilteredFileTypes
+ (const char *const *)imageUnfilteredFileTypes

Returns a NULL terminated array of types (file extensions) that an instance of the decoder class can filter to TIFF.  It is the responsibility of the subclass to implement this method!

sharedInstance
+ sharedInstance

Returns an instance that can be shared throughout the application.  It is the responsibility of the subclass to implement this method!

Instance Methods
 
_decodeFromStream:
- _decodeFromStream:(NXStream *)theStream

This is the method that actually performs the decoding.  This method should never be called directly.

Upon entry, theStream has already been validated as a stream that contains an image that the image decoder can [potentially] decode.  The decoder should decode the image into an instance of some subclass of NXImageRep that is stored in the returnImage by using the -useRepresentation: method.

It is the responsibility of the subclass to implement this method!

decodeFromFile:
- decodeFromFile:(const char *)filePath

Decode image contained in filePath.  Returns an instance of NXImage containing the image data.  It is the caller's responsibility to dispose of the iamge object.  Returns nil if unable to decode filePath.  Note that this method may return an image if filePath is corrupt. 

decodeFromFile:intoImage:
- decodeFromFile:(const char *)filePath intoImage:image

Decode image contained in filePath into image.  Image should be an instance of NXImage.  If iamge is undefined, an instance of NXImage will be allocated.  It is the caller's responsibility to dispose of the iamge object.  Returns nil if unable to decode filePath.  Note that this method may return an image if filePath is corrupt. 

decodeFromStream:
- decodeFromStream:(NXStream *)stream

Decode image contained in stream.  Same behaviour as -decodeFromFile:

decodeFromStream:intoImage:
- decodeFromStream:(NXStream *)stream intoImage:image

Decode image contained in stream.  Same behaviour as -decodeFromFile:intoImage:

errorDelegate
- errorDelegate

returns the error delegate. 

imageDepth
- (NXWindowDepth) imageDepth

Returns the target decoding depth. 

init
- init

Designated initializer.  Disables verbose mode. 

lastImageCorrupt
- (BOOL) lastImageCorrupt

Returns YES if the last image decoded was corrupt. 

setErrorDelegate:
- (void) setErrorDelegate:(id <SurfErrorDelegate>)aDelegate

Sets the error delegate to aDelegate.  aDelegate will receive notification whenever the decoder generates an error message. 

setImageDepth:
- (void) setImageDepth:(NXWindowDepth)aDepth

Sets the decoding depth (imageDepth) to aDepth.  The decoder can use imageDepth to optimize the decoding process to the particular display device. 

setLastImageCorrupt:
- (void) setLastImageCorrupt:(BOOL)aFlag

This method should only be called by the decoder.  If is used to mark the last decoded image as being corrupt. 

setVerboseMode:
- (void) setVerboseMode:(BOOL)aFlag

Enables / disables verbose mode. 

spewMessage:withSeverity:
- (void) spewMessage:(const char *)errMsg withSeverity:(SurfErrorSeverity)aSeverity

This method should not be overridden.  It should be invoked whenever the decoder wishes to spew a message.  The message will be passed to the errorDelegate via the -decoder:spewMessage:withSeverity: method in the SurfErrorDelegate protocol. 

verboseMode
- (BOOL) verboseMode

Returns YES if verbose mode is enabled.  If verbose mode is enabled, the image decoder should dump notes about the decoding process.  For example, the GIF decoder dumps information about each step of the decoding process.  Useful for debugging purposes.