@database "layers"
@master "AMIDEV:NDK/Autodocs/layers.doc"

@Node Main "layers.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" AllocClipRect() " Link "AllocClipRect()"}
    @{" BeginUpdate() " Link "BeginUpdate()"}
    @{" BehindLayer() " Link "BehindLayer()"}
    @{" CreateBehindHookLayer() " Link "CreateBehindHookLayer()"}
    @{" CreateBehindLayer() " Link "CreateBehindLayer()"}
    @{" CreateUpfrontHookLayer() " Link "CreateUpfrontHookLayer()"}
    @{" CreateUpfrontLayer() " Link "CreateUpfrontLayer()"}
    @{" DeleteLayer() " Link "DeleteLayer()"}
    @{" DisposeLayerInfo() " Link "DisposeLayerInfo()"}
    @{" DoHookClipRects() " Link "DoHookClipRects()"}
    @{" EndUpdate() " Link "EndUpdate()"}
    @{" FattenLayerInfo() " Link "FattenLayerInfo()"}
    @{" FreeClipRect() " Link "FreeClipRect()"}
    @{" HideLayer() " Link "HideLayer()"}
    @{" InitLayers() " Link "InitLayers()"}
    @{" InstallClipRegion() " Link "InstallClipRegion()"}
    @{" InstallLayerHook() " Link "InstallLayerHook()"}
    @{" InstallLayerInfoHook() " Link "InstallLayerInfoHook()"}
    @{" LayerOccluded() " Link "LayerOccluded()"}
    @{" LockLayer() " Link "LockLayer()"}
    @{" LockLayerInfo() " Link "LockLayerInfo()"}
    @{" LockLayers() " Link "LockLayers()"}
    @{" MoveLayer() " Link "MoveLayer()"}
    @{" MoveLayerInFrontOf() " Link "MoveLayerInFrontOf()"}
    @{" MoveSizeLayer() " Link "MoveSizeLayer()"}
    @{" NewLayerInfo() " Link "NewLayerInfo()"}
    @{" ScrollLayer() " Link "ScrollLayer()"}
    @{" SetLayerInfoBounds() " Link "SetLayerInfoBounds()"}
    @{" ShowLayer() " Link "ShowLayer()"}
    @{" SizeLayer() " Link "SizeLayer()"}
    @{" SortLayerCR() " Link "SortLayerCR()"}
    @{" SwapBitsRastPortClipRect() " Link "SwapBitsRastPortClipRect()"}
    @{" ThinLayerInfo() " Link "ThinLayerInfo()"}
    @{" UnlockLayer() " Link "UnlockLayer()"}
    @{" UnlockLayerInfo() " Link "UnlockLayerInfo()"}
    @{" UnlockLayers() " Link "UnlockLayers()"}
    @{" UpfrontLayer() " Link "UpfrontLayer()"}
    @{" WhichLayer() " Link "WhichLayer()"}
@EndNode

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

@{b}    NAME@{ub}
       AllocClipRect -- build a @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95}

@{b}    SYNOPSIS@{ub}
       cliprect = AllocClipRect( li )
       d0                        a0

       struct @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} *AllocClipRect( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);

@{b}    FUNCTION@{ub}
       This function allocates a new @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} from a @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}
       structure and returns a pointer to the @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95}. The
       @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} is inialized up to the cliprect bounds.
       NOTE THAT THIS FUNCTION IS PRIVATE. You should never
       play with layer cliprects yourself and never attach
       this cliprect to a layer yourself.
       This cliprect belongs to the given @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure
       and must be released before the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} gets released.

@{b}    INPUTS@{ub}
       li - pointer to a @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} to allocate the @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95}
       from.

@{b}    RESULTS@{ub}
       cliprect - a pointer to a @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} structure or @{"NULL" Link "rexxsupport/NULL"}
                  in case the system run out of memory.

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"layers/FreeClipRect()" Link "FreeClipRect()"}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       BeginUpdate -- Prepare to repair damaged layer.

@{b}    SYNOPSIS@{ub}
       result = BeginUpdate( l )
       d0                    a0

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} BeginUpdate( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       Convert damage list to @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} 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.

@{b}    INPUTS@{ub}
       l - pointer to a layer

@{b}    RESULTS@{ub}
       result - TRUE if damage list converted to @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} list successfully.
                FALSE if list conversion aborted. (probably out of memory)

@{b}    BUGS@{ub}
       If BeginUpdate returns FALSE, programmer must abort the attempt to
       refresh this layer and instead call EndUpdate( l, FALSE ) to restore
       original @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} and damage list.

@{b}    SEE ALSO@{ub}
       @{"EndUpdate" Link "layers/EndUpdate()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       BehindLayer -- Put layer behind other layers.

@{b}    SYNOPSIS@{ub}
       result = BehindLayer( dummy, l )
       d0                    a0     a1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} BehindLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       @{"Move" Link "graphics/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 "INCLUDE:graphics/layers.h/Main" 54} structure.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a layer

@{b}    RESULTS@{ub}
       result - TRUE    if operation successful
                FALSE   if operation unsuccessful (probably out of memory)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME                                                              (V36)@{ub}
       CreateBehindHookLayer -- Create a layer behind all existing layers
                                using supplied callback BackFill hook.

@{b}    SYNOPSIS@{ub}
       result = CreateBehindHookLayer(li,bm,x0,y0,x1,y1,flags,hook,[,bm2])
       d0                             a0 a1 d0 d1 d2 d3 d4    a3   [ a2 ]

       struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *CreateBehindHookLayer(struct Layer_Info*,struct BitMap*,
           @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *, ... );

@{b}    FUNCTION@{ub}
       Create a new @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} of position and size (x0,y0)->(x1,y1)
       Make this layer of type found in flags.
       Install Layer->BackFill callback @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26}.
       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.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure
       bm - pointer to common @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} 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 "INCLUDE:graphics/layers.h/Main" 0} )
       hook -  Layer->BackFill callback @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} (see @{"InstallLayerHook()" Link "InstallLayerHook()"})

               If hook is LAYERS_BACKFILL, the default backfill is
               used for the layer.  (Same as pre-2.0)

               As of V39:
               If hook is LAYERS_NOBACKFILL, the layer will not be
               backfilled (NO-OP).

       bm2 - pointer to optional Super @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}

