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

SurfImageDecoder 

Inherits From:	Object
Declared In:	SurfImageDecoder.h

Class Description
 
A controller for image decoding.  This class implements a generic image decoder that can be used to decde any of a number of different image formats depending on what decoder classes have been registered with the instance.

Given an arbitrary path or stream, an instance of SurfImageDecoder will determine the type of the image, attempt to decode it, and, upon success, will return an instance of NXImage containing the decoded image.

Instances are designed to be used in a multi-threaded context.  Any instance can be decoding image in any thread of execution while other instances are simultaneously decoding images.  A single instance cannot decode multiple images from different threads; to attempt this guarantees catastrophic failure of the environment.

Registrering Custom Decoders

A class can register to be a potential decoder by calling SurfImageDecoder's -addDecoderClass: method.  When instantiated, an instance of SurfImageDecoder automatically registers the SurfGIFDecoder and SurfJPEGDecoder classes.

How Image Formats Are Determined

The -loadFromStream:... family of methods determines the contents of the stream by calling +canLoadFromStream:} within each potentially eligible decoder's class.  The first decoder to return YES decodes the stream.

-loadFromFile:... and friends try to determine the image type by looking up the file's extension in the decoderByType HashTable.  If not found, the stream is mapped into memory and passed to -loadFromStream:....

Note: the -lastImageCorrupt method assumes that the last decoder used still exists and is still viable; ie: don't call -lastImageCorrupt if you are using external decoders that may have been freed between the time an image decoding attempt was made and the time that -lastImageCorrupt is called!.

Instance Variables
 
HashTable *decoderClassByType;
HashTable *decoderByType;
List *decoderList;
NXWindowDepth imageDepth;
id <SurfErrorDelegate> errorDelegate;

decoderClassByType 	decoder classes hashed by type

decoderByType 	decoders hashed by type

decoderList 	list of all decoders

imageDepth 	target decoding depth

errorDelegate 	Error Delegate

Method Types
 
 Existance Methods 	+ sharedInstance
- init
- free

Image Type Management 	- imageUnfilteredFileTypes
- canLoadFromStream:
- dumpTypes

Decoder Management 	- decoderForType:
- decoderClassForType:
- decoderForStream:
- decoderClassForStream:
- addDecoderClass:

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

Configuration 	- setImageDepth:
- imageDepth

State Inspection 	- lastImageCorrupt
- decoderList
- decoderByType
- decoderClassByType
- verboseMode
- setVerboseMode:

Error Handling 	- setSpewToStderr:
- spewToStderr
- setErrorDelegate:
- errorDelegate

Debugging 	- printForDebugger:

Class Methods
 
sharedInstance
+ sharedInstance

Returns the shared instance of SurfImageDecoder.  Should only be used in applications that require a single image decoder. 

Instance Methods
 
addDecoderClass:
- addDecoderClass:aClass

Adds aClass as a possible decoder.  This is accomplished by retrieving the types accepted by the decoder class by calling +imageUnfilteredFileTypes.  The returned types are appended to the list of types that can be converted by this image converter object.  An instance of the class is allocated and an entry is created in hashedExtensions for each type the decoder can decode.  If a decoder that can decode that particular type already exists in hashedExtensions, it is replaced (but not freed). 

canLoadFromStream:
- (BOOL)canLoadFromStream:(NXStream *)aStream

Returns YES if the decoder thinks it can decode the data in aStream.  This forwards aStream to each specific format decoding class, if any return YES, this method immediately returns YES.

The current position in the stream is unchanged. 

decodeFromFile:
- decodeFromFile:(const char *)filePath

Attempts to decode the data in filePath as an image.  Uses the filePath's extension to determine the image type.  If it fails to find a decoder given the filePath's extension, the method maps the filePath and calls -decodeFromStream:} in hopes that one of the image decoders will decide it can decode the stream contents.

Returns the decoded image upon success and nil upon failure.  This methdo is a cover for -decodeFromFile:intoImage:withDecoder:

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

Attempts to decode the contents of filePath in the same fashion as -decodeFromFile:.  Instead of allocating an instance of NXImage, this method will append the newly decoded image in an NXBitmapImageRep using the -useRepresentation: method.

