************************************************************************


FRENCH
------
DEEP est un format d'image standard au mme titre que l'ILBM. Nous vous
en rappelons ici la description officielle, agrmente de la desription
du format d'icne utilis par TVPaint 3.0 et Broadcast Painter. Cet
icne est aussi sauvegard dans le format IFF24.

Pourquoi le format DEEP ? Parce qu'il est STRUCTUR (description iff)
donc rapide et volutif (proprement). Il offre le mme encombrement que
le TGA avec un icne intgr en plus (et une volution propre garantie).  



ENGLISH
-------
Here is an offcial description of the DEEP file format, a standard,
compact and speedy format. See also the description of the saved-in
icon used by TVpaint 3.0 and Broadcast Painter. This icon is also
saved in the IFF24 format.

Why the DEEP ?  Because it is a STRUCTURED format (iff definition) so it
is fast and evolutionary (cleanly). Deep format offers the same size than
TGA with an integrated icon (and a clean evolution warranty).  



************************************************************************

QUELQUES CONCEPTS
-----------------
Un fichier IFF commence par les 4 lettres FORM, un MOT LONG (32 bits)
qui contient la taille de ce qui suit, 4 lettres d'identification du
type de format (ici DEEP), puis une srie de chunks. Cette entte permet
de reconnatre le format sans tenir compte des extension du nom du
fichier. Cette extension (.dip) doit tout de mme tre sauvegarde dans
le monde PC/Windows pour pallier  la gestion anarchique des autres
formats...

Le format IFF se compose de diffrents "chunk" qui contiennent chacun
des donnes particulires (palette, icne, informations, son, pixels...). 

Un chunk commence TOUJOURS par 4 caractres (lettres) d'identifications,
suivis d'un MOT LONG (32 bits) qui contient la taille des donnes sui-
vantes, suivi des donnes elles-mmes.

Le chunk suivant se trouve juste aprs, ALIGN SUR UN MOT SHORT (16 bits)

TOUTES les valeurs sont crites en BIG ENDIAN (valeur la plus
significative, octet de poids fort en premier).



SOME CONCEPTS
-------------
An IFF file begins with the 4 letters FORM, a LONG WORD (32 bits)
which contains the size of the following then 4 identification letters
of the format type (here it is DEEP) and then a series of chunks. This
heading enable to identify without taking in account the extension in
the file name. Unfortunately this extension (.dip) must be saved in the
PC/Windows world because of the lack of intelligent format...

The IFF format is composed with different chunks each contain specific
datas (color palette, icon, informations, sound, pixels...)

A chunk ALWAYS begins with 4 identification characters (letters),
then a LONG WORD (32 bits) which contain the size of the following datas,
then the datas themselves.

The next chunk is placed just after, ALIGNED ON A SHORT WORD (16 bits).

EVERY values are written in BIG ENDIAN mode (the most significant value
first).


************************************************************************

IFF FORM / CHUNK DESCRIPTION

Form / Chunk ID :	FORM  DEEP	( Deep pixels )
			Chunk DGBL	( Deep GloBaL information )
			Chunk DPEL	( Deep Pixel ELement )
			Chunk DLOC	( Deep display LOCation )
			Chunk DBOD	( Deep data BODy )
			Chunk DCHG	( Deep CHanGe buffer )

Date Submitted : March-91 / March 92


*****  FORM  ***********************************************************

FORM ID : 	DEEP		( DEEP pixels )

FORM purpose :
To allow faster loading and saving of images when pixels are stored in
consecutive memory locations and provide support for common extensions
implemented on advanced graphics cards.

FORM description :
This FORM is designed to provide support for a variety of deep pixels,
included 24 bits images. A deep pixel is one in which the pixel value
is used to directly produce the output colour without the use of a color
look-up table and also where the pixel stored in consecutive memory
locations. The format allows additional bits to be stored along with the
color bits to provide support for additional features such as masks,
Z-buffers, linear keys, etc.

The format is designed to allow different colour formats to be stored
such as RGB, RGBA, YCM and YCMB with varying depths supported. Bit
ordering will be most significant bit first.


*****  CHUNKS  *********************************************************



Chunk ID :	DGBL		( Deep GloBaL information )

Chunk purpose :
Provide global information of relevance to all the data contained in
the file. DGBL will always be the first chunk in the file.

Chunk description :
Used to provide information that is constant for all contents of the
file. One chunk is mandatory at the start of the file. When the file
is used to store a group of images it may, in  exceptional circum-
stances, be necessary to add additional DGBLchunks. The contents of
a DGBL chunk remain valid until anotherDGBL chunk is encountered.


*************************


Chunk ID :	DPEL		( Deep Pixel ELement )

Chunk purpose :
Defines the contents of each pixel. Enables the data content to be
identified and handled. Data that is unknown or not required can be
discared.

Chunk description :
This chunk is best described by an example :

    Original data = RGBA 8,8,8,4

	DPEL =	4		( number of elements )
			RED		( first element )
			8		( bits in element )
			GREEN	( second element )
			8		( bits in second element )
			BLUE		( third element )
			8		( bits in third element )
			ALPHA	( fourth element )
			4		( bits in fourth element )

	Stored data ( binary ) = rrrrrrrr gggggggg bbbbbbbb aaaa0000