@{b}    RESULTS@{ub}
       result - pointer to @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} structure if successful
                @{"NULL" Link "rexxsupport/NULL"} if not successful

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"InstallLayerHook" Link "layers/InstallLayerHook()"}, @{"DeleteLayer" Link "layers/DeleteLayer()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0},
       @{"graphics/gfx.h" Link "INCLUDE:graphics/gfx.h/Main" 0}, @{"utility/hooks.h" Link "INCLUDE:utility/hooks.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       CreateBehindLayer -- Create a new layer behind all existing layers.

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

       struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *CreateBehindLayer(struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *, struct @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} *,
           @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, ... );

@{b}    FUNCTION@{ub}
       Create a new @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} 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.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure
       bm - pointer to common @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} 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 "INCLUDE:graphics/layers.h/Main" 0} )
       bm2 - pointer to optional Super @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}

@{b}    RESULTS@{ub}
       result - pointer to @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} structure if successful
                @{"NULL" Link "rexxsupport/NULL"} if not successful

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"DeleteLayer" Link "layers/DeleteLayer()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}, @{"graphics/gfx.h" Link "INCLUDE:graphics/gfx.h/Main" 0}

@EndNode

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

@{b}    NAME                                                              (V36)@{ub}
       CreateUpfrontHookLayer -- Create a layer on top of existing layers
                                 using supplied callback BackFill hook.

@{b}    SYNOPSIS@{ub}
       result = CreateUpfrontHookLayer(li,bm,x0,y0,x1,y1,flags,hook,[,bm2])
       d0                              a0 a1 d0 d1 d2 d3   d4  a3   [ a2 ]

       struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *CreateUpfrontHookLayer(struct Layer_Info*,struct BitMap*
,
           @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *, ... );

@{b}    FUNCTION@{ub}
       Create a new @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} 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
       Install Layer->BackFill callback hook.
       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.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure
       bm - pointer to common @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} 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.
       hook -  Layer->BackFill callback @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} (see @{"InstallLayerHook()" Link "InstallLayerHook()"})

               If hook is LAYERS_BACKFILL, the default backfill is
               used for the layer.  (Same as pre-2.0)

               As of V39:
               If hook is LAYERS_NOBACKFILL, the layer will not be
               backfilled (NO-OP).

       bm2 - pointer to optional Super @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}

@{b}    RESULTS@{ub}
       result - pointer to @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} structure if successful
                @{"NULL" Link "rexxsupport/NULL"} if not successful

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"InstallLayerHook" Link "layers/InstallLayerHook()"}, @{"DeleteLayer" Link "layers/DeleteLayer()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0},
       @{"graphics/gfx.h" Link "INCLUDE:graphics/gfx.h/Main" 0}, @{"utility/hooks.h" Link "INCLUDE:utility/hooks.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       CreateUpfrontLayer -- Create a new layer on top of existing layers.

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

       struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *CreateUpfrontLayer(struct Layer_Info*,struct @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} *,
           @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, ... );

@{b}    FUNCTION@{ub}
       Create a new @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} 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.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure
       bm - pointer to common @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} 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 "INCLUDE:graphics/gfx.h/Main" 61}

@{b}    RESULTS@{ub}
       result - pointer to @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} structure if successful
                @{"NULL" Link "rexxsupport/NULL"} if not successful

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"DeleteLayer" Link "layers/DeleteLayer()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}, @{"graphics/gfx.h" Link "INCLUDE:graphics/gfx.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       DeleteLayer -- delete layer from layer list.

@{b}    SYNOPSIS@{ub}
       result = DeleteLayer( dummy, l )
       d0                    a0,    a1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} DeleteLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       @{"Remove" Link "exec/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.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a layer

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       DisposeLayerInfo -- Return all memory for LayerInfo to memory pool

@{b}    SYNOPSIS@{ub}
       DisposeLayerInfo( li )
                         a0

       void DisposeLayerInfo( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);

@{b}    FUNCTION@{ub}
       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 "INCLUDE:graphics/layers.h/Main" 54}
           structure, remember to call @{"DeleteLayer()" Link "DeleteLayer()"} for each of the layers
           before calling DisposeLayerInfo().

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure

@{b}    EXAMPLE@{ub}

       -- delete the layers associated this @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure --

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

       -- see docs on @{"DeleteLayer" Link "layers/DeleteLayer()"} about deleting SuperBitMap layers --
       my_super_bitmap_ptr = super_layer->SuperBitMap;
       DeleteLayer(li,super_layer);

       -- now dispose of the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure itself --
       DisposeLayerInfo(li);


@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"DeleteLayer" Link "layers/DeleteLayer()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       DoHookClipRects - Do the given hook for each of the ClipRects    (V39)

