@DATABASE "Pictures"
@AUTHOR   "Paul Manias"
@NODE     "Main" "Object: Picture"

@{b}@{u}OBJECT DOCUMENTATION@{uu}@{ub}
Name:      @{"PICTURE" LINK "Description"}
Version:   1.0
Date:      May 1998
Author:    Paul Manias
Copyright: DreamWorld Productions, 1996-1998.  All rights reserved.

@{b}@{u}CHANGES VERSION 1.0@{uu}@{ub}
Added:    SaveToFile()

Edited:   Picture->Load()
          Picture->Init()
          Picture->Query()
          Picture->Source
          Picture->Options
          Introduction

Removed:  Picture->Palette

A very important change is that Load() no longer loads pictures into
video ram.  You have to Copy() picture bitmaps into Screens now.

@{b}@{u}CHANGES VERSION 0.9B@{uu}@{ub}
Added:    Picture->Bitmap

Removed:  Picture->AmtColours
          Picture->ByteWidth
          Picture->Data
          Picture->Height
          Picture->Planes
          Picture->Width
          Picture->ScrType
          Picture->Options: IMG_BLITMEM, IMG_VIDEOMEM

Edited:   Description
          Picture->Palette
          Picture->Options

@EndNode
---------------------------------------------------------------------------
@NODE "Description" "Object: Picture"

@{b}@{u}OBJECT@{uu}@{ub}
Name:     Picture
Version:  1
ID:       ID_PICTURE
Module:   Picture
Include:  @{"graphics/picture.h" LINK "GMSDev:Includes/graphics/pictures.h/Main"}
Type:     Simple
Children: Bitmap

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  purpose  of the Picture object is to provide a standard interface that
any program can use to load a picture file.  The main advantage is that the
source  picture  can  be  in  any  file  format currently recognised by the
system, so effectively the program in question will be able to support file
formats  that  it  does not understand.  The default picture format is IFF,
the other formats (such as JPEG) can be added with 3rd party support.

The  Picture  object  will clip any loaded picture so that it fits the size
given in Bitmap->Width and Bitmap->Height.  If you specify the RESIZE flag,
the picture will be shrunk or enlarged to fit the given dimensions.  If you
leave  the Width and Height at NULL, then the picture will be loaded at its
default dimensions.

Images   are  also  remapped  auto-magically  if  the  source  palette  and
destination palettes do not match.

@{b}@{u}ACTIONS@{uu}@{ub}
The Picture object supports the following actions:

     @{"CopyStructure()" LINK "GMSDev:AutoDocs/Kernel.guide/CopyStructure()"} - Copy Picture details to another object.
     @{"Free()" LINK "GMSDev:AutoDocs/Kernel.guide/Free()"}          - Free a Picture object.
     @{"Get()" LINK "GMSDev:AutoDocs/Kernel.guide/Get()"}           - Get a new Picture object.
   * @{"Init()" LINK "Picture_Init()"}          - Initialise a Picture.
   * @{"Load()" LINK "Picture_Load()"}          - Load a picture file.
   * @{"Query()" LINK "Picture_Query()"}         - Just load the information of a Picture.
     @{"Read()" LINK "GMSDev:AutoDocs/Kernel.guide/Read()"}          - Read from the Bitmap data.
     @{"SaveToFile()" LINK "GMSDev:AutoDocs/Kernel.guide/SaveToFile()"}    - Save a Picture to a File.
     @{"Seek()" LINK "GMSDev:AutoDocs/Kernel.guide/Seek()"}          - Seek to a position for Read/Write.
     @{"Write()" LINK "GMSDev:AutoDocs/Kernel.guide/Write()"}         - Write to the Bitmap data.

@{b}@{u}STRUCTURE@{uu}@{ub}
The Picture object consists of the following public fields, plus all fields
inherited from the Bitmap object:

   + @{"Bitmap" LINK "GMSDev:AutoDocs/Objects/Bitmap.guide/Description"}    - Bitmap child object.
     @{"Options" LINK "PIC_Options"}   - Special flags.
     @{"ScrHeight" LINK "PIC_ScrHeight"} - Screen Height (pixels)
     @{"ScrMode" LINK "PIC_ScrMode"}   - Intended screen mode for picture.
     @{"ScrWidth" LINK "PIC_ScrWidth"}  - Screen Width (pixels)
     @{"Source" LINK "PIC_Source"}    - Where this picture comes from.

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

@{b}@{u}FIELD@{uu}@{ub}
Name:      Options
Type:      LONG
On Change: Cannot change after initialisation.
Status:    Read/Init

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

  @{u}IMG_REMAP@{uu}
  This flag remaps the source picture to fit the palette you have specified
  in the Picture->Bitmap->Palette field.  However, this will be done
  "auto-magically" if the two palettes differ.  For this reason this flag
  is somewhat redundant, but you can test if the picture was remapped on
  loading by checking for the flag afterwards.

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

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

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

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

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