Returns the decoded image upon success or nil upon failure.  This methdo is a cover for -decodeFromFile:intoImage:withDecoder:

decodeFromFile:intoImage:withDecoder:
- decodeFromFile:(const char *)filePath intoImage:anImage withDecoder:aDecoder

Attempts to decode the contents of filePath using aDecoder.  If anImage is defined, the decoded representation will be appended to anImage using the -useRepresentation: method.  If aDecoder is not defined, the method will try to identify the decoder to be used from filePath's extension.  If that fails, this method will map the file and pass control -decodeFromStream:....

Returns the decoded image upon success or nil upon failure. 

decodeFromStream:
- decodeFromStream:(NXStream *)aStream

This method is a cover for -decodeFromStream:intoImage:withDecoder:. 

decodeFromStream:intoImage:
- decodeFromStream:(NXStream *)aStream intoImage:anImage

This method is a cover for -decodeFromStream:intoImage:withDecoder:. 

decodeFromStream:intoImage:withDecoder:
- decodeFromStream:(NXStream *)aStream intoImage:anImage withDecoder:aDecoder

Decodes the contents of aStream into the image anImage using the decoder aDecoder.  If anImage is defined, the decoded image will be appended using the -useRepresentation: method.  If aDecoder is not defined, this method determines the decoder using the -decoderForStream: method.

Returns the decoded image upon success, or nil upon failure. 

decoderByType
- decoderByType

Returns the decoderByType HashTable. 

decoderClassByType
- decoderClassByType

Returns the decoderClassByType HashTable. 

decoderClassForStream:
- (Class) decoderClassForStream:(NXStream *)aStream

Returns the decoder Class used to decode aStream.  If no class is available, returns nil. 

decoderClassForType:
- (Class) decoderClassForType:(const char *)imageType

Returns the decoder class for images of type imageType.  This can be used to customize the particular image decoder. 

decoderForStream:
- decoderForStream:(NXStream *)aStream

Returns the decoder object that should be used to decode aStream.  If an appropriate decoder object is not available, returns nil. 

decoderForType:
- decoderForType:(const char *)imageType

Returns the decoder for images of type imageType.  This can be used to customize the particular image decoder. 

decoderList
- decoderList

Returns the decoderList List. 

dumpTypes
- (void) dumpTypes

Pretty-prints file extensions to stderr. 

errorDelegate
- errorDelegate

Returns the image decoder's error delegate. 

free
- free

Frees the image decoder and all specific type decoders. 

imageDepth
- (NXWindowDepth) imageDepth

Returns imageDepth. 

imageUnfilteredFileTypes
- (const char *const *)imageUnfilteredFileTypes

Returns NULL terminated array of strings containing all of the image types an instance of SurfImageDecoder can decode. 

init
- init

Designated intializer.  Creates entries in decoderByType for each decoder type, but does not allocate/initialize any decoders. 

lastImageCorrupt
- (BOOL) lastImageCorrupt

Returns YES if last the image that was decoded contained some kind of error. 

printForDebugger:
- (void)printForDebugger:(NXStream *)aStream

Prints a summary of the decoders state to aStream. 

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

Sets the error delegate to aDelegate.  aDelegate's implementation of -decoder:spewMessage:withSeverity: will be invoked whenever a decoder generates an error message. 

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

Sets the target image depth to aDepth.  Some of the image decoders can optimize the decoding process to a specific depth.  This method will propagate aDepth to all decoders using the setImageDepth method; whether or not a decoder can actually decode to that depth is entirely up to the decoder.

Generally, image decoders default to producing 24-bit deep images. 

setSpewToStderr:
- (void) setSpewToStderr:(BOOL)aFlag

If aFlag is YES, error messages geneerated by decoders will be printed via NXLogError(). 

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

Enabled/disables verbose mode.  Verbose mode spews a HUGE quantity of state information to stderr. 

spewToStderr
- (BOOL) spewToStderr

Returns YES if error messages will be printed to the console/stderr. 

verboseMode
- (BOOL) verboseMode

Returns YES if verbose mode is enabled.