@{b}    SYNOPSIS@{ub}
       DoHookClipRects(hook,rport,rect)
                       a0   a1    a2

       void DoHookClipRects(struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *,struct @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} *,
                            struct @{"Rectangle" Link "INCLUDE:graphics/gfx.h/Main" 41} *);

@{b}    FUNCTION@{ub}
       This function will call the given hook for each cliprect in the
       layer that can be rendered into.  This is how the backfill hook
       in Layers is implemented.  This means that hidden simple-refresh
       cliprects will be ignored.  It will call the SuperBitMap cliprects,
       smart refresh off-screen cliprects, and all on screen cliprects.
       If the rect parameter is not @{"NULL" Link "rexxsupport/NULL"}, the cliprects are bounded to
       the rectangle given.

@{b}    INPUTS@{ub}
       hook - pointer to layer callback @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} which will be called
              with object == (struct @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} *) result->RastPort
              and message == [ (Layer *) layer, (struct Rectangle) bounds,
                               (LONG) offsetx, (LONG) offsety ]

              This hook should fill the @{"Rectangle" Link "INCLUDE:graphics/gfx.h/Main" 41} in the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}
              with the BackFill pattern appropriate for offset x/y.

              If hook is LAYERS_BACKFILL, the default backfill is
              used for the layer.

              If hook is LAYERS_NOBACKFILL, the layer will not be
              backfilled (NO-OP).

       rport- A pointer to the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} that is to be operated on.
              This function will lock the layer if the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} is
              layered...
              If the rport is non-layered your hook will be called with
              the rectangle as passed, the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}, and a @{"NULL" Link "rexxsupport/NULL"} layer...

       rect - The bounding rectangle that should be used on the layer.
              This rectangle "clips" the cliprects to the bound given.
              If this is @{"NULL" Link "rexxsupport/NULL"}, no bounding will take place.
              *MUST* not be @{"NULL" Link "rexxsupport/NULL"} if the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} is non-layered!

@{b}    NOTES@{ub}
       The @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} you are passed back is the same one passed to the
       function.  You should *not* use "layered" rendering functions
       on this @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}.  Generally, you will wish to do @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} operations
       such as @{"BltBitMap()" Link "graphics/BltBitMap()"}.  The callback is a raw, low-level rendering
       call-back.  If you need to call a rendering operation with a
       @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}, make sure you use a copy of the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} and @{"NULL" Link "rexxsupport/NULL"} the
       @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} pointer.

@{b}    SEE ALSO@{ub}
       @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0} @{"utility/hooks.h" Link "INCLUDE:utility/hooks.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       EndUpdate -- remove damage list and restore state of layer to normal.

@{b}    SYNOPSIS@{ub}
       EndUpdate( l, flag )
                  a0  d0

       void EndUpdate( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, UWORD);

@{b}    FUNCTION@{ub}
       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 "graphics/OrRectRegion()"}, @{"AndRectRegion" Link "graphics/AndRectRegion()"}, and @{"XorRectRegion" Link "graphics/XorRectRegion()"} ) to clip adjust
       the DamageList to reflect a partial update.

@{b}    INPUTS@{ub}
       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.

@{b}    EXAMPLE@{ub}

       -- 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);

@{b}    BUGS@{ub}
       In V40 or below, EndUpdate() could have failed to re-install
       the user clip region in low-memory situations. This has been
       fixed for V45. V45 may leave the layer cliprects in sub-
       optimal, but valid stage if it runs low on memory.

@{b}    SEE ALSO@{ub}
       @{"BeginUpdate" Link "layers/BeginUpdate()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       FattenLayerInfo -- convert 1.0 LayerInfo to 1.1 LayerInfo
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    SYNOPSIS@{ub}
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE
       FattenLayerInfo( li )
                        a0

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} FattenLayerInfo( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    FUNCTION@{ub}
       As of V45, this function does nothing and returns TRUE. V45 no
       longer requires additional information in the Layers_Info, but
       nevertheless, this function *MUST NOT* be used for new code.
       In case the system (Intuition, namely) must roll its own
       @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}, it is mandatory to call @{"ThinLayerInfo()" Link "ThinLayerInfo()"} if you are
       done with it as it releases some additional internal buffers.
       @{"NewLayerInfo" Link "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 "layers/ThinLayerInfo()"} before freeing the memory. @{"ThinLayerInfo" Link "layers/ThinLayerInfo()"}
       is not necessary if @{"New/DisposeLayerInfo" Link "layers/DisposeLayerInfo()"} are used however.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}

       @{"NewLayerInfo" Link "layers/NewLayerInfo()"}, @{"ThinLayerInfo" Link "layers/ThinLayerInfo()"}, @{"DisposeLayerInfo" Link "layers/DisposeLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       FreeClipRect -- release a @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} build by @{"AllocClipRect" Link "layers/AllocClipRect()"}

@{b}    SYNOPSIS@{ub}
       FreeClipRect( li, cliprect )
                     a0     a1

       void FreeClipRect( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *li, struct @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} *cr);

@{b}    FUNCTION@{ub}
       Disposes a @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} that is no longer required by the caller.
       The @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} is either released immedately into the free memory
       pool, or gets recycled by layers as soon as clipping operations
       are performed in the same @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}.

       This function also releases the @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} linked to by the @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95}.
       In case you disposed this bitmap already, make sure that you
       @{"NULL" Link "rexxsupport/NULL"} cr->BitMap before calling this function.

       NOTE THAT THIS FUNCTION IS PRIVATE. You should never
       play with layer cliprects yourself and never attach
       this cliprect to a layer yourself.

