@database "layers"
@master "ADCD_v1.2:IncludesD/Inc&AD1.3/doc/layers.doc"

@Node Main "layers.doc"
@TOC 1.3Includes_Autodocs/Autodocs

@{" BeginUpdate() " Link "BeginUpdate()"}           @{" MoveLayer() " Link "MoveLayer()"}
@{" BehindLayer() " Link "BehindLayer()"}           @{" MoveLayerInFrontOf() " Link "MoveLayerInFrontOf()"}
@{" CreateBehindLayer() " Link "CreateBehindLayer()"}     @{" NewLayerInfo() " Link "NewLayerInfo()"}
@{" CreateUpfrontLayer() " Link "CreateUpfrontLayer()"}    @{" ScrollLayer() " Link "ScrollLayer()"}
@{" DeleteLayer() " Link "DeleteLayer()"}           @{" SizeLayer() " Link "SizeLayer()"}
@{" DisposeLayerInfo() " Link "DisposeLayerInfo()"}      @{" SwapBitsRastPortClipRect() " Link "SwapBitsRastPortClipRect()"}
@{" EndUpdate() " Link "EndUpdate()"}             @{" ThinLayerInfo() " Link "ThinLayerInfo()"}
@{" FattenLayerInfo() " Link "FattenLayerInfo()"}       @{" UnlockLayer() " Link "UnlockLayer()"}
@{" InitLayers() " Link "InitLayers()"}            @{" UnlockLayerInfo() " Link "UnlockLayerInfo()"}
@{" InstallClipRegion() " Link "InstallClipRegion()"}     @{" UnlockLayers() " Link "UnlockLayers()"}
@{" LockLayer() " Link "LockLayer()"}             @{" UpfrontLayer() " Link "UpfrontLayer()"}
@{" LockLayerInfo() " Link "LockLayerInfo()"}         @{" WhichLayer() " Link "WhichLayer()"}
@{" LockLayers() " Link "LockLayers()"}

@EndNode

@Node "BeginUpdate()" "layers.library/BeginUpdate"

NAME
    BeginUpdate -- Prepare to repair damaged layer.

SYNOPSIS
    result = BeginUpdate( l )
    d0                    a0

    BOOLEAN result;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;

FUNCTION
    Convert damage list to @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} list and swap in for
    programmer to redraw through. This routine simulates
    the ROM library environment. The idea is to only render in the
    "damaged" areas, saving time over redrawing all of the layer.
    The layer is locked against changes made by the layer library.

INPUTS
    l - pointer to a layer

RESULTS
    result - TRUE if damage list converted to @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} list sucessfully.
             FALSE if list conversion aborted. (probably out of memory)

BUGS
    If BeginUpdate returns FALSE, programmer must abort the attempt to
    refresh this layer and instead call EndUpdate( l, FALSE ) to restore
    original @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} and damage list.

SEE ALSO
    @{"EndUpdate" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/EndUpdate()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "BehindLayer()" "layers.library/BehindLayer"

NAME
    BehindLayer -- Put layer behind other layers.

SYNOPSIS
    result = BehindLayer( dummy, l )
    d0                    a0     a1

    BOOLEAN result;
    LONG dummy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;

FUNCTION
    Move this layer to the most behind position swapping bits
    in and out of the display with other layers.
    If other layers are REFRESH then collect their damage lists and
    set the LAYERREFRESH bit in the Flags fields of those layers that
    may be revealed.  If this layer is a backdrop layer then
    put this layer behind all other backdrop layers.
    If this layer is NOT a backdrop layer then put in front of the
    top backdrop layer and behind all other layers.

    Note: this operation may generate refresh events in other layers
       associated with this layer's @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure.

INPUTS
    dummy - unused
    l - pointer to a layer

RESULTS
    result - TRUE    if operation successful
             FALSE   if operation unsuccessful (probably out of memory)

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "CreateBehindLayer()" "layers.library/CreateBehindLayer"

NAME
    CreateBehindLayer -- Create a new layer behind all existing layers.

SYNOPSIS
    result = CreateBehindLayer(li,bm,x0,y0,x1,y1,flags [,bm2])
    d0                         a0 a1 d0 d1 d2 d3   d4  [ a2 ]

    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *result;
    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;
    struct @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} *bm;
    LONG x0,y0,x1,y1;
    LONG flags;
    struct @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} *bm2;