Note : The pixel has been padded to the next byte boundary.


The element must be defined in the order in which they are stored,
with the most significant bit first.


*************************


Chunk ID :	DLOC		( Deep display LOCation )

Chunk purpose :
Provides information specific to the following DBOD section. Enables
image sections to be located within the screen areas individually and
allows images with a size different to DisplayWidth and DisplayHeight
to be stored.

Chunk description :
Specifies the width, height and where to place the following Deep data
BODy. If no DLOC is encountered before a DBOD, the DisplayWidth and
DisplayHeight parameters will be used as the DBOD image data dimensions.
The contents of a DLOC chunk remain valid until another DLOC chunk is
encountered.


*************************


Chunk ID :	DBOD		( Deep BODy )

Chunk purpose :
Contains the image data.

Chunk description :
Contains image data compressed by the method defined in DGBL. The image
size and the location where it is to be displayed is provided by a DLOC
 chunk. If no DLOC chunk has been read the data will be displayed in the
upper left corner and will be DisplayWidth wide and DisplayHeight high.


*************************


Chunk ID :	DCHG		( Deep CHanGe buffer )

Chunk purpose :
Informs the IFF reader that a complete frame has been read. Only required
when multiple images are stored for cell animation.

Chunk description :
When a chunk is encounter the IFF reader knows that a complete frame has
been read. The chunk gives the time, from the last frame change, before
the frame should be changed again. If the time has already elapsed the
frame should be changed immediatly. A FrameRate of 0 will cause the
frame changes to occur as fast as possible. A FrameRate of -1 is used to
indicate the end of the data for one frame and the start of the next in
cases where multiple frames are stored but are not intended for animation.
A DCHG chunk is not required when only a single frame is stored.


*************************


Chunk ID :	XS24		( eXtra Small 24 bit image )

Chunk purpose :
Contain a small image which is supposed to be an 24 bit icon of the
file.

Chunk description :
This icon is currently generated (and displayed) by TVPaint3 and Broadcast
Painter. The icon should have a maximum size of 64 pixels by 64 pixels.
When the creation of the image, it should be PROPORTIONALLY reduced to
enter in these dimensions: the biggest dimension (X or Y) of the image
should be equal to 64. 

The small image is NOT compressed. It is a raw format: RGBRGBRGB... with
ONLY RGB values.

Note: Because the Alpha value is not saved, the icon can be subtly
different from the real image. In TVPaint, we can display a color
in the background of the image to show the alpha transparencies. When
you save the image, the icon take this background color in account. But
if you reload the image the image without a background color the
transparent colors will appear black even if they appear blue or red
in the icon. That is why in our examples the icon has a dark blue
background when the image seems to have a black background.




*****  FORM DEEP  ********************************************************


// chunk DGBL
Struct DGBL = {
		UWORD	DisplayWidth, DisplayHeight;
//			size of source display

		UWORD	Compression;
//			type of compression

		UBYTE	xAspect, yAspect;
//			pixel aspect, a ratio w/h
		};



// chunk DPEL
Struct DPEL = {
		ULONG	nElements;
//			Number of pixel components
		Struct TypeDepth = {

// The TypeDepth structure is repeated times to  identify the content
// of every pixel. Pixels will always be padded to byte boundaries.
// The DBOD chunk will be padded to an even longword boundary.
					UWORD	cType;
//						type of data

					UWORD	cBitDepth;
//						Bit depth of this element
					} typedepth [ Nelements ];
		};



// chunk DLOC
struct DLOC = {

		UWORD	w,h;
//			Body width and height in pixels

		WORD	x,y;
//			Pixel position for this image
		};



// chunk DBOD
pixel ( 0 ), pixel ( 2 ), pixel ( 3 ),...  pixel ( w-1 ), 
pixel ( ((h-1)*w)),...   pixel(h*w-1)



// chunk DCHG
struct DCHG = {
		LONG		FrameRate;
//			Animation control when multiple images are stored
//			FrameRate - milliseconds between frames changes
		};



// chunk TVDC
struct TVDC = {
		WORD	Table[16];
		};


// chunk XS24
struct XS24 = {
		WORD	Width,Height;
		WORD	type; /* type MUST BE equal to 0 (zero) */
		};



Compressions currently defined :
	NOCOMPRESSION	=	0
	RUNLENGHT		=	1
	Reserved		=	2
	Reserved		=	3
	Reserved		=	4
	DELTA or TVDC	=	5
	Reserved		=	6
	Reserved		=	7


Ctype currently defined :
	RED		=	1
	GREEN	=	2
	BLUE	=	3
	ALPHA	=	4
	YELLOW	=	5
	CYAN	=	6
	MAGENTA	=	7
	BLACK	=	8
	MASK	=	9
	ZBUFFER	=	10
	OPACITY	=	11
	LINEARKEY	=	12
	Reserved	=	13
	Reserved	=	14
	Reserved	=	15
	Reserved	=	16
	DENSITY		=	17



*****  DEEP decompression routine  ************************************