@{b}    INPUTS@{ub}
       li - pointer to a @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} the @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} has been allocated
       from by means of @{"AllocClipRect()" Link "AllocClipRect()"}

@{b}    RESULTS@{ub}

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"layers/AllocClipRect()" Link "AllocClipRect()"}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       HideLayer -- Make layer invisible (V45)

@{b}    SYNOPSIS@{ub}
       result = HideLayer( l )
       d0                 a0

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} HideLayer( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       @{"Move" Link "graphics/Move()"} this layer behind the bottommost layer and make all
       of its cliprects invisible. For LAYERSMART layers, copy
       all image data into the backing store of the layer.
       This operation may generate refresh events in other layers
       associated with this layer's @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure.

@{b}    INPUTS@{ub}
       l - pointer to a layer

@{b}    RESULTS@{ub}
       result - TRUE   if operation successful
                FALSE  if operation unsuccessful (probably out of memory)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       InitLayers -- Initialize @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    SYNOPSIS@{ub}
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE
       InitLayers( li )
                   a0

       void InitLayers( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    FUNCTION@{ub}
       Initialize @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure in preparation to use
       other layer operations on this list of layers.
       Make the Layers unlocked (open), available to layer operations.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"NewLayerInfo" Link "layers/NewLayerInfo()"}, @{"DisposeLayerInfo" Link "layers/DisposeLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       InstallClipRegion -- Install clip region in layer

@{b}    SYNOPSIS@{ub}
       oldclipregion = InstallClipRegion( l,  region )
       d0                                 a0  a1

       struct @{"Region" Link "INCLUDE:graphics/regions.h/Main" 25} *InstallClipRegion( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, struct @{"Region" Link "INCLUDE:graphics/regions.h/Main" 25} *);

@{b}    FUNCTION@{ub}
       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 "intuition/CloseWindow()"}
       if you have installed a non-NULL ClipRegion in l.

@{b}    INPUTS@{ub}
       l - pointer to a layer
       region - pointer to a region

@{b}    RESULTS@{ub}
       oldclipregion - The pointer to the previous ClipRegion that
       was installed. Returns @{"NULL" Link "rexxsupport/NULL"} if no previous ClipRegion installed.

       Returns "region" in case it could not install the user clip
       region, for example because it run out of memory.

@{b}    NOTES@{ub}
       In V44 and before, if the system runs out of memory during this
       function, it would not install the user cliprect, but would also
       swep away the previously installed cliprect, hence would leave
       the layer completely unclipped. This has been fixed in V45.
       Note that you should therefore check the result code against
       your clip region. In case they are equal, the clip region
       could not be installed.
       Removing a cliprect (i.e. installing NULL) will always work.

@{b}    BUGS@{ub}
       If you try to remove a user clip rect while the layer is
       updating, i.e. @{"BeginUpdate()" Link "BeginUpdate()"} has been called, then this
       function may erraneously insert cliprects that are not
       part of the damage list into the layer if layers runs low
       on memory. Note that calling InstallClipRegion() under
       this condition is discouraged.
       If this function runs low on memory for removing a clip
       region otherwise, the resulting layer will be still in valid
       state, but the cliprect layout may be sub-optimal. This gets
       fixed on the next layer resize or depth-arrange operation.

@{b}    SEE ALSO@{ub}
       @{"BeginUpdate" Link "layers/BeginUpdate()"} @{"EndUpdate" Link "layers/EndUpdate()"},
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}, @{"graphics/regions.h" Link "INCLUDE:graphics/regions.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       InstallLayerHook -- safely install a new Layer->BackFill hook.(V36)

@{b}    SYNOPSIS@{ub}
       oldhook = InstallLayerHook( layer, hook )
       d0                          a0     a1

       struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *InstallLayerHook( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *);

@{b}    FUNCTION@{ub}
       Installs a new Layer->Backfill @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26}, waiting until it is safe to do
       so. Locks the layer while substituting the new @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} and removing the
       old one. If a new @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} is not provided, will install the default layer
       BackFill @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26}.

@{b}    INPUTS@{ub}
       layer - pointer to the layer in which to install the Backfill @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26}.
       hook -  pointer to layer callback @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} which will be called
               with object == (struct @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} *) result->RastPort
               and message == [ (Layer *) layer, (struct Rectangle) bounds,
                                (LONG) offsetx, (LONG) offsety ]

               This hook should fill the @{"Rectangle" Link "INCLUDE:graphics/gfx.h/Main" 41} in the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}
               with the BackFill pattern appropriate for offset x/y.

               If hook is LAYERS_BACKFILL, the default backfill is
               used for the layer.  (Same as pre-2.0)

               As of V39:
               If hook is LAYERS_NOBACKFILL, the layer will not be
               backfilled (NO-OP).

@{b}    RESULTS@{ub}
       oldhook - pointer to the Layer->BackFill @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} that was previously
                 active.  Returns @{"NULL" Link "rexxsupport/NULL"} if it was the default hook.
                 In V39, it could return 1 if there was no hook.

