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

SurfGIFDecoder 

Inherits From:	SurfDecoder
Declared In:	SurfGIFSupport.subproj/SurfGIFDecoder

Class Description
 
This class encapsulates all state necessary to decode a particular GIF stream into an instance of NXImage.  The instance of NXImage may contain multiple NXBitmapImageReps-- each one containing one of the images decoded from the GIF stream.  This level of abstraction [a class encapsulating the decoder] is necessary to fully support the features of GIF in a manner compatible with NXImage and also support the move to a threaded environment.

The GIF specification defines more than an image encapsulation schema; the decoder must be able to "remember" some state between decoding images.  For example, a valid GIF stream is one that contains nothing but a Global Color Table -- as well, a valid GIF stream is one that doesn't contain any Color Tables at all; when encountered, it effectively inherits the color table used to decode the last image [hence the usefulness of a stream that is nothing but a color table].

Instance Variables
 
unsigned char showColorTable:1;
unsigned char produceSilhouette:1;
unsigned char gctZeroUnused:1;
unsigned char gctPresent:1;
unsigned char gctSorted:1;
unsigned char gcePresent:1;
unsigned char gceUseTransparency:1;
unsigned char lctPresent:1;
unsigned char lctSorted:1;
unsigned char idInterlaced:1;
char version[4];
unsigned char gceTransparentColorIndex;
unsigned short lsdWidth;
unsigned short lsdHeight;
unsigned char lsdColorResolution;
unsigned short lsdGlobalColorTableSize;
unsigned char lsdBackgroundIndex;
unsigned char globalColorTable[GCT_MAX_BYTES];
unsigned short idX;
unsigned short idY;
unsigned short idWidth;
unsigned short idHeight;
unsigned char *localColorTable;
LWZState *decompressionState;

showColorTable:1 	dump color table?

produceSilhouette:1 	produce silhouette?

gctZeroUnused:1 	zero unspecified bytes?

gctPresent:1 	gct present in stream?

gctSorted:1 	gct sorted most to least significant?

gcePresent:1 	graphic control extension?

gceUseTransparency:1 	image has transparency?

lctPresent:1 	local color table?

lctSorted:1 	local color table sorted?

idInterlaced:1 	interlaced iamge?

version[4] 	GIF stream version; typically "87a" or "89a".

gceTransparentColorIndex 	transparent color

lsdWidth 	logical screen width

lsdHeight 	logical screen height

lsdColorResolution 	logical screen resolution

lsdGlobalColorTableSize 	ls table size

lsdBackgroundIndex 	ls background color index

globalColorTable[GCT_MAX_BYTES] 	color table

idX 	local image descriptor X location

idY 	local image descriptor Y location

idWidth 	local image descriptor width

idHeight 	local image descriptor height "/ unsigned char lctSize;/*" local color table size

localColorTable 	local color table

decompressionState 	LWZ decompression engine

Method Types
 
 Instantiation 	+ sharedInstance

Class query 	+ imageUnfilteredFileTypes
+ canLoadFromStream:

Custom GIF Features 	- produceSilhouette
- setProduceSilhouette:
- gctZeroUnused
- setGctZeroUnused:
- setShowColorTable:
- showColorTable

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

Returns YES if the first few bytes of stream indicate an image that an instance of this decoder can likely decode successfully. 

imageUnfilteredFileTypes
+ (const char *const *)imageUnfilteredFileTypes

Returns a NULL terminated array of file extensions that this decoder class can decode. 

sharedInstance
+ sharedInstance

This method is provided for convenience and should only be used in a single-threaded conversion environment.  In a multiple threaded environment, it is much safer to not use this method and to manage the multiple iinstances using the normal alloc/init/free paradigm. 

Instance Methods
 
gctZeroUnused
- (BOOL) gctZeroUnused

Returns YES if the decoder will zero all unused global color table entries beyond the last entry for the current image.  Basically, this ensures that if the image references an entry in the color table beyond the color table size (since the global color table is large enough to hold the maximum sized color table, overrunning the current global color table size CANOT cause a memory exception), the resulting pixel will be black. 

produceSilhouette
- (BOOL) produceSilhouette

Returns YES if decoder will produce a silhouette of the image.  A silhuette is transparent wherever the gif is transparent and is solid white wherever the image is non-transparent. 

setGctZeroUnused:
- (void) setGctZeroUnused:(BOOL)aFlag

Enables/disables zeroing of unused global color table entries.

see -gctZeroUnused. 

setProduceSilhouette:
- (void) setProduceSilhouette:(BOOL)aFlag

Enables/disables silhouette mode.

see -produceSilhouette. 

setShowColorTable:
- (void) setShowColorTable:(BOOL)aFlag

If enabled, each color table will be printed in ASCII form to stderr. 

showColorTable
- (BOOL) showColorTable

Returns YES if each decoded color table is printed to stderr.