@DATABASE "ObjectFile"
@AUTHOR   "Paul Manias"
@NODE     "Main" "Object: ObjectFile"

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

@{b}@{u}CHANGES VERSION 0.9B@{uu}@{ub}
Renamed: ObjectBase now called ObjectFile.

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

@{b}@{u}OBJECT@{uu}@{ub}
Name:    ObjectFile
Version: 1
ID:      ID_OBJECTFILE
Module:  @{"Objects" LINK "GMSDev:AutoDocs/Objects.guide"}
Include: @{"files/objects.h" LINK "GMSDev:Includes/files/objects.h/Main"}
Type:    Complex

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  ObjectFile  is  one  of  the  most powerful and useful objects in this
system,  allowing  your  program  to load object specifications from binary
files.   The  use  of  external  object  definitions allows one significant
advantage:  After your program is compiled you can still make major changes
and enhancements without needing any source code.

This  is  a  major  boon for both developers and users alike.  Lets look at
some  examples  of  what  can  be  acheived  when  your objects are defined
externally:

  * You could set new Screen parameters, such as width, height, colours
    and resolution.

  * External code segments can be written for easy "plug-in" and program
    extensions.

  * New sound effects could be added or old ones replaced.

  * Graphics can be enhanced by other artists to unforeseen levels.  For
    example typical resolutions today are 640x512, but in 3 years your
    game could easily run in 2560x2048 without any recompiling.  Bob sizes
    can also be increased and then redrawn to fit resolution differences.

You  can  probably  think of a lot more examples, depending on what sort of
programs you want to write.

@{b}@{u}How To Create ObjectFiles@{uu}@{ub}
Before you get to use the ObjectFile object in a program, you first need to
create  an  object  file  for you to load.  Currently you need an assembler
like PhxAss to generate one for you.  You best way to learn how to write an
object file is by example.  Click @{"here" LINK "OBJ_Example"} to see an object file that contains
a Screen and a Picture.

The format for an object file is as follows:

---START----------------------------------

       SECTION "ObjectData",DATA

       dc.l   "OBJF"        ;Standard Header.

OBJ_1: dc.l   <Type>        ;Type of object.
       dc.l   <NextObject>  ;Pointer to next object.
       dc.b   <Name>        ;Name of this object.
       even

       <ObjectData>

OBJ_2: ...More Objects...

OBJ_END:
       dc.l   <Type>        ;Type of object.
       dc.l   <EndOfFile>   ;Pointer to the termination string.
       dc.b   <Name>        ;Name of this object.
       even

       <ObjectData>

End:   dc.l   "OEND"        ;Termination of the file.

---END------------------------------------

The Type of the object tells the processing functions what you are about to
define.  The currently available Types are:

  "TAGS" - This is what you will normally specify when defining objects
           such as Screens, Pictures, Bobs etc.

  "M000" - Set this if the Data section consists of M68000 instructions.
           M020, M030, and M040 settings may be specified if necessary.

  "DATA" - This is to be used when you are defining some program specific
           data that should stay in its raw format.

The  NextObject  field  points to the next object in the list, in this case
OBJ_2.

The  Name  string  is  a  simple  name  for your object like "My Screen" or
whatever  makes sense to you.  You will need to remember what you call each
object because that is the only way to find them in the ObjectFile.

The  ObjectData  section  follows  immediately after the Name string (on an
even  boundary)  and contains the data for your object.  For example if you
specifed the "TAGS" Type, you will start with a normal TagList here.

The  end  of  the  file is then terminated with "OEND".  Note that the last
object in your list must have a pointer to this string.

@{b}@{u}FUNCTIONS@{uu}@{ub}
Some functions supporting the ObjectFile are:

     @{"PullObject()"     LINK "GMSDev:AutoDocs/Objects.guide/PullObject()"}
     @{"PullObjectList()" LINK "GMSDev:AutoDocs/Objects.guide/PullObjectList()"}

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

     @{"Free()" LINK "GMSDev:AutoDocs/Kernel.guide/Free()"} - Free an ObjectFile.
     @{"Get()" LINK "GMSDev:AutoDocs/Kernel.guide/Get()" }  - Get a new ObjectFile.
     @{"Init()" LINK "GMSDev:AutoDocs/Kernel.guide/Init()"} - Initialise/Load an ObjectFile.
   * @{"Load()" LINK "ObjectFile_Load()"} - Easy loading for ObjectFiles.

@{b}@{u}STRUCTURE@{uu}@{ub}
The ObjectFile structure consists of one public field:

     @{"Source" LINK "OBJ_Source"} Pointer to a file source.

@EndNode
---------------------------------------------------------------------------
@NODE "OBJ_Source" "Object: ObjectFile"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Source
Type:        struct Source *
Inheritance: Must be specified by programmer.
On Change:   Cannot change after initialisation.
Status:      Read/Init

@{b}@{u}DESCRIPTION@{uu}@{ub}
Before  you initialise your ObjectFile you need to have specified a source.
This field accepts pointers to FileNames, MemPtrs, and standard Files.  All
you need to do is make sure that the location is in the correct object file
format.

@EndNode
-----------------------------------------------------------------------------
@NODE "ObjectFile_Load()" "ObjectFile: Load()"

@{b}@{u}ACTION@{uu}@{ub}
Name:   Load(*File, ID_OBJECTFILE)
Object: ObjectFile
Short:  Load an external object file.

@{b}@{u}DESCRIPTION@{uu}@{ub}
Loads  in  a  standard  object file, checks it for validity and returns the
resulting ObjectFile structure back to you.

Once  you  have  called  this  action  you  can  use  the object processing
functions such as PullObject() to obtain your data.  See the information on
Objects for further understanding of these files.

You will need to Free() the ObjectFile ater you have finished using it.

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

@EndNode
---------------------------------------------------------------------------
@NODE "OBJ_Example" "ObjectFile Example"

	INCDIR	"GMSDev:Includes/"
	INCLUDE	"dpkernel/dpkernel.i"

	SECTION	"ObjectData",DATA

Objects	dc.l	"OBJF"	;Header.

OBJ_Screen:
	dc.l	"TAGS"	;Structure ID.
	dc.l	.next	;Pointer to next object.
	dc.b	"Screen",0	;Name.
	even
.data	dc.l  TAGS_SCREEN,0
	dc.l  GSA_Width,640
	dc.l  GSA_Height,256
	dc.l  GSA_Attrib,SCR_CENTRE
	dc.l  GSA_ScrMode,SM_HIRES|SM_LACED
	dc.l    GSA_BitmapTags,0
	dc.l    BMA_Type,ILBM
	dc.l    BMA_AmtColours,16
	dc.l    TAGEND,0
	dc.l  TAGEND

.next ;-------------------------------------------------------------------;

OBJ_Picture:
	dc.l	"TAGS"	;Structure ID.
	dc.l	.next	;Pointer to next object.
	dc.b	"Picture",0	;Name.
	even
.data	dc.l	TAGS_PICTURE,0
	dc.l	PCA_ScrMode,SCR_HIRES|SCR_LACED
	dc.l	PCA_Source,.file
	dc.l	  PCA_BitmapTags,0
	dc.l	  BMA_AmtColours,16
	dc.l	  BMA_Type,ILBM
	dc.l	  BMA_Width,640
	dc.l	  BMA_Height,256 
	dc.l	  BMA_MemType,MEM_VIDEO
	dc.l	  TAGEND,0
	dc.l	TAGEND

.file	FILENAME "GMS:demos/data/PIC.Pic640x256"

.next ;-------------------------------------------------------------------;

	dc.l	"OEND"

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