@{b}    EXAMPLE@{ub}
       The following hook is a very simple example that does rather little
       but gives the basis idea of what is going on.

       *
       * This is the code called by the layer hook...
       * Note that some other setup is required for this to work, including
       * the definition of the PrivateData structure (pd_...) and the
       * definition of the BitMapPattern structure (bmp_...)
       *
       CoolHook:       xdef    CoolHook
                       movem.l d2-d7/a3-a6,-(sp) ; Save these...
                       move.l  h_SubEntry(a0),a4 ; (my private data #1 here)
                       move.l  h_Data(a0),a5     ; Put data into address reg
       *
       * Now, we do the rendering...
       * Note that the layer may not be important...  But it is here...
       *
                       move.l  (a1)+,a0          ; Get the layer...
       *
       * a1 now points at the rectangle...
       *
                       move.l  pd_GfxBase(a4),a6 ; Point at @{"GfxBase" Link "INCLUDE:graphics/gfxbase.h/Main" 25}
                       move.l  bmp_Pattern(a5),d0; Get PatternBitMap
                       beq     SimpleCase        ; None?  Simple (0) case
       *
       * Now do the complex case of a pattern...
       *
                       move.l  a1,a3             ; Pointer to rectangle
                       addq.l  #8,a1             ; Get past rectangle
                       move.l  (a1)+,d2          ; X Offset (For pattern)
                       move.l  (a1)+,d3          ; Y Offset
               ;
               ; Whatever complex blitting you would do in the complex case
               ; goes here
               ;
       *
       * No bitmap, so just do the simple (0) minterm case...
       *
       SimpleCase:     moveq.l #0,d2             ; Clear d2
                       move.w  ra_MinX(a1),d2    ; Get X pos
       *
                       moveq.l #0,d3
                       move.w  ra_MinY(a1),d3    ; Get Y pos
       *
                       moveq.l #0,d4
                       move.w  ra_MaxX(a1),d4
                       sub.l   d2,d4
                       addq.l  #1,d4             ; Get X size
       *
                       moveq.l #0,d5
                       move.w  ra_MaxY(a1),d5
                       sub.l   d3,d5
                       addq.l  #1,d5             ; Get Y size
       *
                       move.l  d2,d0             ; X Source
                       move.l  d3,d1             ; Y Source
                       moveq.l #0,d6             ; @{"NULL" Link "rexxsupport/NULL"} minterm
                       moveq.l #-1,d7            ; FF mask
       *
                       move.l  rp_BitMap(a2),a1  ; Get bitmap
                       move.l  a1,a0
                       CALLSYS @{"BltBitMap" Link "graphics/BltBitMap()"}         ; Do the backfill-0
       *
       HookDone:       movem.l (sp)+,d2-d7/a3-a6 ; Restore
                       rts

@{b}    NOTES@{ub}
       The @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} you are passed back is the same one passed to the
       function.  You should *not* use "layered" rendering functions
       on this @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}.  Generally, you will wish to do @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} operations
       such as @{"BltBitMap()" Link "graphics/BltBitMap()"}.  The callback is a raw, low-level rendering
       call-back.  If you need to call a rendering operation with a
       @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}, make sure you use a copy of the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} and @{"NULL" Link "rexxsupport/NULL"} the
       @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} pointer.

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0} @{"utility/hooks.h" Link "INCLUDE:utility/hooks.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       InstallLayerInfoHook - Install a backfill hook for non-layer (V39)

@{b}    SYNOPSIS@{ub}
       oldhook=InstallLayerInfoHook(li,hook)
       d0                           a0 a1

       struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *InstallLayerInfoHook(struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *,struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *);

@{b}    FUNCTION@{ub}
       This function will install a backfill hook for the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}
       structure passed.  This backfill hook will be used to clear the
       background area where no layer exists.  The hook function is
       passed the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} and the bounds just like the layer backfill
       hook.  Note that this hook could be called for any layer.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure

       hook -  pointer to layer callback @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} which will be called
           with object == (struct @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} *) result->RastPort
           and message == [ (ULONG) undefined, (struct Rectangle) bounds ]

               This hook should fill the @{"Rectangle" Link "INCLUDE:graphics/gfx.h/Main" 41} in the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}
               with the BackFill pattern appropriate for rectangle given.

               If hook is LAYERS_BACKFILL, the default backfill is
               used.  (Same as pre-2.0)

               If hook is LAYERS_NOBACKFILL, there will be no
               backfill.  (NO-OP).

@{b}    RESULTS@{ub}
       oldhook - Returns the backfill hook that was in the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}.
                 Returns LAYERS_BACKFILL if the default was installed.
                 Returns LAYERS_NOBACKFILL if there was a NO-OP hook.
                 Returns -1 if there was some failure.

@{b}    EXAMPLE@{ub}
       See the example in @{"InstallLayerHook" Link "layers/InstallLayerHook()"}.  Note that both the @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40}
       pointer and the OffsetX/Y values are not available in the
       LayerInfo backfill hook.

@{b}    NOTES@{ub}
       When the hook is first installed, it is *NOT* called.  It is up
       to the application to know if it is safe to fill in the area.
       Since the hook will be called when a layer is deleted, the easiest
       way to have layers call this hook is to create and delete a backdrop
       layer that is the size of the area.

       Also, note that currently the first long word of the hook message
       contains an undefined value. This value may look like a layer
       pointer. It is *not* a layer pointer.

       The @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} you are passed back is the same one passed to the
       function.  You should *not* use "layered" rendering functions
       on this @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}.  Generally, you will wish to do @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61} operations
       such as @{"BltBitMap()" Link "graphics/BltBitMap()"}.  The callback is a raw, low-level rendering
       call-back.  If you need to call a rendering operation with a
       @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}, make sure you use a copy of the @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} and @{"NULL" Link "rexxsupport/NULL"} the
       @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} pointer.

@{b}    SEE ALSO@{ub}
       @{"InstallLayerHook" Link "layers/InstallLayerHook()"}

