@DATABASE "Pictures"
@AUTHOR "Paul Manias"
@NODE "Main" "Pictures Documentation"

Name:         @{"PICTURES" LINK "Functions"} AUTODOC
Version:      0.7 Beta.
Date:         7 July 1997
Author:       Paul Manias
Copyright:    DreamWorld Productions, 1996-1997.  All rights reserved.
Notes:        This  document is still being written and will contain errors
              in  a  number  of  places.   The information within cannot be
	      treated as official until this autodoc reaches version 1.0.

@EndNode
---------------------------------------------------------------------------
@NODE "Functions" "Picture Functions"

 @{b}PICTURE INTERFACE@{ub}
 @{"GetPicInfo()"  LINK "GetPicInfo()"}
 @{"GetPicture()"  LINK "GetPicture()"}
 @{"LoadPic()"     LINK "LoadPic()"}
 @{"LoadPicFile()" LINK "LoadPicFile()"}
 @{"UnpackPic()"   LINK "UnpackPic()"}

 @{b}STRUCTURES@{ub}
 @{"Picture" LINK "Picture"}

@EndNode
---------------------------------------------------------------------------
@NODE  "Picture" "Structure: Picture"

Name:    Picture
Version: 1
ID Code: PC
Type:    Simple

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  purpose  of  the  Picture structure is to provide a standard interface
that  any GMS program can use to load a picture.  The advantage is that the
source  picture  can  be in any file format currently recognised by GMS, so
effectively  the  program  in question will be able to support file formats
that it does not immediately recognise.

Some functions using Pictures are:

	GetPicture()
	GetPicInfo()
	LoadPic()
	UnpackPic()

