@database CadOS memory
@node main "CadOS.memory functions"
TABLE OF CONTENTS

@{" CadOS.memory/AllocMem " link AllocMem}
@{" CadOS.memory/FreeMem " link FreeMem}
@{" CadOS.memory/SizeMem " link SizeMem}

@endnode

@node AllocMem
CadOS.memory/AllocMem                                 CadOS.memory/AllocMem

  NAME
    AllocMem()

  SYNOPSIS
    *memory=AllocMem(size, type)
       D0             D0    D1

  DESCRIPTION
    This routine allocates a block of memory for you to use, if there is
    enough memory free for this. If you specify 0 as type, the memory will
    be Fast memory if possible, but it may also be Chip memory if there is
    no Fast memory in the Amiga, or none left. If the function cannot
    allocate the memory on its first attempt, it will flush the system in
    the same way that the AmigaDOS command "Avail FLUSH" does, then it will
    try again. Do not worry about Chip memory bandwidth alignment - this is
    done if needed.

  INPUTS
    size       - the size of the block you want
    type       - 0 to try for Fast memory, but it might be Chip memory
                 allocated, any other value will ensure Chip memory, or
                 nothing at all

  RESULT
    memory     - a pointer to the block of cleared memory, or 0 if the
                 allocation failed. The allocation can be freed with the
                 FreeMem routine.

  NOTE
    The maximum number of memory allocations at any one time is specified
    by the assembler equate MEMELEMENTS, which is, by default, 128.

  SEE ALSO
    @{" FreeMem " link FreeMem}, @{" CadOS.display/AllocBitmap " link CadOS_display.guide/AllocBitmap}

@endnode

@node FreeMem
CadOS.memory/FreeMem                                   CadOS.memory/FreeMem

  NAME
    FreeMem()

  SYNOPSIS
    void FreeMem(*memory)
                    D0

  DESCRIPTION
    This routine frees any memory you got from within the CadOS environment
    or allocated yourself. Memory allocations are tracked within the CadOS
    environment, so there is no worry of things going wrong if you pass a
    bad or null pointer to FreeMem. All allocations made with CadOS, from
    AllocMem, AllocBitmap, DisplayIFF, MakeScreen, LoadFile and others, can
    be freed with the FreeMem routine. Anything you do not free during the
    demo will be freed at the end of your demo, but you should free memory
    whenever you don't need it again, to allow more chance of enough memory
    being free for the rest of the demo.

  INPUTS
    memory     - a pointer to the address of the start of the memory block
                 being freed.

  RESULT
    nothing - memory is freed

  NOTE
    Due to the memory tracking, there is no need to specify the size of the
    memory block being freed, like you would with exec's AllocMem.

  SEE ALSO
    @{" AllocMem " link AllocMem}

@endnode

@node SizeMem
CadOS.memory/SizeMem                                   CadOS.memory/SizeMem

  NAME
    SizeMem()

  SYNOPSIS
    size=SizeMem(*memory)
     D0             A0

  DESCRIPTION
    When you pass this routine a memory pointer, it searches the memory
    list to see if the address passed is in one of the CadOS allocated
    memory blocks. If it is, then the amount of memory between your pointer
    and the end of the block is returned. You may also use the result as
    a boolean value of whether the pointer is CadOS allocated memory or
    not.

  EXAMPLE
    move.l  #2000,d0
    jsr     _AllocMem	; allocate 2000 bytes
    tst.l   d0
    beq.s   quit
    add.l   #1500,d0
    move.l  d0,a0	; point at 1500 bytes into the block
    jsr     _SizeMem
    ; will return 500 in d0

  INPUTS
    memory     - a pointer to an address that you think is part of a memory
                 block allocated by CadOS.

  RESULT
    size       - The size remaining in the block from that pointer onwards,
                 or 0 if the pointer isn't in a block.

  SEE ALSO
    @{" AllocMem " link AllocMem}

@endnode