@EndNode

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

@{b}    NAME@{ub}
       LayerOccluded -- Is @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} occluded by any other layer (V45)

@{b}    SYNOPSIS@{ub}
       occluded = LayerOccluded( l )
       d0                        a0

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} LayerOccluded(struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       This function checks whether the indicated layer is occluded
       by any other layer of the same layer info. It returns FALSE
       in case the layer is fully visible, or returns TRUE if parts
       of this layer are covered by any other layer of the same
       @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}.

@{b}    INPUTS@{ub}
       l     = pointer to @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} structure

@{b}    RESULTS@{ub}
       occluded - a boolean TRUE/FALSE indicator

@{b}    NOTES@{ub}
       You should at least lock the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} of the layer or the
       result is unpredictable as the layer arrangement may change
       while this function is running.

@{b}    SEE ALSO@{ub}
       @{"LockLayerInfo()" Link "LockLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       LockLayer -- @{"Lock" Link "dos/Lock()"} layer to make changes to ClipRects.

@{b}    SYNOPSIS@{ub}
       LockLayer( dummy, l )
                  a0     a1

       void LockLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       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.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a layer

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"UnlockLayer" Link "layers/UnlockLayer()"}, @{"LockLayerInfo" Link "layers/LockLayerInfo()"}, @{"UnlockLayerInfo" Link "layers/UnlockLayerInfo()"},
       @{"graphics.library/LockLayerRom" Link "graphics/LockLayerRom()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       LockLayerInfo -- @{"Lock" Link "dos/Lock()"} the LayerInfo structure.

@{b}    SYNOPSIS@{ub}
       LockLayerInfo( li )
                      a0

       void LockLayerInfo( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);

@{b}    FUNCTION@{ub}
       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 "layers/UnlockLayerInfo()"} for every LockLayerInfo.

       Note: Most 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.

@{b}    INPUTS@{ub}
       li - pointer to @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"UnlockLayerInfo" Link "layers/UnlockLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       LockLayers -- lock all layers from graphics output.

@{b}    SYNOPSIS@{ub}
       LockLayers( li )
                   a0

       void LockLayers( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);

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

@{b}    INPUTS@{ub}
       li - pointer to @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure

@{b}    BUGS@{ub}
       V44 and below might have failed on a low-memory situation.
       In this case, layer cliprects, especially user clip rects
       might have been un-installed and incorrect. This has been
       fixed in V45.
       As a side-condition, LockLayers() removes all user- and
       damage-list constraints of the layer such that it will
       become draw-able in its full rectangle. Whether this side
       condition is desired or not is argueable, but we leave it
       like this for now for backwards compatibility. The cliprect
       layout LockLayers() results in is sub-optimal, but correct.
       @{"UnlockLayers()" Link "UnlockLayers()"} restores the original cliprect layout.

@{b}    SEE ALSO@{ub}
       @{"UnlockLayer" Link "layers/UnlockLayer()"}, @{"LockLayerInfo" Link "layers/LockLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       MoveLayer -- @{"Move" Link "graphics/Move()"} layer to new position in @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}.

@{b}    SYNOPSIS@{ub}
       result = MoveLayer( dummy, l, dx, dy )
       d0                  a0     a1 d0  d1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} MoveLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, LONG);

@{b}    FUNCTION@{ub}
       @{"Move" Link "graphics/Move()"} this layer to new position in shared @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}.
       If any refresh layers become revealed, collect damage and
       set REFRESH bit in layer Flags.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a nonbackdrop layer
       dx - delta to add to current x position
       dy - delta to add to current y position

@{b}    RETURNS@{ub}
       result - TRUE if operation successful
                FALSE if failed (out of memory)

@{b}    BUGS@{ub}
       May not handle (dx,dy) which attempts to move the layer outside the
       layer's RastPort->BitMap bounds .

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       MoveLayerInFrontOf -- Put layer in front of another layer.

@{b}    SYNOPSIS@{ub}
       result = MoveLayerInFrontOf( layertomove, targetlayer )
                                    a0           a1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} MoveLayerInFrontOf( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       @{"Move" Link "graphics/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 "INCLUDE:graphics/layers.h/Main" 54} structure.

@{b}    INPUTS@{ub}
       layertomove - pointer to layer which should be moved
       targetlayer - pointer to target layer in front of which to move layer

@{b}    RESULTS@{ub}
       result = TRUE    if operation successful
                FALSE   if operation unsuccessful (probably out of memory)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME                                                              (V36)@{ub}
       MoveSizeLayer -- Position/Size layer

@{b}    SYNOPSIS@{ub}
       result = MoveSizeLayer( layer, dx, dy, dw, dh )
       d0                      a0     d0  d1  d2  d3

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} MoveSizeLayer( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, LONG);

@{b}    FUNCTION@{ub}
       Change upperleft and lower right position of @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40}.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a nonbackdrop layer
       dx,dy - change upper left corner by (dx,dy)
       dw,dy - change size by (dw,dh)

@{b}    RETURNS@{ub}
       result - TRUE if operation successful
                FALSE if failed (due to out of memory)
                FALSE if failed (due to illegal layer->bounds)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       NewLayerInfo -- @{"Allocate" Link "exec/Allocate()"} and Initialize full @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure.

@{b}    SYNOPSIS@{ub}
       result = NewLayerInfo()
       d0

       struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *NewLayerInfo( void );