@{b}@{u}STRUCTURE@{uu}@{ub}
The Picture structure consists of the following public fields:

	@{"AmtColours" LINK "PIC_AmtColours"} Amount of colours.
	@{"ByteWidth " LINK "PIC_ByteWidth" } Picture Width (bytes)
	@{"Data      " LINK "PIC_Data"      } Source of actual picture data.
	@{"File      " LINK "PIC_File"      } Where this picture comes from.
	@{"Height    " LINK "PIC_Height"    } Picture Height (pixels)
	@{"Options   " LINK "PIC_Options"   } Special flags.
	@{"Palette   " LINK "PIC_Palette"   } Pointer to Palette.
	@{"Planes    " LINK "PIC_Planes"    } Amount of planes.
	@{"ScrHeight " LINK "PIC_ScrHeight" } Screen Height (pixels)
	@{"ScrMode   " LINK "PIC_ScrMode"   } Intended screen mode for picture.
	@{"ScrType   " LINK "PIC_ScrType"   } ILBM / CHUNKY8 / PLANAR ...
	@{"ScrWidth  " LINK "PIC_ScrWidth"  } Screen Width (pixels)
	@{"Width     " LINK "PIC_Width"     } Picture Width (pixels)

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Data" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Data
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: Allocated on initialisation.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Pointer  to  the picture's data destination for the unpack.  If you specify
NULL here, a buffer will be allocated and placed here for you.  The size is
determined by the calcuation ByteWidth*Height*Depth.

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Width" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Width
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      
Inheritance: Source picture.

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  width  of the picture in pixels.  Note that the source picture will be
clipped  if  it  exceeds  a  given  width  boundary, unless you specify the
RESIZEX flag.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"Height" LINK "PIC_Height"}, @{"ByteWidth" LINK "PIC_ByteWidth"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_ByteWidth" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        ByteWidth
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read only.
Inheritance: Width

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  width of the picture in bytes.  This field can only be written to from
a  picture  initialisation  function,  so  do  not  attempt  to  specify it
yourself.   This  value  of  ByteWidth  is  highly dependent on the ScrType
field.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"Width" LINK "PIC_Width"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Height" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Height
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: Source picture.

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  height  of the picture in pixels.  This field will be initialised if a
height  is  not  given  here.   Note that the picture will be clipped if it
exceeds the height boundary.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"Width" LINK "PIC_Width"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Planes" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Planes
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: Source picture.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies the amount of planes in this picture.  Generally you should avoid
setting  this  field as much as possible and use AmtColours instead.  Since
it  only  applies  to  planar and interleaved screen types, you can see the
danger in specifying this field only to have a user default in ScrType give
you a chunky based screen.

Note  that  the  source picture would lose planes if it exceeds this value,
unless REMAP is also specified.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"ScrType" LINK "PIC_ScrType"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_AmtColours" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        AmtColours
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: Source picture.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies the amount of colours available in the picture and the palette.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"Palette" LINK "PIC_Palette"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Palette" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Palette
On Change:   Dynamic.
Structure:   Picture
Status:      Read/Write
Inheritance: Source picture.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Points  to  a  palette if you want to use the REMAP option.  On the
other hand if you specify the GETPALETTE option, then the picture's
palette will calculated and placed in here.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"AmtColours" LINK "PIC_AmtColours"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_ScrMode" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        ScrMode
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: Source picture.

@{b}@{u}DESCRIPTION@{uu}@{ub}
The screen mode that this picture is being loaded into.  Applicable flags
are outlined in GameScreen->ScrMode (LORES, HIRES, SHIRES, LACED etc).

@{b}@{u}SEE ALSO@{uu}@{ub}
GameScreen->ScrMode

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_ScrType" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        ScrType
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: User default.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies  the  data  type  of  this  picture,  eg  PLANAR.   If you omit a
specification  in this field, the function will initialise it to the user's
preferred screen type.

@{b}@{u}SEE ALSO@{uu}@{ub}
GameScreen->ScrType

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Options" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Options
On Change:   Cannot change after initialisation.
Structure:   Picture
Status:      Read/IWrite
Inheritance: None.

@{b}@{u}DESCRIPTION@{uu}@{ub}
You  can specify certain flags here that will affect the way the picture is
initialised.  Valid flags are:

  @{u}GETPALETTE@{uu}
  Gets the palette of the picture and generates a copy of the colour values
  in  the  24 bit colour $RRGGBB format.  The amount of colours obtained is
  dependent  on  the PIC_AmtColours field.  If you specify 0 in that field,
  all  the  colours  will  be obtained.  If the picture is stored as a true
  colour type, this flag will be ignored.

  @{u}REMAP@{uu}
  Remaps  the picture data to fit the palette pointed to in the PIC_Palette
  field.  If the picture is stored as a true colour type, this flag will be
  ignored.

  @{u}VIDEOMEM@{uu}
  Allocates video memory that is displayable on screen.

  @{u}RESIZEX@{uu}
  Resizes  the  picture  so that it fits the given Picture->Width.  If this
  flag is not set then the picture will be clipped.

  @{u}RESIZEY@{uu}
  Resizes  the  picture so that it fits the given Picture->Height.  If this
  flag is not set then the picture will be clipped.

  @{u}RESIZE@{uu}
  Short way of setting the RESIZEX and RESIZEY flags, above.

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_File" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        File
On Change:   Dynamic
Structure:   Picture
Status:      Read/IWrite
Inheritance: None

@{b}@{u}DESCRIPTION@{uu}@{ub}
Pointer  to  a  NULL terminated string, that contains the filename for this
picture, eg "HD1:Pictures/MyPicture.iff".

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_ScrWidth" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        ScrWidth
On Change:   Dynamic
Structure:   Picture
Status:      Read/Write
Inheritance: Source picture (if possible) or estimate based on resolution.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies  the  width  of  the screen/viewport when displaying the picture.
Some  picture file formats may not contain a suitable value to be placed in
this  field.   In this case, the field will be initialised to a value based
on the pictures resolution.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"ScrHeight" LINK "PIC_ScrHeight"}

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_ScrHeight" "Structure: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:        ScrHeight
On Change:   Dynamic
Structure:   Picture
Status:      Read/Write
Inheritance: Source picture (if possible) or estimate based on resolution.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies  the  height  of the screen/viewport when displaying the picture.
Some  picture file formats may not contain a suitable value to be placed in
this  field.   In this case, the field will be initialised to a value based
on the pictures resolution.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"ScrWidth" LINK "PIC_ScrWidth"}

@EndNode
---------------------------------------------------------------------------
@NODE "LoadPic()" "Pictures/LoadPic"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      LoadPic()
Short:     Load in a recognised picture file.
Assembler: Picture = LoadPic(APTR [a1])
C/C++:     struct Picture * LoadPic(struct Picture *)
           struct Picture * LoadPicTags(unsigned long ...)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Loads  in a picture file (PIC_File), and if the picture type is recognised,
unpacks  the  data  to  a buffer given in PIC_Data.  If you do not supply a
data  destination,  then  a  buffer will be allocated for you and placed in
PIC_Data.

LoadPic()  has  all the standard features of GMS functions, including field
initialisation  for  NULL  fields.  Note that by setting certain fields you
are placing restrictions on the picture that is to be loaded.  For example,
if  the  picture  is bigger then the specified width, the picture will have
its  right  edge  clipped.  To get around this simply leave the Width field
unspecified,  and LoadPic() will initialise this field, loading the picture
without  clipping  it.   Alternatively  you  could specify the RESIZE flag,
depending on the circumstances.

Make  sure  that  you  call FreePic() on the Picture once you have finished
with it.

@{b}@{u}NOTE@{uu}@{ub}
If  this  function  cannot  identify  the source header, then the call will
fail.   Currently the only supported format is IFF, but GIF, JPEG and other
picture  format  support  will  be  added later (someone please send me the
info!)

@{b}@{u}INPUT@{uu}@{ub}
APTR - Pointer to a Picture structure or tag list.