FUNCTION
    Create a new @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} of position and size (x0,y0)->(x1,y1)
    Make this layer of type found in flags.
    If SuperBitMap, use bm2 as pointer to real SuperBitMap,
    and copy contents of Superbitmap into display layer.
    If this layer is a backdrop layer then place it behind all
    other layers including other backdrop layers. If this is
    not a backdrop layer then place it behind all nonbackdrop
    layers.

    Note: when using SUPERBITMAP, you should also set LAYERSMART flag.

INPUTS
    li - pointer to LayerInfo structure
    bm - pointer to common @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} used by all Layers
    x0,y0 - upper left hand corner of layer
    x1,y1 - lower right hand corner of layer
    flags - various types of layers supported as bit sets.
            (for bit definitions, see @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0} )
    bm2 - pointer to optional Super @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35}

RESULTS
    result - pointer to @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} structure if successful
             NULL if not successful

BUGS

SEE ALSO
    @{"DeleteLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DeleteLayer()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}, @{"graphics/gfx.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 0}

@EndNode

@Node "CreateUpfrontLayer()" "layers.library/CreateUpfrontLayer"

NAME
    CreateUpfrontLayer -- Create a new layer on top of existing layers.

SYNOPSIS
    result = CreateUpfrontLayer(li,bm,x0,y0,x1,y1,flags [,bm2])
    d0                          a0 a1 d0 d1 d2 d3   d4  [ a2 ]

    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *result;
    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;
    struct @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} *bm;
    LONG x0,y0,x1,y1;
    LONG flags;
    struct @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} *bm2;

FUNCTION
    Create a new @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} of position and size (x0,y0)->(x1,y1)
    and place it on top of all other layers.
    Make this layer of type found in flags
    if SuperBitMap, use bm2 as pointer to real SuperBitMap.
    and copy contents of Superbitmap into display layer.

    Note: when using SUPERBITMAP, you should also set LAYERSMART flag.

INPUTS
    li - pointer to LayerInfo structure
    bm - pointer to common @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} used by all Layers
    x0,y0 - upper left hand corner of layer
    x1,y1 - lower right hand corner of layer
    flags - various types of layers supported as bit sets.
    bm2 - pointer to optional Super @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35}

RESULTS
    result - pointer to @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} structure if successful
             NULL if not successful

BUGS

SEE ALSO
    @{"DeleteLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DeleteLayer()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}, @{"graphics/gfx.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 0}

@EndNode

@Node "DeleteLayer()" "layers.library/DeleteLayer"

NAME
    DeleteLayer -- delete layer from layer list.

SYNOPSIS
    result = DeleteLayer( dummy, l )
    d0                    a0,    a1

    BOOLEAN result;
    LONG dummy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;

FUNCTION
    Remove this layer from the list of layers.  Release memory
    associated with it.  Restore other layers that may have been
    obscured by it.  Trigger refresh in those that may need it.
    If this is a superbitmap layer make sure SuperBitMap is current.
    The SuperBitMap is not removed from the system but is available
    for program use even though the rest of the layer information has
    been deallocated.

INPUTS
    dummy - unused
    l - pointer to a layer

RESULTS
    result - TRUE if this layer successfully deleted from the system
             FALSE if layer not deleted. (probably out of memory )

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "DisposeLayerInfo()" "layers.library/DisposeLayerInfo"

NAME
    DisposeLayerInfo -- Return all memory for LayerInfo to memory pool

SYNOPSIS
    DisposeLayerInfo(li)
                     a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;

FUNCTION
    return LayerInfo and any other memory attached to this LayerInfo
    to memory allocator.

    Note: if you wish to delete the layers associated with this @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31}
        structure, remember to call @{"DeleteLayer()" Link "DeleteLayer()"} for each of the layers
        before calling DisposeLayerInfo().

INPUTS
    li - pointer to LayerInfo structure

EXAMPLE
    -- delete the layers associated this @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure --

    DeleteLayer(li,simple_layer);
    DeleteLayer(li,smart_layer);

    - see documentation on @{"DeleteLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DeleteLayer()"} about deleting SuperBitMap layers -
    my_super_bitmap_ptr = super_layer->SuperBitMap;
    DeleteLayer(li,super_layer);

    -- now dispose of the @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure itself --
    DisposeLayerInfo(li);