@{b}    FUNCTION@{ub}
       @{"Allocate" Link "exec/Allocate()"} memory required for full @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure.
       Initialize @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure in preparation to use
       other layer operations on this list of layers.
       Make the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} unlocked (open).

@{b}    INPUTS@{ub}
       None

@{b}    RESULT@{ub}
       result- pointer to @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure if successful
               @{"NULL" Link "rexxsupport/NULL"} if not enough memory

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       ScrollLayer -- Scroll around in a superbitmap, translate coordinates
                      in non-superbitmap layer.

@{b}    SYNOPSIS@{ub}
       ScrollLayer( dummy, l, dx, dy )
                    a0     a1 d0  d1

       void ScrollLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, LONG);

@{b}    FUNCTION@{ub}
       For a SuperBitMap Layer:
       Update the SuperBitMap from the layer display, then copy bits
       between @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} 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 "layers/InstallClipRegion()"} to simulate Intuition GZZWindows
       without the overhead of an extra layer.

@{b}    INPUTS@{ub}
       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

@{b}    BUGS@{ub}
       May not handle (dx,dy) which attempts to move the layer outside the
       layer's SuperBitMap bounds.

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       SetLayerInfoBounds -- define clipping bounds for all layers (V45)

@{b}    SYNOPSIS@{ub}
       ok = SetLayerInfoBounds( li, bounds );
       d0                       a0    a1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} SetLayerInfoBounds(struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *,struct @{"Rectangle" Link "INCLUDE:graphics/gfx.h/Main" 41} *r);

@{b}    FUNCTION@{ub}
       This function defines a global clipping rectangle for all
       layers of the layer info. Graphics outside of this rectangle
       will be off-screen and non-visible. The purpose of this
       function is therefore to allow windows that are partially
       off-screen by installing a layer info rectangle of the
       screen size.

@{b}    INPUTS@{ub}
       li    = pointer to @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure
       r     = rectangle describing hard clipping bounds for
               this @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}. The contents of the rectangle
               is copied, and "r" may be re-used as soon as
               SetLayerInfoBounds returns.

@{b}    RESULTS@{ub}
       ok - a boolean success/failure indicator. TRUE on success.

@{b}    NOTES@{ub}
       This function absolutely MUST be called before the first
       layer gets installed into this @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54}. It will not affect
       clipping of already existing layers.
       Default @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} clipping is MIN_WORD to MAX_WORD, i.e.
       no clipping takes place. This is V40 behaivour.

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       ShowLayer -- Make invisible layer visible again (V45)

@{b}    SYNOPSIS@{ub}
       result = ShowLayer( l , other )
       d0                 a0    a1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} ShowLayer( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} * );

@{b}    FUNCTION@{ub}
       Make this layer visible again and move it in front of
       the "other" layer. For LAYERSMART layers, copy the
       image from the backding store back on the screen, for
       simple layers, generate apropriate damage.
       If the layer is not hidden, this call does nothing.
       This operation may generate refresh events in other layers
       associated with this layer's @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure.

@{b}    INPUTS@{ub}
       l - pointer to a layer to un-hide
       other - pointer to layer to move in front of.
               for @{"NULL" Link "rexxsupport/NULL"}, this layer is moved into the background
               behind layers of similar kind,
               for (struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *)1, this layer is moved on top
               of the layer stack of layers of similar kind.

@{b}    RESULTS@{ub}
       result - TRUE   if operation successful
                FALSE  if operation unsuccessful (probably out of memory)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       SizeLayer -- Change the size of this nonbackdrop layer.

@{b}    SYNOPSIS@{ub}
       result = SizeLayer( dummy, l, dx, dy )
       d0                  a0     a1 d0  d1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} SizeLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, LONG);

@{b}    FUNCTION@{ub}
       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.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a nonbackdrop layer
       dx - delta to add to current x size
       dy - delta to add to current y size

@{b}    RESULTS@{ub}
       result - TRUE if operation successful
                FALSE if failed (out of memory)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}   NAME@{ub}
       SortLayerCR - Sort the layer's cliprects for scroll raster (V39)

@{b}   SYNOPSIS@{ub}
       SortLayerCR(layer,dx,dy)
                   A0    D0 D1

       VOID SortLayerCR(struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *,WORD,WORD);

@{b}   FUNCTION@{ub}
       This function will sort the give layer's cliprects such that a
       scroll in the direction given will be optimal.

@{b}   NOTE@{ub}
       This routine is for Layers/Graphics internal use only.
       The layer must be locked before calling this routine.

@{b}   INPUTS@{ub}
       layer   - The layer to be sorted...
       dx      - x scroll offset
       dy      - y scroll offset

@{b}   SEE ALSO@{ub}

@EndNode

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

@{b}    NAME@{ub}
       SwapBitsRastPortClipRect -- Swap bits between common bitmap
                                   and obscured @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95}

@{b}    SYNOPSIS@{ub}
       SwapBitsRastPortClipRect( rp, cr )
                                 a0  a1

       void SwapBitsRastPortClipRect( struct @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} *, struct @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} *);