@{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 Picture's resolution and Bitmap->Height.

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

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

@{b}@{u}FIELD@{uu}@{ub}
Name:        ScrMode
Type:        WORD
Inheritance: Source picture.
On Change:   Dynamic
Status:      Read/Write

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

@{b}@{u}SEE ALSO@{uu}@{ub}
Screen: @{"ScrMode" LINK "GMSDev:AutoDocs/Objects/Screens.guide/GS_ScrMode"}

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

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

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  field  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 Picture's resolution and Bitmap->Width.

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

@EndNode
---------------------------------------------------------------------------
@NODE "PIC_Source" "Object: Picture"

@{b}@{u}FIELD@{uu}@{ub}
Name:      Source
Type:      APTR
On Change: Cannot change after initialisation.
Status:    Read/Init

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  field  points  to  a source object - either FileName or MemPtr.  This
field  is  compulsory,  so  if  you  do  not  specify  a  Source  then  the
initialisation will fail.

@EndNode
---------------------------------------------------------------------------
@NODE "Picture_Init()" "Picture: Init()"

@{b}@{u}ACTION@{uu}@{ub}
Name:   *Picture Init(*Picture, NULL)
Object: Picture
Short:  Initialise a picture object so that it is ready for active use.

@{b}@{u}DESCRIPTION@{uu}@{ub}
This   action  initialises  a  picture  by  loading  it  into  memory.   If
Picture->Source  is  specified,  then  this  action  will  first attempt to
initialise  the  Picture  by  loading  the  Source  data.   If  the data is
recognised,   it   will   be   unpacked   to   the   buffer   specified  in
Picture->Bitmap->Data.   If  you do not supply a Data buffer, then a buffer
will   be   allocated  for  you  and  placed  in  Picture->Bitmap->Data  on
initialisation.

Note  that  by  setting  certain fields you are placing restrictions on the
picture  that is to be loaded.  For example, if the picture is wider then a
specified  width,  the  picture  will  have its right edge clipped.  To get
around  this  simply  leave  the  Width  field unspecified, and Init() will
initialise   this   field,   loading   the  picture  without  clipping  it.
Alternatively   you  could  specify  the  RESIZE  flag,  depending  on  the
circumstances.

Once  the  Picture  is loaded, the image will be held in the Bitmap object.
Remember  that  the  Bitmap  will  also  contain  information on the width,
height, amount of colours and so on.  If you specified for the Bitmap to be
held  in  VIDEO memory (Bitmap->MemType), you can also draw to and from the
Bitmap with functions like DrawLine() in the blitter module.

@{b}@{u}NOTE@{uu}@{ub}
If  this  action  cannot identify the source data, then the call will fail.
The native data format for the Picture class is IFF, but other formats such
as JPEG and PNG can be added via child classes.

@{b}@{u}SEE ALSO@{uu}@{ub}
Kernel:  @{"Init()" LINK "GMSDev:AutoDocs/Kernel.guide/Init()"}
Picture: @{"Load()" LINK "Picture_Load()"}
Include: @{"graphics/pictures.h" LINK "GMSDev:Includes/graphics/pictures.h/Main"}

@EndNode
-----------------------------------------------------------------------------
@NODE "Picture_Load()" "Picture: Load(*Source,[ID_PICTURE]|[NULL])"

@{b}@{u}ACTION@{uu}@{ub}
Name:   *Picture Load(*Source, [ID_PICTURE]|[NULL])
Object: Picture
Short:  Loads in a file that has been successfully identified as belonging
        to the picture class.

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  action  is provided as a quick and simple way of loading in a Picture
object.  All Picture data will be loaded into standard DATA memory.  If you
want to display your picture on a screen, use this action:

  Copy(Picture->Bitmap, Screen->Bitmap);

If  you  require more versatile loading, use the Init() function instead of
Load().

@{b}@{u}SEE ALSO@{uu}@{ub}
Kernel:  @{"Load()" LINK "GMSDev:AutoDocs/Kernel.guide/Load()"}
Picture: @{"Init()" LINK "Picture_Init()"}

@EndNode
---------------------------------------------------------------------------
@NODE "Picture_Query()" "Picture: Query(Picture)"

@{b}@{u}ACTION@{uu}@{ub}
Name:   Error = Query(Picture)
Object: Picture
Short:  Get the information on a recognised picture type.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Calling  this  action  will  fill  out all of the information on a Picture,
according  to  what  is  found  from  the  Picture->Source.   This includes
information  such  as  the width, height, palette values, screen dimensions
and so on.

This  action  is  safe  to  call before Init()ialising your Picture object.
Fields  that  are  !=  NULL  will  not be touched by this action.  For this
reason,  calling  Query()  after  a  call to Init() may be a fairly useless
exercise.

If the picture format is not supported, then an error code of ERR_DATA will
be returned.

@{b}@{u}SEE ALSO@{uu}@{ub}
Kernel: @{"Init()" LINK "GMSDev:AutoDocs/Kernel.guide/Init()"}
        @{"Query()" LINK "GMSDev:AutoDocs/Kernel.guide/Query()"}

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