BUGS

SEE ALSO
    @{"DeleteLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DeleteLayer()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "EndUpdate()" "layers.library/EndUpdate"

NAME
    EndUpdate -- remove damage list and restore state of layer to normal.

SYNOPSIS
    EndUpdate( l, flag )
               a0  d0

    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;
    USHORT flag;

FUNCTION
    After the programmer has redrawn his picture he calls this
    routine to restore the ClipRects to point to his standard
    layer tiling. The layer is then unlocked for access by the
    layer library.

    Note: use flag = FALSE if you are only making a partial update.
        You may use the other region functions (graphics functions such as
        @{"OrRectRegion" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/OrRectRegion()"}, @{"AndRectRegion" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/AndRectRegion()"}, and @{"XorRectRegion" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/XorRectRegion()"} ) to clip adjust
        the DamageList to reflect a partial update.

INPUTS
    l - pointer to a layer
    flag - use TRUE if update was completed. The damage list is cleared.
           use FALSE if update not complete. The damage list is retained.

EXAMPLE
    -- begin update for first part of two-part refresh --
    BeginUpdate(my_layer);

    -- do some refresh, but not all --
    my_partial_refresh_routine(my_layer);

    -- end update, false (not completely done refreshing yet) --
    EndUpdate(my_layer, FALSE);

    -- begin update for last part of refresh --
    BeginUpdate(my_layer);

    -- do rest of refresh --
    my_complete_refresh_routine(my_layer);

    -- end update, true (completely done refreshing now) --
    EndUpdate(my_layer, TRUE);

BUGS

SEE ALSO
    @{"BeginUpdate" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/BeginUpdate()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "FattenLayerInfo()" "layers.library/FattenLayerInfo"

NAME
    FattenLayerInfo -- convert 1.0 LayerInfo to 1.1 LayerInfo
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

SYNOPSIS
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE
    FattenLayerInfo(li)
                    a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

FUNCTION
    V1.1 software and any later releases need to have more info in the
    @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure. To do this in a 1.0 supportable manner requires
    allocation and deallocation of the memory whenever most
    layer library functions are called.  To prevent unnecessary
    allocation/deallocation FattenLayerInfo will preallocate the
    necessary data structures and fake out the layer library into
    thinking it has a LayerInfo gotten from @{"NewLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/NewLayerInfo()"}.
    @{"NewLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/NewLayerInfo()"} is the approved method for getting this structure.
    When a program needs to give up the LayerInfo structure it
    must call @{"ThinLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/ThinLayerInfo()"} before freeing the memory. @{"ThinLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/ThinLayerInfo()"}
    is not necessary if @{"New/DisposeLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DisposeLayerInfo()"} are used however.

INPUTS
    li - pointer to LayerInfo structure

BUGS

SEE ALSO
    @{"NewLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/NewLayerInfo()"}, @{"ThinLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/ThinLayerInfo()"}, @{"DisposeLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DisposeLayerInfo()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "InitLayers()" "layers.library/InitLayers"

NAME
    InitLayers -- Initialize @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

SYNOPSIS
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE
    InitLayers(li)
               a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

FUNCTION
    Initialize @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure in preparation to use
    other layer operations on this list of layers.
    Make the Layers unlocked (open), available to layer operations.

INPUTS
    li - pointer to LayerInfo structure

BUGS

SEE ALSO
    @{"NewLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/NewLayerInfo()"}, @{"DisposeLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DisposeLayerInfo()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "InstallClipRegion()" "layers.library/InstallClipRegion"

NAME
    InstallClipRegion -- Install clip region in layer

SYNOPSIS
    oldclipregion = InstallClipRegion( l,  region )
    d0                                 a0  a1

    struct @{"Region" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/regions.h/Main" 22} *oldclipregion;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;
    struct @{"Region" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/regions.h/Main" 22} *region;

FUNCTION
    Installs a transparent Clip region in the layer. All
    subsequent graphics calls will be clipped to this region.
    You MUST remember to call InstallClipRegion(l,NULL) before
    calling DeleteLayer(l) or the Intuition function @{"CloseWindow()" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/intuition/CloseWindow()"}
    if you have installed a non-NULL ClipRegion in l.

INPUTS
    l - pointer to a layer
    region - pointer to a region

RESULTS
    oldclipregion - The pointer to the previous ClipRegion that
        was installed. Returns NULL if no previous ClipRegion installed.

        Note: If the system runs out of memory while computing the
            resulting ClipRects the LAYERS_CLIPRECTS_LOST bit will
            be set in l->Flags.

BUGS
    If the system runs out of memory during normal layer operations,
    the @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} list may get swept away and not restored.
    As soon as there is enough memory and the layer library
    gets called again the @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} list will be rebuilt.

SEE ALSO
    @{"BeginUpdate" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/BeginUpdate()"} @{"EndUpdate" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/EndUpdate()"},
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}, @{"graphics/regions.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/regions.h/Main" 0}

@EndNode

@Node "LockLayer()" "layers.library/LockLayer"

NAME
    LockLayer -- Lock layer to make changes to ClipRects.

SYNOPSIS
    LockLayer( dummy, l )
               a0     a1

    LONG dummy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;

FUNCTION
    Make this layer unavailable for other tasks to use.
    If another task is already using this layer then wait for
    it to complete and then reserve the layer for your own use.
    (this function does the same thing as graphics.library/LockLayerRom)

    Note: if you wish to lock MORE THAN ONE layer at a time, you
        must call @{"LockLayerInfo()" Link "LockLayerInfo()"} before locking those layers and
        then call @{"UnlockLayerInfo()" Link "UnlockLayerInfo()"} when you have finished. This
        is to prevent system "deadlocks".

    Further Note: while you hold the lock on a layer, Intuition will block
        on operations such as windowsizing, dragging, menus, and depth
        arranging windows in this layer's screen.  It is recommended that
        YOU do not make Intuition function calls while the layer is locked.

INPUTS
    dummy - unused
    l - pointer to a layer

BUGS

SEE ALSO
    @{"UnlockLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/UnlockLayer()"}, @{"LockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/LockLayerInfo()"}, @{"UnlockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/UnlockLayerInfo()"},
    @{"graphics.library/LockLayerRom" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/graphics/LockLayerRom()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "LockLayerInfo()" "layers.library/LockLayerInfo"

NAME
    LockLayerInfo -- Lock the LayerInfo structure.

SYNOPSIS
    LockLayerInfo( li )
                   a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;

FUNCTION
    Before doing an operation that requires the LayerInfo
    structure, make sure that no other task is also using the
    LayerInfo structure.  LockLayerInfo() returns when the
    LayerInfo belongs to this task.  There should be
    an @{"UnlockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/UnlockLayerInfo()"} for every LockLayerInfo.

    Note: All layer routines presently LockLayerInfo() when they
    start up and @{"UnlockLayerInfo()" Link "UnlockLayerInfo()"} as they exit.  Programmers
    will need to use these Lock/Unlock routines if they wish
    to do something with the LayerStructure that is not
    supported by the layer library.

INPUTS
    li - pointer to @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure

BUGS

SEE ALSO
    @{"UnlockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/UnlockLayerInfo()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "LockLayers()" "layers.library/LockLayers"

NAME
    LockLayers -- lock all layers from graphics output.

SYNOPSIS
    LockLayers( li )
                a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;

FUNCTION
    First calls @{"LockLayerInfo()" Link "LockLayerInfo()"}
    Make all layers in this layer list locked.

INPUTS
    li - pointer to @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure

BUGS

SEE ALSO
    @{"LockLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/LockLayer()"}, @{"LockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/LockLayerInfo()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "MoveLayer()" "layers.library/MoveLayer"

NAME
    MoveLayer -- Move layer to new position in @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35}.

SYNOPSIS
    result = MoveLayer( dummy, l, dx, dy )
    d0                  a0     a1 d0  d1

    BOOLEAN result;
    LONG dummmy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;
    LONG dx,dy;

FUNCTION
    Move this layer to new position in shared @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35}.
    If any refresh layers become revealed, collect damage and
    set REFRESH bit in layer Flags.

INPUTS
    dummy - unused
    l - pointer to a nonbackdrop layer
    dx - delta to add to current x position
    dy - delta to add to current y position

RETURNS
    result - TRUE if operation successful
             FALSE if failed (out of memory)

BUGS
    May not handle (dx,dy) which attempts to move the layer ouside the
    layer's RastPort->BitMap bounds .

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "MoveLayerInFrontOf()" "layers.library/MoveLayerInFrontOf"

NAME
    MoveLayerInFrontOf-- Put layer in front of another layer.

SYNOPSIS
    result = MoveLayerInFrontOf( layertomove, targetlayer )
                                 a0           a1
    BOOLEAN result;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *layertomove;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *targetlayer;

FUNCTION
    Move this layer in front of target layer, swapping bits
    in and out of the display with other layers.
    If this is a refresh layer then collect damage list and
    set the LAYERREFRESH bit in layer->Flags if redraw required.

    Note: this operation may generate refresh events in other layers
       associated with this layer's @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure.

INPUTS
    layertomove - pointer to layer which should be moved
    targetlayer - pointer to target layer in front of which to move layer

RESULTS
    result = TRUE    if operation successful
             FALSE   if operation unsuccessful (probably out of memory)

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "NewLayerInfo()" "layers.library/NewLayerInfo"

NAME
    NewLayerInfo -- Allocate and Initialize full @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure.

SYNOPSIS
    result = NewLayerInfo()
    d0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *result;

FUNCTION
    Allocate memory required for full @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure.
    Initialize @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure in preparation to use
    other layer operations on this list of layers.
    Make the @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} unlocked (open).

INPUTS
    None

RESULT
    result- pointer to @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure if successful
            NULL if not enough memory

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "ScrollLayer()" "layers.library/ScrollLayer"

NAME
    ScrollLayer -- Scroll around in a superbitmap, translate coordinates
                  in non-superbitmap layer.

SYNOPSIS
    ScrollLayer( dummy, l, dx, dy )
                 a0     a1 d0  d1

    LONG dummy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;
    LONG dx,dy;

FUNCTION
    For a SuperBitMap Layer:
    Update the SuperBitMap from the layer display, then copy bits
    between @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} and SuperBitMap to reposition layer over different
    portion of SuperBitMap.
    For nonSuperBitMap layers, all (x,y) pairs are adjusted by
    the scroll(x,y) value in the layer.  To cause (0,0) to actually
    be drawn at (3,10) use ScrollLayer(-3,-10). This can be useful
    along with @{"InstallClipRegion" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/InstallClipRegion()"} to simulate Intuition GZZWindows
    without the overhead of an extra layer.

INPUTS
    dummy - unused
    l - pointer to a layer
    dx - delta to add to current x scroll value
    dy - delta to add to current y scroll value

BUGS
    May not handle (dx,dy) which attempts to move the layer ouside the
    layer's SuperBitMap bounds.

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "SizeLayer()" "layers.library/SizeLayer"

NAME
    SizeLayer -- Change the size of this nonbackdrop layer.

SYNOPSIS
    result = SizeLayer( dummy, l, dx, dy )
    d0                  a0     a1 d0  d1

    BOOLEAN result;
    LONG dummy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;
    LONG dx, dy;

FUNCTION
    Change the size of this layer by (dx,dy). The lower right hand
    corner is extended to make room for the larger layer.
    If there is SuperBitMap for this layer then copy pixels into
    or out of the layer depending on whether the layer increases or
    decreases in size.  Collect damage list for those layers that may
    need to be refreshed if damage occurred.

INPUTS
    dummy - unused
    l - pointer to a nonbackdrop layer
    dx - delta to add to current x size
    dy - delta to add to current y size

RESULTS
    result - TRUE if operation successful
             FALSE if failed (out of memory)

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "SwapBitsRastPortClipRect()" "layers.library/SwapBitsRastPortClipRect"

NAME
    SwapBitsRastPortClipRect -- Swap bits between common bitmap
                                and obscured @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53}

SYNOPSIS
    SwapBitsRastPortClipRect( rp, cr )
                              a0  a1

    struct @{"RastPort" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/rastport.h/Main" 49} *rp;
    struct @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} *cr;

FUNCTION
    Support routine useful for those that need to do some
    operations not done by the layer library.  Allows programmer
    to swap the contents of a small @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35} with a subsection of
    the display. This is accomplished without using extra memory.
    The bits in the display @{"RastPort" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/rastport.h/Main" 49} are exchanged with the
    bits in the ClipRect's @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35}.

    Note: the @{"ClipRect" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 53} structures which the layer library allocates are
    actually a little bigger than those described in the @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}
    include file.  So be warned that it is not a good idea to have
    instances of cliprects in your code.

INPUTS
    rp - pointer to rastport
    cr - pointer to cliprect to swap bits with

BUGS

SEE ALSO
    @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}, @{"graphics/rastport.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/rastport.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "ThinLayerInfo()" "layers.library/ThinLayerInfo"

NAME
    ThinLayerInfo -- convert 1.1 LayerInfo to 1.0 LayerInfo.
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

SYNOPSIS
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE
    ThinLayerInfo(li)
                  a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;
    OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

FUNCTION
    return the extra memory needed that was allocated with
    @{"FattenLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/FattenLayerInfo()"}. This is must be done prior to freeing
    the @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure itself. V1.1 software should be
    using @{"DisposeLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DisposeLayerInfo()"}.

INPUTS
    li - pointer to LayerInfo structure

BUGS

SEE ALSO
    @{"DisposeLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/DisposeLayerInfo()"}, @{"FattenLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/FattenLayerInfo()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "UnlockLayer()" "layers.library/UnlockLayer"

NAME
    UnlockLayer -- Unlock layer and allow graphics routines to use it.

SYNOPSIS
    UnlockLayer( l )
                 a0

    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;

FUNCTION
    When finished changing the ClipRects or whatever you were
    doing with this layer you must call UnlockLayer() to allow
    other tasks to proceed with graphic output to the layer.

INPUTS
    l - pointer to a layer

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 0}

@EndNode

@Node "UnlockLayerInfo()" "layers.library/UnlockLayerInfo"

NAME
    UnlockLayerInfo -- Unlock the LayerInfo structure.

SYNOPSIS
    UnlockLayerInfo( li )
                     a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;

FUNCTION
    After the operation is complete that required a @{"LockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/LockLayerInfo()"},
    unlock the LayerInfo structure so that  other tasks may
    affect the layers.

INPUTS
    li - pointer to the @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure

    BUGS

    SEE ALSO
    @{"LockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/LockLayerInfo()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "UnlockLayers()" "layers.library/UnlockLayers"

NAME
    UnlockLayers -- Unlock all layers from graphics output.
            Restart graphics output to layers that have been waiting

SYNOPSIS
    UnlockLayers( li )
                  a0

    struct @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} *li;

FUNCTION
    Make all layers in this layer list unlocked.
    Then call @{"UnlockLayerInfo" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/UnlockLayerInfo()"}

INPUTS
    li - pointer to the @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure

BUGS

SEE ALSO
    @{"LockLayers" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/LockLayers()"}, @{"UnlockLayer" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/layers/UnlockLayer()"}, @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "UpfrontLayer()" "layers.library/UpfrontLayer"

NAME
    UpfrontLayer -- Put layer in front of all other layers.

SYNOPSIS
    result = UpfrontLayer( dummy, l )
    do                     a0  a1

    BOOLEAN result;
    LONG dummy;
    struct @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} *l;

FUNCTION
    Move this layer to the most upfront position swapping bits
    in and out of the display with other layers.
    If this is a refresh layer then collect damage list and
    set the LAYERREFRESH bit in layer->Flags if redraw required.
    By clearing the BACKDROP bit in the layers Flags you may
    bring a Backdrop layer up to the front of all other layers.

    Note: this operation may generate refresh events in other layers
       associated with this layer's @{"Layer_Info" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 31} structure.

INPUTS
    dummy - unused
    l - pointer to a nonbackdrop layer

RESULTS
    result - TRUE   if operation successful
             FALSE  if operation unsuccessful (probably out of memory)

BUGS

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

@Node "WhichLayer()" "layers.library/WhichLayer"

NAME
    WhichLayer -- Which @{"Layer" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/clip.h/Main" 24} is this point in?

SYNOPSIS
    layer = WhichLayer( li, x, y )
    d0                  a0  d0 d1

FUNCTION
    Starting at the topmost layer check to see if this point (x,y)
        occurs in this layer.  If it does return the pointer to this
        layer. Return NULL if there is no layer at this point.

INPUTS
    li  = pointer to LayerInfo structure
    (x,y)   = coordinate in the @{"BitMap" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/gfx.h/Main" 35}

RESULTS
    layer - pointer to the topmost layer that this point is in
            NULL if this point is not in a layer

SEE ALSO
    @{"graphics/layers.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/graphics/layers.h/Main" 0}

@EndNode