@{b}    FUNCTION@{ub}
       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 "INCLUDE:graphics/gfx.h/Main" 61} with a subsection of
       the display. This is accomplished without using extra memory.
       The bits in the display @{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52} are exchanged with the
       bits in the ClipRect's @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}.

       Note: the @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} structures which the layer library allocates are
       actually a little bigger than those described in the @{"graphics/clip.h" Link "INCLUDE: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.

@{b}    INPUTS@{ub}
       rp - pointer to rastport
       cr - pointer to cliprect to swap bits with

@{b}    NOTE@{ub}
       Because the blit operation started by this function is done
       asynchronously, it is imperative that a @{"WaitBlit()" Link "graphics/WaitBlit()"} be performed
       before releasing or using the processor to modify any of the
       associated structures.

       Note, too, that this call is slow on RTG screens as it uses a
	double-XOR to exchange graphics between the @{"ClipRect" Link "INCLUDE:graphics/clip.h/Main" 95} and the
	@{"RastPort" Link "INCLUDE:graphics/rastport.h/Main" 52}.
	If possible, other means of exchanging bits should be used.
	At the time of writing, the only operating system use of this
	function is intuition, for menu rendering in low memory
	situations. If memory permits, intuition uses a second buffer.
	It is recommended that user programs follow a similar strategy
	and avoid this function if memory permits.

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}, @{"graphics/rastport.h" Link "INCLUDE:graphics/rastport.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       ThinLayerInfo -- convert 1.1 LayerInfo to 1.0 LayerInfo.
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    SYNOPSIS@{ub}
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE
       ThinLayerInfo( li )
                      a0

       void ThinLayerInfo( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);
       OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    FUNCTION@{ub}
       In V45, this function only flushes the cliprect scratch list
       of the layer info. New software MUST use @{"DisposeLayerInfo()" Link "DisposeLayerInfo()"}
       instead.

@{b}    INPUTS@{ub}
       li - pointer to LayerInfo structure

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"DisposeLayerInfo()" Link "DisposeLayerInfo()"}, @{"FattenLayerInfo()" Link "FattenLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       UnlockLayer -- Unlock layer and allow graphics routines to use it.

@{b}    SYNOPSIS@{ub}
       UnlockLayer( l )
                    a0

       void UnlockLayer( struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       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.

@{b}    INPUTS@{ub}
       l - pointer to a layer

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "INCLUDE:graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       UnlockLayerInfo -- Unlock the LayerInfo structure.

@{b}    SYNOPSIS@{ub}
       UnlockLayerInfo( li )
                        a0

       void UnlockLayerInfo( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);

@{b}    FUNCTION@{ub}
       After the operation is complete that required a @{"LockLayerInfo" Link "layers/LockLayerInfo()"},
       unlock the LayerInfo structure so that  other tasks may
       affect the layers.

@{b}    INPUTS@{ub}
       li - pointer to the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure

@{b}     BUGS@{ub}

@{b}     SEE ALSO@{ub}
       @{"LockLayerInfo" Link "layers/LockLayerInfo()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       UnlockLayers -- Unlock all layers from graphics output.
                       Restart graphics output to layers that have
                       been waiting

@{b}    SYNOPSIS@{ub}
       ok = UnlockLayers( li )
                          a0

       @{"BOOL" Link "INCLUDE:exec/types.h/Main" 168} UnlockLayers( struct @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} *);

@{b}    FUNCTION@{ub}
       Make all layers in this layer list unlocked.
       Then calls @{"UnlockLayerInfo" Link "layers/UnlockLayerInfo()"}

@{b}    INPUTS@{ub}
       li - pointer to the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} structure

@{b}    RESULTS@{ub}
       returns a boolean TRUE/FALSE condition for backwards
       compatibility. V45 and above will always return TRUE.

@{b}    BUGS@{ub}
       V44 and below might have failed on a low-memory situation.
       In this case, layer cliprects, especially user clip rects
       might have been un-installed and incorrect. This has been
       fixed in V45.

@{b}    SEE ALSO@{ub}
       @{"LockLayers()" Link "LockLayers()"}, @{"UnlockLayer()" Link "UnlockLayer()"}, @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       UpfrontLayer -- Put layer in front of all other layers.

@{b}    SYNOPSIS@{ub}
       result = UpfrontLayer( dummy, l )
       d0                     a0     a1

       @{"LONG" Link "INCLUDE:exec/types.h/Main" 112} UpfrontLayer( @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *);

@{b}    FUNCTION@{ub}
       @{"Move" Link "graphics/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 "INCLUDE:graphics/layers.h/Main" 54} structure.

@{b}    INPUTS@{ub}
       dummy - unused
       l - pointer to a nonbackdrop layer

@{b}    RESULTS@{ub}
       result - TRUE   if operation successful
                FALSE  if operation unsuccessful (probably out of memory)

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
       WhichLayer -- Which @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} is this point in?

@{b}    SYNOPSIS@{ub}
       layer = WhichLayer( li, x, y )
       d0                  a0  d0 d1

       struct @{"Layer" Link "INCLUDE:graphics/clip.h/Main" 40} *WhichLayer(struct Layer_Info*, WORD, WORD);

@{b}    FUNCTION@{ub}
       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" Link "rexxsupport/NULL"} if there is no layer at this point.

@{b}    INPUTS@{ub}
       li  = pointer to LayerInfo structure
       (x,y) = coordinate in the @{"BitMap" Link "INCLUDE:graphics/gfx.h/Main" 61}

@{b}    RESULTS@{ub}
       layer - pointer to the topmost layer that this point is in
               @{"NULL" Link "rexxsupport/NULL"} if this point is not in a layer

@{b}    NOTES@{ub}
       You should at least lock the @{"Layer_Info" Link "INCLUDE:graphics/layers.h/Main" 54} of the layer or the
       result is unpredictable as the layer arrangement may change
       while this function is running.


@{b}    SEE ALSO@{ub}
       @{"graphics/layers.h" Link "INCLUDE:graphics/layers.h/Main" 0}

@EndNode