Routine de dcompactage du format DEEP. Notez que la compression est
faite ligne  ligne pour chaque pixel.

Here is a decompression routine for the DEEP format. Note that the
compression is made LINE by LINE for each pixel.



UBYTE *DecodeDeep(UBYTE *source,Pixel *point,int size)
{
int	a,b;

	while(size>0)
	{

		a = *((BYTE*)source++);

		if(a == -128)
		{
			/* nothing */
		}
		else
		if(a>=0)
		{
			a = a + 1;
			memcpy(point,source,a*sizeof(Pixel));
			source += sizeof(Pixel)*a;
			point += a;
			size  -= a;
		}
		else
		{
			a = -a + 1;
			b=a;
			while(b--)
			{
				memcpy(point,source,sizeof(Pixel))
				source += sizeof(Pixel);
			}			
			point += a;
			size  -= a;
		}
	}

	return(source);
}


****************************************************************
****************************************************************

  **  **   **  *****   ****  *****  ******  ****  **  ** ******
  **  *** ***  ****** ****** ****** ****** ****** *** ** ******
  **  *******  **  ** **  ** **  **   **   **  ** ******   **  
  **  *******  ****** **  ** ******   **   **  ** ******   **  
  **  ** * **  *****  **  ** *****    **   ****** ** ***   **  
  **  **   **  **     **  ** **  **   **   ****** **  **   **  
  **  **   **  **     ****** **  **   **   **  ** **  **   **  
  **  **   **  **      ****  **  **   **   **  ** **  **   **  

****************************************************************
****************************************************************


LE MEILLEUR POUR LA FIN: GESTION DES COULEURS
---------------------------------------------

Ce paragraphe est TRS IMPORTANT (TRS TRS IMPORTANT), la
gestion des couleurs de TVPaint tant particulire.

Toutes les couleurs de TVPaint sont codes de manire  ce
que les valeurs RGB NE DPASSENT JAMAIS (JAMAIS) la valeur
de l'alpha.

   Un blanc opaque  100% est cod:      R=255 G=255 B=255 A=255
   Un blanc transparent  50% est cod:  R=128 G=128 B=128 A=128
   Un blanc transparent  10% est cod:  R=25  G=25  B=25  A=25

Avant d'utiliser de faire des calculs sur les couleurs, il
convient le plus souvent de CONVERTIR les couleurs en RGB
classique. De mme, APRS les calculs, pour sauver, IL FAUT
ABSOLUMENT convertir les couleurs de manire  ce que les
valeurs RGB ne dpassent pas la valeur Alpha.

   Red rel   = Red layer   * 255 / Alpha
   Blue rel  = Blue layer  * 255 / Alpha
   Green rel = Green layer * 255 / Alpha

   Red layer   = Red rel   * Alpha  / 255
   Blue layer  = Blue rel  * Alpha  / 255
   Green layer = Green rel * Alpha  / 255

Les valeurs RGB ne doivent JAMAIS DPASSER la valeur Alpha.
Dans le cas contraire, l'image est dtriore et les ractions
de TVPaint (notamment) deviennent instables. Les dveloppeurs
sont supposs savoir ce qu'ils font.


****************************************************************
****************************************************************

  **  **   **  *****   ****  *****  ******  ****  **  ** ******
  **  *** ***  ****** ****** ****** ****** ****** *** ** ******
  **  *******  **  ** **  ** **  **   **   **  ** ******   **  
  **  *******  ****** **  ** ******   **   **  ** ******   **  
  **  ** * **  *****  **  ** *****    **   ****** ** ***   **  
  **  **   **  **     **  ** **  **   **   ****** **  **   **  
  **  **   **  **     ****** **  **   **   **  ** **  **   **  
  **  **   **  **      ****  **  **   **   **  ** **  **   **  

****************************************************************
****************************************************************


LAST BUT NOT LEAST: COLOR CONTROL
---------------------------------

This chapter is VERY IMPORTANT (VERY VERY IMPORTANT), because
TVPaint uses specific rules to handle colors.

EVERY colors in TVPaint are coded with RGB values which are
never (NEVER) superior to the Alpha value.

   A 100% opaque white is coded:     R=255 G=255 B=255 A=255
   A 50% transparent white is coded: R=128 G=128 B=128 A=128
   A 10% transparent white is coded: R= 25 G= 25 B= 25 A= 25

BEFORE to work with colors, you (usually) have to CONVERT
these colors in classic RGB. In the same way, AFTER the work,
to save the image, you ABSOLUTELY MUST convert these colors
so as to have RGB values not superior to the Alpha value. 

   Real Red   = Red   in layer * 255 / Alpha
   Real Blue  = Blue  in layer * 255 / Alpha
   Real Green = Green in layer * 255 / Alpha

   Red   in layer = Real Red   * Alpha  / 255
   Blue  in layer = Real Blue  * Alpha  / 255
   Green in layer = Real Green * Alpha  / 255

The RGB values must NEVER be superior to the Alpha value.
If they are, the working image is altered and the reactions of
TVPaint are OUT OF CONTROL. Developpers are supposed to know
what they do. 


****************************************************************
****************************************************************