@{b}@{u}RESULT@{uu}@{ub}
Picture - Pointer to a picture structure, NULL if error.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"UnpackPic" LINK "UnpackPic()"}, @{"FreePic" LINK "FreePic()"}, @{"games/image.i" LINK "games/image.i/Main"}

@EndNode
---------------------------------------------------------------------------
@NODE "UnpackPic()" "Pictures/UnpackPic"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      UnpackPic()
Short:     Unpacks a picture to a designated buffer.
Assembler: ErrorCode = UnpackPic(Source [a0], Picture [a1])
C/C++:     LONG UnpackPic(APTR Source, struct Picture *)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Unpacks  the  data  contained  in  a  recognised picture header to the data
destination  given  in  PIC_Data.  If you do not supply a data destination,
then a buffer will be allocated for you and placed in PIC_Data.

If  this  function  cannot  identify  the source header, then the call will
fail.   The  standard expected format is IFF, but GIF and JPEG support will
be added (for benefit of the user) later.

@{b}@{u}INPUT@{uu}@{ub}
Source  - Pointer to the header of the picture source.
Picture - Pointer to a Picture structure.

@{b}@{u}RESULT@{uu}@{ub}
ErrorCode - Returns NULL if successful.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"LoadPic" LINK "LoadPic()"}, @{"FreePic" LINK "FreePic()"}, @{"games/image.i" LINK "games/image.i/Main"}

@EndNode
---------------------------------------------------------------------------
@NODE "GetPicInfo()" "Pictures/GetPicInfo"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GetPicInfo()
Short:     Get the information on a recognised picture type.
Assembler: ErrorCode = GetPicInfo(Picture [a1])
C/C++:     LONG GetPicInfo(struct Picture *)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  will  load  a  picture's  information  header (unless it is
already  present  in  PIC_Header), and then fills out the Picture structure
according  to  the  information that it finds.  Only fields that are set to
NULL will be initialised, so preset fields will not be affected.

You will need to use some special options provided by the PIC_Options field
to  get  certain  information.   GETPALETTE  will  write  out the picture's
palette  data  to the address in PIC_Palette.  If PIC_Palette is empty then
the correct amount of memory will be allocated and placed in this field for
you.

By  using  this  function  you  can  find information on any picture format
currently supported by GMS.  If the picture format cannot be assessed, then
an error code of ERR_DATA will be returned.

@{b}@{u}NOTE@{uu}@{ub}
You  will  have  to  call  FreePic()  if  any  memory  was allocated by the
GetPicInfo()  function (eg if GETPALETTE was specified without a pointer in
PIC_Palette).

@{b}@{u}INPUT@{uu}@{ub}
Picture - Pointer to a Picture structure.

@{b}@{u}RESULT@{uu}@{ub}
ErrorCode - Returns NULL if successful.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"LoadPic" LINK "Master.guide/LoadPic()"}

@EndNode
-----------------------------------------------------------------------------
@NODE "GetPicture()" "Pictures/GetPicture"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GetPicture()
Short:     Gets the latest version of the picture structure.
Assembler: Picture = GetPicture()
C/C++:     struct Picture * GetPicture(void);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Allocates the latest version of a GMS picture structure and returns it back
to  you.   The structure fields will be empty so that you can fill them out
to suit your requirements.  Before your program exits you will need to free
the structure with the FreePic() function.

You  have  to  use  this  function  if  you do not want to use tag lists to
initialise  your  pictures  (remember that it is illegal to compile and use
pre-initialised structures in GMS programs).

@{b}@{u}RESULT@{uu}@{ub}
Picture - Points to the latest version of a GMS picture structure or NULL
          if failure.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"GetStructure" LINK "GetStructure()"}

@EndNode
-----------------------------------------------------------------------------
@NODE "LoadPicFile()" "Pictures/LoadPicFile"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      LoadPicFile()
Short:     Load in picture file.
Assembler: Picture = LoadPicFile(Filename [a1], Flags [d0])
C/C++:     struct Picture * LoadPicFile(BYTE *Filename, LONG Flags)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  is  provided  as  a  quick and simple way of loading in any
picture,  without the need of structures or tags.  It converts the Filename
and  Flags  arguments  to  a tag list which it passes on to LoadPic().  You
will be returned a Picture structure if the call is successful.

At  some  point  you will have to call FreePic(), which frees the allocated
structure,  the  loaded  picture data and any extra allocations such as the
palette.

@{b}@{u}INPUT@{uu}@{ub}
Filename - Pointer to the file (picture) to load.
Flags    - Flags valid for use in the PIC_Options field.

@{b}@{u}RESULT@{uu}@{ub}
Picture - Points to a newly allocated Picture structure.  NULL if
	  unsuccessful.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"LoadPic" LINK "LoadPic()"}

@EndNode
-----------------------------------------------------------------------------