@DATABASE "Kernal"
@AUTHOR "Paul Manias"
@NODE "Main" "Kernal"

Name:         @{"GMS KERNAL" 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" "Kernal Functions"

 @{b}KERNAL@{ub}
 @{"AddInputHandler()" LINK "AddInputHandler()"}
 @{"AllocMemBlock()"   LINK "AllocMemBlock()"}
 @{"AutoSwitch()"      LINK "AutoSwitch()"}
 @{"CloseGMS()"        LINK "CloseGMS()"}
 @{"CloseGPI()"        LINK "CloseGPI()"}
 @{"FindGMSTask()"     LINK "FindGMSTask()"}
 @{"FreeMemBlock()"    LINK "FreeMemBlock()"}
 @{"GetMemSize()"      LINK "GetMemSize()"}
 @{"GetMemType()"      LINK "GetMemType()"}
 @{"GMSForbid()"       LINK "GMSForbid()"}
 @{"GMSPermit()"       LINK "GMSPermit()"}
 @{"OpenGPI()"         LINK "OpenGPI()"}
 @{"OpenGPIFile()"     LINK "OpenGPIFile()"}
 @{"RemInputHandler()" LINK "RemInputHandler()"}
 @{"SetUserPrefs()"    LINK "SetUserPrefs()"}
 @{"Switch()"          LINK "Switch()"}
 @{"TotalMem()"        LINK "TotalMem()"}

 @{b}Resource Tracking@{ub}
 @{"AddTrack()"     LINK "AddTrack()"}
 @{"DeleteTrack()"  LINK "DeleteTrack()"}
 @{"InitDestruct()" LINK "InitDestruct()"}
 @{"SelfDestruct()" LINK "SelfDestruct()"}

 @{"Load()"   LINK "Load()"}
 @{"Unload()" LINK "Unload()"}

@EndNode
---------------------------------------------------------------------------
@NODE "AddInputHandler()" "Kernal/AddInputHandler"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      AddInputHandler()
Short:     Add an input handler to the system.
Assembler: AddInputHandler()
C/C++:     void AddInputHandler(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Adds  an  input  handler at the highest priority to delete all system input
events.  The idea behind this is to prevent input falling through to system
screens and to give you more CPU time by killing all inputs.

If you are going to use any of the Read functions (eg ReadKey()) then it is
vital  that  this  function  is  active.   This is because some of the Read
functions are hooked into the input handler that this function provides.

@{b}@{u}NOTE@{uu}@{ub}
By  default  this function is always called by ShowScreen().  Therefore you
only  need  to call this routine if you are using some other screen opening
routine not in GMS.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "AddTrack()" "Kernal/AddTrack"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      AddTrack()
Short:     Adds a resource tracking node.
Assembler: Key = AddTrack(Resource [d0], Data [d3], Routine [a0])
C/C++:     LONG AddTrack(LONG Resource, LONG Data, void *Routine);

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  is  intended  for  use  by GPI's but you may use it in your
program if necessary.

@{u}About Resource Tracking@{uu}
Each GMS task has a special list of all system resources that are currently
in  use.   Each resource has its own list node that uniquely identifiess it
(eg  each  memory allocation has its own resource node).  When a particular
resource  has  been  freed  the  list  is  checked  and its related node is
deleted.   When the program shuts down, any resources that are still in the
list can be freed by GMS so that they are not lingering in the system.

It  is  important to acknowledge here that resources are preferably tracked
in their most basic form rather than the most complex types.  For example a
call  to  InitBob()  results in a lot of calculations and data storage, but
when  we  look at it in detail we find that it consists entirely of memory.
Therefore  only  the  memory needs to be tracked and a special track on the
bob  itself is not necessary.  This keeps resource tracking very simple and
efficient.

When you call AddTrack() you need to give it a resource ID which is made up
from  one  of the following resource types.  This is important as resources
are freed from the system in an order based on these ID's.  The order looks
like this:

	1. Free all hardware based resources (blitter, sound, etc).
	2. Free complex resources (both hardware and software).
	3. Free customised resources (user defined types etc).
	4. Free memory (always free memory last).

As  you  can  see  the correct order is vital, if memory was freed first it
would  have  adverse  affects  when  freeing  the complex and user resource
types.   Always make sure that you give the correct ID when describing your
resource.    The   ID's   are  RES_MEMORY,  RES_HARDWARE,  RES_COMPLEX  and
RES_CUSTOM, as outlined in games/tasks.i.

Passing  a  Data  pointer  is  optional,  but  you will need it to uniquely
identify  your  resource  later on (eg AllocMemBlock() uses this to store a
pointer to the allocated memory).

The  Routine  points  to code that will free the resource if it is still in
use  when  the  program exits (or if SelfDestruct() is called).  It will be
passed  the  Data  field  of  the resource node in register d0, and the Key
field in register d1.  This routine must save all the CPU registers that it
uses  and  can  only free its resource - it may not make new allocations of
any  sort.   It  may send debug and error messages, which will help working
out what the problem is if anything goes wrong.

@{b}@{u}INPUT@{uu}@{ub}
Resource - Correct resource identifier from games/tasks.i.
Data     - Optional data pointer to store in the resource node.
Routine  - Pointer to the routine to call when freeing the resource.

@{b}@{u}RESULT@{uu}@{ub}
Key  -  A  key  that AddTrack() has used to uniquely identify the resource.
You will need to store the key somewhere for when you call DeleteTrack().

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"DeleteTrack" LINK "DeleteTrack()"}, games/tasks.i

@EndNode
---------------------------------------------------------------------------
@NODE "AllocMemBlock()" "Kernal/AllocMemBlock"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      AllocMemBlock()
Short:     Allocate a new memory block.
Assembler: MemBlock = AllocMemBlock(Size [d0], MemType [d1])
C/C++:	   APTR AllocMemBlock(LONG Size, LONG MemType)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  allocates  a  memory  block from the system memory pool and
returns  it  to  your  program.  By default all GMS memory is public.  This
open memory model is used to enhance the communication levels between tasks
and  functions.   If  you need private memory make sure that you ask for it
and that you will be the only task using it.

Header  and  Tail  ID's  are  used  to  offer  a security system similar to
MungWall,  acting  as cookies on the header and tail of memory blocks.  You
will  be  alerted  by  FreeMemBlock()  if  the ID's are damaged.  This is a
permanent  debugging  feature,  so there is little need to run MungWall for
debugging your programs.

Resource  tracking  is  automatic,  so  you  will be warned if you allocate
memory  and forget to free it on exit (ie when you close GMS).  This memory
will be freed for your convenience.

By  default  all GMS memory is cleared before it is given to you.  Here are
the memory types:

  @{u}MEM_DATA@{uu}
  Suitable for storing data and variables.  This is the default.  Note that
  you are disallowed from running code from this type of memory.

  @{u}MEM_CODE@{uu}
  Can  store and execute CPU instructons.  It also fits the requirements of
  MEM_DATA, so you can store variables and data in it.

  @{u}MEM_VIDEO@{uu}
  Is  for  displaying  graphics,  and  is  also compatible with the Blitter
  interface.

  @{u}MEM_BLIT@{uu}
  Is  memory  that  is compatible with the Blitter.GPI.  Currently this GPI
  only uses chip memory, but future versions could also support CPU drawing
  from fast if the graphic is located in that area.

  @{u}MEM_SOUND@{uu}
  For memory that is compatible with the Sound interface.

You  may  also  use  the  following  extra  flags  when  making your memory
allocation:

  @{u}MEM_PRIVATE@{uu}
  If other programs should not have access to your memory.

  @{u}MEM_UNTRACKED@{uu}
  If  you don't want resource tracking on your allocation.  You should only
  use this flag if the memory is part of a complex resource that is already
  being tracked.


@{b}@{u}INPUT@{uu}@{ub}
Size    - Size of the required memblock in bytes.
MemType - The type of memory to allocate, eg MEM_VIDEO.


@{b}@{u}RESULT@{uu}@{ub}
MemBlock - Pointer to the start of your allocated memblock or NULL if
           failure.


@{b}@{u}SEE ALSO@{uu}@{ub}
@{"FreeMemBlock" LINK "FreeMemBlock()"}, @{"GetMemSize"   LINK "GetMemSize()"}, @{"GetMemType"   LINK "GetMemType()"}

@EndNode
-----------------------------------------------------------------------------
@NODE "CloseGMS()" "Kernal/CloseGMS"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:	   CloseGMS()
Short:     Closes the Games Master System.
Assembler: CloseGMS()
C/C++:     void CloseGMS(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Before  your  program exits you will have to call this function so that the
system  knows  you  are  shutting down.  If you do not close GMS before you
exit  you  will  leave  certain memory allocations unfreed and there may be
other adverse system effects.

This  function  will  perform a resource tracking check, so if you have not
freed  any  system resources you will be notified here (if you get a yellow
alert  box,  you  will need to use IceBreaker to get a detailed list of the
errors).

This  function  is  used in the StartGMS macro and the gms.o file, so C and
assembler programmers should not need to call this function explicitly.

@{b}@{u}NOTE@{uu}@{ub}
Remember that you may not call any GMS functions after calling CloseGMS().

@EndNode
--------------------------------------------------------------------------
@NODE "CloseGPI()" "Kernal/CloseGPI"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      CloseGPI()
Short:     Closes a GPI that was previously initialised.
Assembler: CloseGPI(GPI [a0])
C/C++:	   void CloseGPI(struct GPI *GPI)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Informs  GMS  that you no longer wish to use the specified GPI's functions.
You cannot make any calls to the GPI after removing it.

All GPI's that you open must be removed before your program exits.

@{b}@{u}INPUTS@{uu}@{ub}
GPI - Pointer to a valid GPI structure as returned from InitGPI().

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

@EndNode
-----------------------------------------------------------------------------
@NODE "DeleteTrack()" "Kernal/DeleteTrack"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      DeleteTrack()
Short:     Delete a resource tracking node.
Assembler: DeleteTrack(Key [d1])
C/C++:     void DeleteTrack(LONG Key);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Deletes  a  resource node allocated from AddTrack().  If resource nodes are
not  deleted  they  will stay linked to the program and GMS will attempt to
free them when the program shuts down.

Note that this function only deletes the resource node, it will not attempt
to deallocate the resource by calling its deallocation function.

@{b}@{u}INPUT@{uu}@{ub}
Key - A key that was obtained from AddTrack().

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

@EndNode
-----------------------------------------------------------------------------
@NODE "FindGMSTask()" "Kernal/FindGMSTask"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      FindGMSTask()
Short:     Find the GMSTask structure for the current task.
Assembler: GMSTask = FindGMSTask()
C/C++      struct GMSTask * FindGMSTask(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  will  return the GMSTask structure for the task that called
it.   The  GMSTask  structure  is used for storing data that is specific to
your task - things like preference settings for example.  Almost all of the
GMSTask  fields  are  private  and  you  you cannot write to this structure
unless you are a GPI.

For  the  curious,  it only takes 3 assembler instructions to grab the task
node, so there is no time wasted in calling this function.

@{b}@{u}RESULT@{uu}@{ub}
GMSTask - Points to the GMSTask structure.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"games/tasks.i" LINK "INCLUDES:games/tasks.i/Main"}

@EndNode
---------------------------------------------------------------------------
@NODE "FreeMemBlock()" "Kernal/FreeMemBlock"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      FreeMemBlock()
Short:     Free a previously allocated mem block.
Assembler: FreeMemBlock(MemBlock [d0])
C/C++:     void FreeMemBlock(APTR MemBlock)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Frees   a   memory  area  allocated  by  AllocMemBlock(),  AllocVideoMem(),
AllocBlitMem(),  or AllocSoundMem().  If the mem header or tail is missing,
then  it  is assumed that something has written over the boundaries of your
memblock,  or  you  are  attempting  to  free  a  non-existant  allocation.
Normally  this  would  cause a complete system crash, but instead we simply
send a message to IceBreaker and leave the memory block in the system.

Bear  in  mind that it does pay to save your work and reset your machine if
such a message appears, as it indicates that important memory data may have
been destroyed.

@{b}@{u}NOTE@{uu}@{ub}
Never attempt to free the same MemBlock twice.

@{b}@{u}INPUT@{uu}@{ub}
MemBlock - Points  to  the  start  of a memblock.  If NULL, then no
	   action will be taken (function exits).

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

@EndNode
---------------------------------------------------------------------------
@NODE "GMSForbid()" "Kernal/GMSForbid"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GMSForbid()
Short:     Stop other tasks/processes from executing.
Assembler: GMSForbid()
C/C++:     void GMSForbid()

@{b}@{u}DESCRIPTION@{uu}@{ub}
Stops  all  other  tasks  and  processes  from  executing  until  you  call
GMSPermit().  This call will not turn off interrupts.

@{b}@{u}NOTE@{uu}@{ub}
This function has no effect in systems that do not multi-task.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "GMSPermit()" "Kernal/GMSPermit"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GMSPermit()
Short:     Allow other tasks to continue their processing.
Assembler: GMSPermit()
C/C++:     void GMSPermit(void);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Reverses  a  previous  call  to GMSForbid(), so that all tasks can continue
their normal processes.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "InitDestruct()" "Kernal/InitDestruct"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      InitDestruct()
Short:     Initialise the task for use of SelfDestruct().
Assembler: InitDestruct(DestructCode, DestructStack)
C/C++:     void InitDestruct(APTR DestructCode, APTR DestructStack)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  is  a  special  function  that is called in the STARTGMS macro, gms.o
startup  file  and  StartGMS  program  only.   You  should  never call this
function explicitly unless you are writing your own startup code.

InitDestruct()  will  prepare  your task so that it may be destroyed by the
SelfDestruct() function.  DestructCode must point to the exit code for your
task.   The  exit  code  must call CloseGMS() if you are to free your tasks
resources.   DestructStack  must  point  to the correct stack area for your
exit code, otherwise your task cannot return to the system correctly.

To  see an example of how this function works look at the STARTGMS macro in
games/games.i.

@{b}@{u}INPUTS@{uu}@{ub}
DestructCode  - Points to the code at which your task makes its exit.
DestructStack - Points to the stack that will be used for the exit.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "Load()" "Kernal/Load"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      Load()
Short:     Loads an Amiga formatted segment file.
Assembler: Segment = Load(Filename)
C/C++:     struct Segment * Load(char *Filename)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  currently works the same as the DOS LoadSeg() function - be
aware that this will change.

@{b}@{u}INPUT@{uu}@{ub}
Filename - Pointer to a null terminated string identifying the file
	   location.

@{b}@{u}RESULT@{uu}@{ub}
Segment - Pointer to the first segment in the chain.

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

@EndNode
---------------------------------------------------------------------------
@NODE "OpenGPI()" "Kernal/OpenGPI"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      InitGPI()
Short:     Load in a GPI and initialise it for function calls.
Assembler: GPI = InitGPI(ID [d0], Version [d1], Revision [d2], Flags [d3])
C/C++:	   struct GPI * InitGPI(WORD ID, WORD Version, WORD Revision,
	    LONG Flags);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Loads  in a GPI and initialises it ready for function calls.  This function
will return a special structure that you can use to interface with the GPI.
Note  that  due to the involvement of this structure, the behaviour of this
function is significantly different to exec's OpenLibrary().

Firstly  the  library  function  base that is given, may not necessarily be
shared  between  tasks.  InitGPI() has introduced the ability of changing a
function  model  between  versions, without losing backwards compatibility.
For  example  on  early  Amigas  the  OpenLibrary()  call became inadequate
because  it  would  not  take version numbers.  Later this was rectified by
renaming  it  to OldOpenLibrary() and introducing a new OpenLibrary() call.
What  InitGPI()  does  is allow different function models to be defined for
specific  version  numbers.   When a GPI is opened it can check the version
number  argument  and  then  pass  a tailor-made function list back to your
program.   So  if  a  function  had to change in future, your older program
would  simply  be routed to a routine that provides backwards compatibility
to  the  new function model.  Newer programs would of course go straight to
the expected function.

Secondly  InitGPI()  gives you the option of what kind of function base you
would  like  returned.   Amiga  programmers  are  quite  used  to using the
following code to make library calls:

	move.l	GMSBase(pc),a6
	jsr	-XXX(a6)

However   library   calls  on  other  platforms  may  be  taken  completely
differently.   This  is  quite  important  when  producing a cross platform
binary  as there could be some confusion as to what function base should be
returned.   So,  what  InitGPI() does is allow you to specify directly what
sort  of  function  base you want returned.  This also has the advantage in
that  you  may  have  a personal preference for a different type of calling
procedure.  For the moment though, only JMP_AMIGA is given as an option.

The  last  point  of  interest is that GPI code is re-entrant, so all tasks
using a particular GPI will go through the same function code.

If  you  want  to write your own GPI, read the relevant section in the main
documentation.

@{b}@{u}INPUTS@{uu}@{ub}
ID       - A recognised GPI ID from games/games.i.  Examples are GPI_NETWORK,
	    GPI_CARDS, GPI_TEXT.
Version  - The minimum GPI version that you require.
Revision - The minimum GPI revision that you require.
Flags    - Currently allows JMP_AMIGA only.

@{b}@{u}RESULT@{uu}@{ub}
GPI - Pointer to a personalised GPI structure or NULL if error.

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

@EndNode
---------------------------------------------------------------------------
@NODE "RemInputHandler()" "Kernal/RemInputHandler"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      RemInputHandler()
Short:     Remove the active input handler.
Assembler: RemInputHandler()
C/C++:     void RemInputHandler(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Removes  the  active  input handler from the system.  As a result this will
also deactivate certain Read functions (eg ReadKey()).

@{b}@{u}NOTE@{uu}@{ub}
DeleteScreen() automatically calls this function so that any input handlers
set up by ShowScreen() are removed.

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

@EndNode
---------------------------------------------------------------------------
@NODE "SetUserPrefs()" "Kernal/SetUserPrefs"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      SetUserPrefs()
Short:     Initialises a new set of preferences.
Assembler: ErrorCode = SetUserPrefs(Name [a0])
C/C++:     LONG SetUserPrefs(BYTE *Name)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Initialises  a  new  set of preferences for a GMS task.  This function will
take  the  Name  you have given and search for its directory in GMS:Prefs/.
If  found,  the settings in this directory will be loaded and each GPI will
be  reactivated for the new preferences to take effect.  If the Name is not
found or if you supply a Name of NULL, the default settings will be loaded.
If  the  default settings are not found, then the internal settings will be
used.

This  function  may  also set your tasks priority and perform various other
actions  that  can directly affect your task, or the environment that it is
running  in.   For  this  reason,  it  is  essential that this is the first
function that you call after opening GMS.

The prefences manager for altering game settings is GMSPrefs, which handles
all game directories, the default settings and so on.  For more information
on the options available to the user, see the file GMSPrefs.guide.

@{b}@{u}NOTE@{uu}@{ub}
The  field  tc_UserData  in  your exec task node will be used to point to a
second  GMSTask  node.  If you need a UserData node, there is a link called
GT_UserData  in the GMSTask structure (see games/tasks.i) which you may use
for  your  own means.  We recommend that you treat this field as a chain of
links in case of future expansion.

@{b}@{u}INPUT@{uu}@{ub}
Name - The name of the preferences directory to access, or NULL for the
       default.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "SelfDestruct()" "Kernal/SelfDestruct"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      SelfDestruct()
Short:     Destroys the task and frees resources.
Assembler: SelfDestruct()
C/C++:     void SelfDestruct(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Destroys  the  task that called this function and then proceeds to free all
of  its  resources  according  to the resource nodes.  This is a completely
safe  and  effective  way  of  destroying  a  task,  and  can  be  used for
deconstructing a task when it has got into unrecoverable circumstances.

You  must  have called InitDestruct() before calling this function.  If you
are  programming  in  C  or assembler this initialisation is already in the
STARTGMS macro and gms.o startup file, so this does not concern you.

@{b}@{u}NOTE@{uu}@{ub}
This  function  will  not  return.   However if InitDestruct() has not been
called  then  the  function will not be able to do anything and will return
back to the task.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "TotalMem()" "Kernal/TotalMem"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      TotalMem()
Short:
Assembler: Total = TotalMem(GMSTask [a0], Flags [d0])
C/C++:     LONG TotalMem(struct GMSTask *, LONG Flags)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Gets the total amount of memory currently in use by a GMS task.  This total
can  be calculated from a specific type of memory, or a total of all memory
in use if -1 is specified.  If GMSTask is passed as NULL then this function
will sum up the total amount of memory used by all GMS tasks.

@{b}@{u}INPUT@{uu}@{ub}
GMSTask - Pointer  to  a  GMSTask  structure  or NULL to calculate from all
	  structures.
Flags   - The  memory  type  that  you  want  to  be calculated (MEM_VIDEO,
	  MEM_SOUND,  MEM_DATA  or MEM_BLIT).  If you want a complete total
	  of all memory in use, specify -1 here.

@{b}@{u}RESULT@{uu}@{ub}
Total - The total amount of memory in use.

@EndNode
-----------------------------------------------------------------------------
@NODE "Unload()" "Kernal/Unload"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      Unload()
Short:     Unloads a previously loaded segment file.
Assembler: Unload(Segment [a0])
C/C++:     void Unload(struct Segment *)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This function currently works the same as the DOS UnLoadSeg() function - be
aware that this will change.

@{b}@{u}INPUT@{uu}@{ub}

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

@EndNode
-----------------------------------------------------------------------------
@NODE "GetMemSize()" "Kernal/GetMemSize"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GetMemSize()
Short:     Identifies the size of a given memory block.
Assembler: Size = GetMemSize(MemBlock [a0])
C/C++:     LONG GetMemSize(APTR MemBlock)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  will get the size of any memory block legally obtained from
AllocMemBlock().  Illegal pointers will result in a return of NULL.

@{b}@{u}INPUT@{uu}@{ub}
MemBlock - Pointer to the start of the memory block to be identified.

@{b}@{u}RESULT@{uu}@{ub}
Size - The size of the memory block in bytes.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "GetMemType()" "Kernal/GetMemType"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GetMemType()
Short:     Identifies the type of memory in use by a particular memory block.
Assembler: Type = GetMemType(MemBlock [a0])
C/C++:     LONG GetMemType(APTR MemBlock)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This function will get the memory type of any memory block legally obtained
from AllocMemBlock().  Illegal pointers will result in a return of -1.

@{b}@{u}INPUT@{uu}@{ub}
MemBlock - Pointer to the start of the memory block to be identified.

@{b}@{u}RESULT@{uu}@{ub}
Type - Memory flags identifying the block (see @{"AllocMemBlock" LINK "AllocMemBlock()"}).

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

@EndNode
---------------------------------------------------------------------------
@NODE "Switch()" "Kernal/Switch"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      Switch()
Short:     Stops the task that called this function.
Assembler: Switch()
C/C++:     void Switch(void);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Switches  your task over to the next task in the queue.  This function will
not return until the user reactivates your task, so your tasks execution is
effectively  stopped.  Any secondary processes and interrupts that you have
spawned will continue to execute, so multi-tasking can still be effective.

If  the next task is screen-based, then your screen display will be removed
and  the  new  screen  will  be displayed.  If you have any secondary tasks
running,   then   take   note:    You  must  not  allow  them  to  use  the
drawing/blitter  operations as your display memory may be temporarily moved
to  free  up  video  memory.   Blitting  to  an  invisible  display is also
considered  to  be  bad  practice  as  most GMS tasks require all available
blitter time.  We also ask you to refrain from using the audio functions as
the next task will probably be needing all available channels.

If  there  are no more GMS tasks in the queue, then the screen display will
return  to  intuition.   GMS  supports  two  methods of screen switching to
intuition, Switch-To-Window and Switch-To- Screen.  The method used depends
on the setting in the GMSPrefs utility.

Switch-To-Window  drops out to workbench and places a window on the screen.
It  will  wait  until the close gadget is pressed, whereupon your game will
continue where it left off.

Switch-To-Screen  opens an intution screen and busy-waits until that screen
comes  to the front.  At that point the intuition screen will be closed and
your game will resume execution.

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

@EndNode
---------------------------------------------------------------------------
@NODE "AutoSwitch()" "Kernal/AutoSwitch"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      AutoSwitch
Short:     Returns the screen display to the native OS if user requests it.
Assembler: AutoSwitch()
C/C++:     void AutoSwitch(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Returns   the   screen  display  to  intuition  if  the  user  pressed  the
Left-Amiga+M  key  combination.  Your game's execution will be halted until
the user brings your screen back.

GMS   supports  two  methods  of  screen  switching,  Switch-To-Window  and
Switch-To-Screen.   The  method used depends on the setting in the GMSPrefs
utility.

Switch-To-Window  drops out to workbench and places a window on the screen.
It  will  wait  until the close gadget is pressed, whereupon your game will
continue where it left off.

Switch-To-Screen  opens an intution screen and busy-waits until that screen
comes  to the front.  At that point the intuition screen will be closed and
your game will resume execution.

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

@EndNode
-----------------------------------------------------------------------------
@NODE "()" "Kernal/"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      ()
Short:     
Assembler: 
C/C++:     

@{b}@{u}DESCRIPTION@{uu}@{ub}

@{b}@{u}NOTE@{uu}@{ub}

@{b}@{u}INPUT@{uu}@{ub}

@{b}@{u}RESULT@{uu}@{ub}

@{b}@{u}SEE ALSO@{uu}@{ub}

@EndNode