@DATABASE Libraries Manual
@NODE MAIN "Amiga RKM Libraries: 30 Layers Library"
@INDEX Lib_Index/MAIN
@TOC Libraries_Manual/MAIN
This chapter describes the layers library which provides routines that are
used to manage overlapping rectangular drawing areas that share a common
display.  Intuition uses the layers library to manage its system of
windows.

The chapter also describes the use of regions, special structures used to
mask off areas where drawing can take place.  Regions are installed
through the layers library function @{"InstallClipRegion()" link 30-2 16} but the routines
for the creation, disposal and manipulation of regions are part of the
graphics library.

@{" Layers " link 30-1}  @{" Regions " link 30-2}  @{" Function Reference " link 30-3}

@ENDNODE

@NODE 30-1 "30 Layers Library / Layers"
The concept of a layer is closely tied to Intuition windows.  A layer is a
rectangular drawing area.  A layer can overlap other layers and has a
display priority that determines whether it will appear in front or behind
other layers.  Every Intuition window has an associated @{"Layer" link 30-1-1} structure.
Layers allow Intuition and application programs to :

    * Share a display's @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} among various tasks in an orderly way
      by creating layers, separate drawing rectangles, within the
      BitMap.

    * Move, size or depth-arrange a layer while automatically keeping
      track of which portions of other layers are hidden or revealed
      by the operation.

    * Manage the remapping of coordinates, so the application need not
      track the layer's offset into the @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4}.

    * Maintain each layer as a separate entity, which may optionally
      have its own @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4}.

    * Automatically update same newly visible portions.

The layers library takes care of housekeeping: the low level, repetitive
tasks which are required to keep track of where to place bits.  The layers
library also provides a locking mechanism which coordinates display
updating when multiple tasks are drawing graphics to layers.  The
windowing environment provided by the Intuition library is largely based
on layers.

    WARNING:
    --------
    Layers may not be created or used directly with Intuition screens.
    Intuition windows are the only supported method of adding layers to
    Intuition screens.  Only the layer locking and unlocking functions
    are safe to use with Intuition.  An application must create and
    manage its own @{"View" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} if it will be creating layers directly on the
    display.

@{" The Layer Structure " link 30-1-1}         @{" Working With Existing Layers " link 30-1-5}
@{" The Layer's RastPort " link 30-1-2}        @{" Creating and Using New Layers " link 30-1-6}
@{" Types of Layers " link 30-1-3}             @{" Layers Example " link ADCD_v1.2:Reference_Library/Libraries/lib_examples/Layers.c/MAIN}
@{" Opening the Layers Library " link 30-1-4}

@ENDNODE

@NODE 30-1-1 "30 / Layers / The Layer Structure"
The internal representation of layers is essentially a set of clipping
rectangles.  Each layer is represented by an instance of the Layer
structure.  All the layers in a display are linked together through the
@{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure.  Any display shared by multiple layers (such as an
Intuition screen) requires one Layer_Info data structure to handle
interactions between the various layers. Here is a partial listing of the
Layer structure from <graphics/@{"clip.h" link ADCD_v1.2:Inc&AD2.1/includes/graphics/clip.h/MAIN 33}>.  (For a complete listing refer to
the Amiga ROM Kernel Reference Manual: Includes and Autodocs.)

    struct Layer
    {
        struct  Layer *front,*back;
        struct  ClipRect   *ClipRect; /* read ROMs to find 1st cliprect */
        struct  RastPort   *rp;
        struct  Rectangle  bounds;
          ...

        UWORD   Flags;                /* obscured ?, Virtual BitMap? */
        struct  BitMap  *SuperBitMap;
          ...

        struct  Region  *DamageList;  /* list of rectangles to refresh */
                                      /* through */
    };


    The Layer Structure is Read-Only.
    ---------------------------------
    Applications should never directly modify any of the elements of the
    Layer structure. In addition, applications should only read the
    front, back, rp, bounds, Flags, SuperBitMap and DamageList elements
    of the Layer structure. (Some of these elements are subject to
    dynamic change by the system so proper layer locking procedures must
    be followed when relying on what the application has read.)

@ENDNODE

@NODE 30-1-2 "30 / Layers / The Layer's RastPort"
When a layer is created, a @{"RastPort" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-4-1} is automatically to go along with it.
The pointer to the RastPort is contained in the layer data structure.
Using this RastPort, the application may draw anywhere into the layer's
bounds rectangle.  If the application tries to draw outside of this
rectangle, the graphics routines will clip the graphics.

Here is sample code showing how to access the layer's @{"RastPort" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-4-1}:

    struct RastPort *myRPort;
        /* allocate a RastPort pointer for each layer */

    myRPort = layer->rp;

    /* The layer's RastPort may be used with any of the graphics library
    ** calls that require this structure.  For instance, to fill layer
    ** with color:
    */
    SetRast(layer->rp, color);

    /* set up for writing text into layer */
    SetDrMd(layer->rp,JAM1);
    SetAPen(layer->rp,0);
    Move(layer->rp, 5, 7);

    /* write into layer */
    Text(layer->rp, string, strlen(string));

@ENDNODE

@NODE 30-1-3 "30 / Layers / Types of Layers"
The layers library supports three types of layers: simple refresh, smart
refresh and super bitmap.  The type of the layer, specified by the Flags
field in the @{"Layer" link 30-1-1}s structure, determines what facilities the layer
provides.

    Use Only One Layer Type Flag
    ----------------------------
    The three layer-type Flags are mutually exclusive.  That is, only one
    layer-type flag (LAYERSIMPLE, LAYERSMART and LAYERSUPER) should be
    specified.

@{" Simple Refresh Layer " link 30-1-3-1}  @{" Super Bitmap Layer " link 30-1-3-3}
@{" Smart Refresh Layer " link 30-1-3-2}   @{" Backdrop Layer " link 30-1-3-4}

@ENDNODE

@NODE 30-1-3-1 "30 / / Types of Layers / Simple Refresh Layer"
When an application draws into the layer, any portion of the layer that is
visible (not obscured) will be rendered into the common @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} of the
viewing area.  All graphics rendering routines are "clipped", so that only
exposed sections of the layer are drawn into.  No back-up of obscured
areas is provided.

If another layer operation is performed that causes an obscured part of a
simple refresh layer to be exposed, the application must determine if the
section need be refreshed, re-drawing the newly exposed part of the layer
as required.

The basic advantage of simple refresh is that it does not require back-up
area to save drawing sections that cannot be seen, saving memory. However,
the application needs to monitor the layer to see if it needs refreshing.
This is typically performed with statements like:

    if (layer->Flags & LAYERREFRESH)
        refresh(layer);

@ENDNODE

@NODE 30-1-3-2 "30 / / Types of Layers / Smart Refresh Layer"
Under smart refresh, the system provides dynamic backup of obscured
sections of the layer. The graphics routines will automatically draw into
these backup areas when they encounter an obscured part of the layer. The
backup memory will be used to automatically update the display when
obscured sections later become exposed.

With smart refresh layers, the system handles all of the refresh
requirements of the layer, except when the layer is made larger. When
parts of the layer are exposed by a sizing operation, the application must
refresh the newly exposed areas.

The advantage of smart refresh is the speed of updating exposed regions of
the layer and the ability of the system to manage part of the updating
process for the application.. Its main disadvantage is the additional
memory required to handle this automatic refresh.

@ENDNODE

@NODE 30-1-3-3 "30 / / Types of Layers / Super Bitmap Layer"
A super bitmap layer is similar to a @{"smart refresh" link 30-1-3-2} layer.  It too has a
back-up area for rendering graphics for currently obscured parts of the
display.  Whenever an obscured area is made visible, the corresponding
part of the backup area is copied to the display automatically.

However, it differs from @{"smart refresh" link 30-1-3-2} in that:

  * The back-up @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} is user-supplied, rather than being allocated
    dynamically by the system.

  * The back-up @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} may be as large or larger than the the current
    size of the layer. It may also be larger than the maximum size of the
    layer.

To see a larger portion of a super bitmap on-display, use @{"SizeLayer()" link 30-1-6 17}.  To
see a different portion of the super bitmap in the layer, use
@{"ScrollLayer()" link 30-1-6 17}.

When the graphics routines perform drawing commands, part of the drawing
appears in the common @{"BitMap" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} (the on-display portion). Any drawing outside
the displayed portion itself is rendered into the super bitmap. When the
layer is scrolled or sized, the layer contents are copied into the super
bitmap, the scroll or size positioning is modified, and the appropriate
portions are then copied back into the layer. (Refer to the graphics
library functions @{"SyncSBitMap()" link ADCD_v1.2:Reference_Library/Libraries/Lib_4/4-5-5-1 12} and @{"CopySBitMap()" link ADCD_v1.2:Reference_Library/Libraries/Lib_4/4-5-5-1 26}.

@ENDNODE

@NODE 30-1-3-4 "30 / / Types of Layers / Backdrop Layer"
A layer of any type may be designated a backdrop layer which will always
appear behind all other layers. They may not be moved, sized, or
depth-arranged. Non-backdrop layers will always remain in front of
backdrop layers regardless of how the non-backdrop layer is moved, sized
or depth-arranged.

@ENDNODE

@NODE 30-1-4 "30 / Layers / Opening the Layers Library"
Like all libraries, the layers library must be opened before it may be
used.  Check the Layers Autodocs to determine what version of the library
is required for any particular Layers function.

    struct Library *LayersBase;

    if (NULL != (LayersBase = OpenLibrary("layers.library",33L)))
        {
        /* use Layers library */

        CloseLibrary((struct Library *)LayersBase);
        }

@ENDNODE

@NODE 30-1-5 "30 / Layers / Working With Existing Layers"
A common operation performed by applications is to render text or graphics
into an existing layer such as an Intuition window.  To prevent Intuition
from changing the layer (for instance when the user resizes or moves the
window) during a series of graphic operations, the layers library provides
locking functions for obtaining exclusive access to a layer.

These locking functions are also useful for applications that create their
own layers if the application has more than one task operating on the
layers asynchronously.  These calls coordinate multiple access to layers.


  Table 30-1: Functions for Intertask Control of Layers (Layers Library)
   ____________________________________________________________________
  |                                                                    |
  |        @{"LockLayer()" link 30-1-5-1 27}  Lock out rendering in a single layer.          |
  |      @{"UnlockLayer()" link 30-1-5-1 40}  Release LockLayer() lock.                      |
  |       @{"LockLayers()" link 30-1-5-1 49}  Lock out rendering in all layers of a display. |
  |     @{"UnlockLayers()" link 30-1-5-1 49}  Release LockLayers() lock.                     |
  |    @{"LockLayerInfo()" link 30-1-5-1 6}  Gain exclusive access to the display's layers. |
  |  @{"UnlockLayerInfo()" link 30-1-5-1 19}  Release LockLayerInfo() lock.                  |
  |____________________________________________________________________|


The following routines from the graphics library also allow multitasking
access to layer structures:


 Table 30-2: Functions for Intertask Control of Layers (Graphics Library)
   ____________________________________________________________________
  |                                                                    |
  |         @{"LockLayerRom()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/LockLayerRom()}  Same as @{"LockLayer()" link 30-1-5-1 27}, from layers library.  |
  |       @{"UnlockLayerRom()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/UnlockLayerRom()}  Release LockLayerRom() lock.               |
  |  @{"AttemptLockLayerRom()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/AttemptLockLayerRom()}  Lock layer only if it is immediately       |
  |                         available.                                 |
  |____________________________________________________________________|


These functions are similar to the layers @{"LockLayer()" link 30-1-5-1 27} and @{"UnlockLayer()" link 30-1-5-1 40}
functions, but do not require the layers library to be open.  See the
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details.

@{" Intertask Operations " link 30-1-5-1}  @{" Determining Layer Position " link 30-1-5-2}

@ENDNODE

@NODE 30-1-5-1 "30 / / Working With Existing Layers / Intertask Operations"
If multiple tasks are manipulating layers on the same display they will be
sharing a @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure and their use of it and its related data
structures need to be coordinated.  To ensure that a structure remains
cohesive, it should be operated on by only one task at a time.  The
Layer_Info encompasses all the layers existing on a single display.

@{"LockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayerInfo()} must be called whenever the visible portions of layers may
be affected, or when the @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure is changed.

    void LockLayerInfo( struct Layer_Info *li );

The lock should be obtained whenever a layer is created, deleted sized or
moved, as the list of layers that is being managed by the @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} data
structure must be updated.

It is not necessary to lock the @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} data structure while rendering,
or when calling routines like @{"ScrollLayer()" link 30-1-6 17}, because layer sizes and
on-display positions are not being affected.

Use @{"UnlockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayerInfo()} when you have finished the layer operation:

    void UnlockLayerInfo( struct Layer_Info *li );

If you don't unlock the @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} then any other task calling
@{"LockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayerInfo()} on the same Layer_Info structure will be blocked creating
a potential deadlock situation.

In addition to locking the @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure, the layer itself should
be locked if it is shared between tasks so that only one task at a time
renders graphics to it.  @{"LockLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayer()} is used to get exclusive graphics
output to a layer.

    void LockLayer( long dummy, struct Layer *layer );

If a graphics function is in process, the lock will return when the
function is completed.  Other tasks are blocked only if they attempt to
draw graphics into this layer, or try to obtain a lock on this layer. The
@{"MoveLayer()" link 30-1-6 17}, @{"SizeLayer()" link 30-1-6 17} and @{"ScrollLayer()" link 30-1-6 17} functions automatically lock
and unlock the layer they operate on.

@{"UnlockLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayer()} should be used after the graphics operation to make the
layer available to other tasks again.

    void UnlockLayer( struct Layer *layer );

If more than one layer must be locked, then the @{"LockLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayer()} calls should
be surrounded by @{"LockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayerInfo()} and @{"UnlockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayerInfo()} calls, to prevent
deadlock situations.

The layers library provides two additional functions, @{"LockLayers()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayers()} and
@{"UnlockLayers()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayers()}, for locking multiple layers.

    void LockLayers( struct Layer_Info *li );
    void UnlockLayers( struct Layer_Info *li );

@{"LockLayers()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayers()} is used to lock all layers in a single command.
@{"UnlockLayers()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayers()} releases the layers lock.  The system calls these routines
during the @{"BehindLayer()" link 30-1-6 23}, @{"UpfrontLayer()" link 30-1-6 23} and @{"MoveLayerInFrontOf()" link 30-1-6 23}
operations (@{"described below" link 30-1-6}).

@ENDNODE

@NODE 30-1-5-2 "30 / / Working With Existing Layers / Determining Layer Position"
If the viewing area has been separated into several layers, the
application may need to find out which layer is topmost at a particular
x,y coordinate.  Use the @{"WhichLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/WhichLayer()} function for this:

    struct Layer *WhichLayer( struct Layer_Info *li, long x, long y );

To be sure that no task adds, deletes, or changes the sequence of layers
before this information is used, call @{"LockLayerInfo()" link 30-1-5 11} before calling
@{"WhichLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/WhichLayer()}, and call @{"UnlockLayerInfo()" link 30-1-5 11} when the operation is complete.
In this way, the program may ensure that it is acting on valid
information.  Always check for a NULL return value (coordinate not in a
layer) from WhichLayer().

@ENDNODE

@NODE 30-1-6 "30 / Layers / Creating and Using New Layers"
The functions described in this section are generally not safe to use with
Intuition.  To create new layers for Intuition you use Intuition window
calls (see the "@{"Intuition Windows" link ADCD_v1.2:Reference_Library/Libraries/Lib_4/4-2}" chapter earlier in this book).

Only applications that create and mange their own @{"View" link ADCD_v1.2:Reference_Library/Libraries/Lib_3/3-7 4} will be able to
call the layer creation and updating functions discussed here.


         Table 30-3: Functions for Creating and Updating Layers
   ___________________________________________________________________
  |                                                                   |
  |              @{"NewLayerInfo()" link 30-1-6-3}  Allocating a @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure.   |
  |          @{"DisposeLayerInfo()" link 30-1-6-3 5}  Deallocating a Layer_Info structure. |
  |-------------------------------------------------------------------|
  |        @{"CreateUpfrontLayer()" link 30-1-6-4}  Make a new layer in front of others. |
  |         @{"CreateBehindLayer()" link 30-1-6-4 9}  Make a new layer behind others.      |
  |               @{"DeleteLayer()" link 30-1-6-4 28}  Remove and delete an existing layer. |
  |-------------------------------------------------------------------|
  |                 @{"MoveLayer()" link 30-1-6-5}  Change the position (not depth) of a |
  |                              layer.                               |
  |                 @{"SizeLayer()" link 30-1-6-5}  Change the size of a layer.          |
  |               @{"ScrollLayer()" link 30-1-6-6}  Change the internal coordinates of a |
  |                              layer.                               |
  |-------------------------------------------------------------------|
  |               @{"BehindLayer()" link 30-1-6-7}  Depth arrange a layer behind others. |
  |              @{"UpfrontLayer()" link 30-1-6-7}  Depth arrange a layer in front of    |
  |                              others.                              |
  |        @{"MoveLayerInFrontOf()" link 30-1-6-7}  Depth arrange a layer to a specific  |
  |                              position.                            |
  |-------------------------------------------------------------------|
  |  @{"SwapBitsRastPortClipRect()" link 30-1-6-8}  Fast, non-layered and non-damaging   |
  |                              display operation.                   |
  |-------------------------------------------------------------------|
  |               @{"BeginUpdate()" link 30-1-6-7 13}  Synchronize optimized refreshing for |
  |                              layer.                               |
  |                 @{"EndUpdate()" link 30-1-6-7 13}  End optimized layer refresh.         |
  |___________________________________________________________________|


@{" Creating a Viewing Workspace " link 30-1-6-1}
@{" Creating the Layers " link 30-1-6-2}
@{" Allocating and Deallocating Layer_Info " link 30-1-6-3}
@{" Allocating and Deallocating Layers " link 30-1-6-4}
@{" Moving and Sizing Layers " link 30-1-6-5}
@{" Changing a Viewpoint " link 30-1-6-6}
@{" Reordering Layers " link 30-1-6-7}
@{" Sub-Layer Rectangle Operations " link 30-1-6-8}

@ENDNODE

@NODE 30-1-6-1 "30 / / Creating and Using New Layers / Creating a Viewing Workspace"
A viewing workspace may be created by using the primitives @{"InitVPort()" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-2-7-4},
@{"InitView()" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-2-7-1}, @{"MakeVPort()" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-2-7-6}, @{"MrgCop()" link ADCD_v1.2:Reference_Library/Libraries/Lib_28/28-3-12}, and @{"LoadView()" link ADCD_v1.2:Reference_Library/Libraries/Lib_28/28-3-12}. Please reference the
"@{"Graphics Primitives" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-2}" chapter for details on creating a low-level graphics
display.  Do not create Layers directly on Intuition screens.  Windows are
the only supported method of creating a layer on a screen.

@ENDNODE

@NODE 30-1-6-2 "30 / / Creating and Using New Layers / Creating the Layers"
The application must first allocate and initialize a @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} data
structure which the system uses to keep track of layers that are created,
use statements like:

    struct Layer_Info *theLayerInfo;

    if (NULL != (theLayerInfo = NewLayerInfo()))
        {
        /* use Layer_Info */

        DisposeLayerInfo(theLayerInfo);
        }

Layers may be created in the common bit map by calling
@{"CreateUpfrontLayer()" link 30-1-6 13} or @{"CreateBehindLayer()" link 30-1-6 13}, with a sequence such as the
following:

    struct Layer      *layer;
    struct Layer_Info *theLayerInfo;
    struct BitMap     *theBitMap;

    /* requests construction of a smart refresh layer. */
    if (NULL == (layer = CreateUpfrontLayer(theLayerInfo, theBitMap,
              20, 20, 100, 80, LAYERSMART, NULL)))
        error("CreateUpfrontLayer() failed.");
    else
        {
        ; /* layer successfully created here. */
        }

@ENDNODE

@NODE 30-1-6-3 "30 / / / Allocating and Deallocating Layer_Info"
Use @{"NewLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/NewLayerInfo()} to allocate and initialize a @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure and
associated sub-structures.

    struct Layer_Info *NewLayerInfo( void );

You must call this function before attempting to use any of the other
layers functions described below.  When you have finished with a
@{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure, use @{"DisposeLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/DisposeLayerInfo()} to deallocate it.

    void DisposeLayerInfo( struct Layer_Info *li );

This function deallocates a @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} and associated structures
previously allocated with @{"NewLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/NewLayerInfo()}.

@ENDNODE

@NODE 30-1-6-4 "30 / / Creating and Using Layers / Allocating and Deallocating Layers"
Layers are created using the routines @{"CreateUpfrontLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/CreateUpfrontLayer()}
and @{"CreateBehindLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/CreateBehindLayer()}.  CreateUpfrontLayer()
creates a layer that will appear in front of any existing layers.

    struct Layer *CreateUpfrontLayer( struct Layer_Info *li,
                                      struct BitMap *bm,
                                      long x0, long y0, long x1, long y1,
                                      long flags, struct BitMap *bm2 );

@{"CreateBehindLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/CreateBehindLayer()} creates a layer that appears behind existing layers,
but in front of @{"backdrop" link 30-1-3-4} layers.

    struct Layer *CreateBehindLayer( struct Layer_Info *li,
                                     struct BitMap *bm,
                                     long x0, long y0, long x1, long y1,
                                     long flags, struct BitMap *bm2 );

Both of these routines return a pointer to a @{"Layer" link 30-1-1} data structure (as
defined in the include file <graphics/@{"layers.h" link ADCD_v1.2:Inc&AD2.1/includes/graphics/layers.h/MAIN 33}>), or NULL if the operation
was unsuccessful.

    A New Layer Also Gets a RastPort.
    ---------------------------------
    When a layer is created, the routine automatically creates a
    @{"RastPort" link ADCD_v1.2:Reference_Library/Libraries/Lib_27/27-4-1} to go along with it.  If the layer's RastPort is passed
    to the drawing routines, drawing will be restricted to the layer.
    See "@{"The Layer's RastPort" link 30-1-2}" section above.

Use the @{"DeleteLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/DeleteLayer()} call to remove a layer:

    LONG DeleteLayer( long dummy, struct Layer *layer );

@{"DeleteLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/DeleteLayer()} removes a layer from the layer list and frees the memory
allocated by the layer creation calls listed above.

@ENDNODE

@NODE 30-1-6-5 "30 / / Creating and Using New Layers / Moving and Sizing Layers"
The layers library includes three functions for moving and sizing layers:

    LONG MoveLayer( long dummy, struct Layer *layer, long dx, long dy );
    LONG SizeLayer( long dummy, struct Layer *layer, long dx, long dy );
    LONG MoveSizeLayer( struct Layer *layer, long dx, long dy, long dw,
                        long dh);

@{"MoveLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/MoveLayer()} moves a layer to a new position relative to its current
position.  @{"SizeLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/SizeLayer()} changes the size of a layer by modifying the
coordinates of the lower right corner of the layer.  @{"MoveSizeLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/MoveSizeLayer()}
changes both the size and position of a layer in a single call.

@ENDNODE

@NODE 30-1-6-6 "30 / / Creating and Using New Layers / Changing a Viewpoint"
The @{"ScrollLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/ScrollLayer()} function changes the portion of a @{"super bitmap" link 30-1-3-3} that is
shown by a layer:

    void ScrollLayer( long dummy, struct Layer *layer, long dx, long dy );

This function is most useful with @{"super bitmap" link 30-1-3-3} layers but can also
simulate the effect on other layer types by adding the scroll offset to
all future rendering.

@ENDNODE

@NODE 30-1-6-7 "30 / / Creating and Using New Layers / Reordering Layers"
The layers library provides three function calls for reordering layers:

    LONG BehindLayer ( long dummy, struct Layer *layer );
    LONG UpfrontLayer( long dummy, struct Layer *layer );
    LONG MoveLayerInFrontOf( struct Layer *layer_to_move,
                             struct Layer *other_layer );

@{"BehindLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/BehindLayer()} moves a layer behind all other layers.  This function
considers any @{"backdrop" link 30-1-3-4} layers, moving a current layer behind all others
except backdrop layers.  @{"UpfrontLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UpfrontLayer()} moves a layer in front of all
other layers.  @{"MoveLayerInFrontOf()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/MoveLayerInFrontOf()} is used to place a layer at a specific
depth, just in front of a given layer.

As areas of @{"simple refresh" link 30-1-3-1} layers become exposed, due to layer movement or
sizing for example, the newly exposed areas have not been drawn into, and
need refreshing.  The system keeps track of these areas by using a
@{"DamageList" link 30-1-1 21}.  To update only those areas that need it, the @{"BeginUpdate()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/BeginUpdate()}
@{"EndUpdate()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/EndUpdate()} functions are called.

    LONG BeginUpdate( struct Layer *l );
    void EndUpdate  ( struct Layer *layer, unsigned long flag );

@{"BeginUpdate()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/BeginUpdate()} saves the pointer to the current clipping rectangles and
installs a pointer to a set of @{"ClipRect" link 30-1-1 11}s generated from the @{"DamageList" link 30-1-1 21} in
the layer structure.  To repair the layer, use the graphics rendering
routines as if to redraw the entire layer, and the routines will
automatically use the new clipping rectangle list.  So, only the damaged
areas are actually rendered into, saving time.

    Never Modify the DamageList.
    ----------------------------
    The system generates and maintains the @{"DamageList" link 30-1-1 21} region.  All
    application clipping should be done through the @{"InstallClipRegion()" link 30-2 16}
    function.

To complete the update process call @{"EndUpdate()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/EndUpdate()} which will restore the
original @{"ClipRect" link 30-1-1 11} list.

@ENDNODE

@NODE 30-1-6-8 "30 / / Creating and Using New Layers / Sub-Layer Rectangle Operations"
The @{"SwapBitsRastPortClipRect()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/SwapBitsRastPortClipRect()} routine is for applications that do not
want to worry about clipping rectangles.

    void SwapBitsRastPortClipRect( struct RastPort *rp,
                                   struct ClipRect *cr );

For instance, you may use The @{"SwapBitsRastPortClipRect()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/SwapBitsRastPortClipRect()} to produce a menu
without using Intuition.  There are two ways to produce such a menu:

 1. Create an up-front layer with @{"CreateUpfrontLayer()" link 30-1-6 13}, then render the
    menu in it.  This could use lots of memory and require a lot of (very
    temporary) "slice-and-dice" operations to create all of the clipping
    rectangles for the existing windows and so on.

 2. Use @{"SwapBitsRastPortClipRect()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/SwapBitsRastPortClipRect()}, directly on the display drawing area:

      * Render the menu in a back-up area off the display, then lock all
        of the on-display layers so that no task may use graphics
        routines to draw over the menu area on the display.

      * Next, swap the on-display bits with the off-display bits, making
        the menu appear.

      * When finished with the menu, swap again and unlock the layers.

The second method is faster and leaves the clipping rectangles and most of
the rest of the window data structures untouched.

    Warning:
    --------
    All of the layers must be locked while the menu is visible if you
    use the second method above.  Any task that is using any of the
    layers for graphics output will be halted while the menu operations
    are taking place.  If, on the other hand, the menu is rendered as a
    layer, no task need be halted while the menu is up because the lower
    layers need not be locked.

@ENDNODE

@NODE 30-2 "30 Layers Library / Regions"
Regions allow the application to install clipping rectangles into layers.
A clipping rectangle is a rectangular area into which the graphics
routines will draw.  All drawing that would fall outside of that
rectangular area is clipped (not rendered).

User clipping regions are linked lists of clipping rectangles created by
an application program through the graphics library routines described
below.  By combining together various clipping rectangles, any arbitrary
clipping shape can be created.  Once the region is set up, you use the
layers library call @{"InstallClipRegion()" link 30-2-2} to make the clipping region active
in a layer.

Regions are safe to use with layers created by Intuition (i.e., windows).
The following table describes the routines available for the creation,
manipulation and use of regions.


                Table 30-4: Functions Used with Regions
  ____________________________________________________________________
 |                                                                    |
 |          Routine      Library         Description                  |
 |====================================================================|
 |  @{"InstallClipRegion()" link 30-2-2}  Layers    Add a clipping region to a layer.  |
 |--------------------------------------------------------------------|
 |          @{"NewRegion()" link 30-2-1}  Graphics  Create a new, empty region.        |
 |      @{"DisposeRegion()" link 30-2-1 9}  Graphics  Dispose of an existing region and  |
 |                                 its rectangles.                    |
 |--------------------------------------------------------------------|
 |      @{"AndRectRegion()" link 30-2-3-1}  Graphics  And a rectangle into a region.     |
 |       @{"OrRectRegion()" link 30-2-3-1}  Graphics  Or a rectangle into a region.      |
 |      @{"XorRectRegion()" link 30-2-3-1}  Graphics  Exclusive-or a rectangle into a    |
 |                                 region.                            |
 |    @{"ClearRectRegion()" link 30-2-3-1}  Graphics  Clear a rectangular portion of a   |
 |                                 region.                            |
 |    @{"AndRegionRegion()" link 30-2-3-2}  Graphics  And two regions together.          |
 |     @{"OrRegionRegion()" link 30-2-3-2}  Graphics  Or two regions together.           |
 |    @{"XorRegionRegion()" link 30-2-3-2}  Graphics  Exclusive-or two regions together. |
 |--------------------------------------------------------------------|
 |        @{"ClearRegion()" link 30-2-3-2}  Graphics  Clear a region.                    |
 |____________________________________________________________________|


With these functions, the application can selectively update a
custom-shaped part of a layer without disturbing any of the other layers
that might be present.

    Never Modify the DamageList of a Layer Directly.
    ------------------------------------------------
    Use the routine @{"InstallClipRegion()" link 30-2-2} to add clipping to the layer.
    The regions installed by InstallClipRegion() are independent of
    the layer's @{"DamageList" link 30-1-1 21} and use of user clipping regions will not
    interfere with optimized window refreshing.

    Do Not Modify A Region After It Has Been Added.
    -----------------------------------------------
    After a region has been added with @{"InstallClipRegion()" link 30-2-2}, the
    program may not modify it until the region has been removed with
    another call to InstallClipRegion().

@{" Creating and Deleting Regions " link 30-2-1}  @{" Changing a Region " link 30-2-3}
@{" Installing Regions " link 30-2-2}             @{" Regions Example " link ADCD_v1.2:Reference_Library/Libraries/lib_examples/clipping.c/MAIN}

@ENDNODE

@NODE 30-2-1 "30 / Regions / Creating and Deleting Regions"
You allocate a @{"Region" link ADCD_v1.2:Inc&AD2.1/includes/graphics/regions.h/MAIN 28} data structure with the @{"NewRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/NewRegion()} call.

    struct Region *NewRegion( void );

The @{"NewRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/NewRegion()} function allocates and initializes a @{"Region" link ADCD_v1.2:Inc&AD2.1/includes/graphics/regions.h/MAIN 28} structure that
has no drawable areas defined in it.  If the application draws through a
new region, nothing will be drawn as the region is empty.  The application
must add rectangles to the region before any graphics will appear.

Use @{"DisposeRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/DisposeRegion()} to free the @{"Region" link ADCD_v1.2:Inc&AD2.1/includes/graphics/regions.h/MAIN 28} structure when you are done with it.

    void DisposeRegion( struct Region *region );

@{"DisposeRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/DisposeRegion()} returns all memory associated with a region to the system
and deallocates all rectangles that have been linked to it.

    Don't Forget to Free Your Rectangles.
    -------------------------------------
    All of the functions that add rectangles to the region make copies
    of the rectangles.  If the program allocates a rectangle, then adds
    it to a region, it still must deallocate the rectangle.  The call to
    @{"DisposeRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/DisposeRegion()} will not deallocate rectangles explicitly
    allocated by the application.

@ENDNODE

@NODE 30-2-2 "30 / Regions / Installing Regions"
Use the function @{"InstallClipRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/InstallClipRegion()} to install the region.

    struct Region *InstallClipRegion( struct Layer *layer,
                                      struct Region *region );

This installs a transparent clipping region to a layer.  All subsequent
graphics calls will be clipped to this region.  The region must be removed
with a second call to @{"InstallClipRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/InstallClipRegion()} before removing the layer.

    /*
    ** Sample installation and removal of a clipping region
    */
    register struct Region     *new_region ;
    register struct Region     *old_region ;

    /* If the application owns the layer and has not installed a region,
    ** old_region will return NULL here.
    */
    old_region = InstallClipRegion(win->WLayer, new_region);

    /* draw into the layer or window */

    if (NULL != (old_region = InstallClipRegion(win->WLayer, old_region)))
        {
        /* throw the used region away.  This region could be saved and
        ** used again later, if desired by the application.
        */
        DisposeRegion(new_region) ;
        }


    A Warning About InstallClipRegion().
    ------------------------------------
    The program must not call @{"InstallClipRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/InstallClipRegion()} inside of a
    @{"Begin" link ADCD_v1.2:Reference_Library/Libraries/Lib_4/4-5-4}/@{"EndRefresh()" link ADCD_v1.2:Reference_Library/Libraries/Lib_4/4-5-4 25} or @{"Begin/EndUpdate()" link 30-1-6 32} pair.  The following code
    segment shows how to modify the user clipping region when using these
    calls.  See the Autodoc for @{"BeginRefresh()" link ADCD_v1.2:Inc&AD2.1/autodocs/intuition/BeginRefresh()} for more details.


    register struct Region     *new_region ;
    register struct Region     *old_region ;

    /* you have to have already setup the new_region and old_region */

    BeginRefresh(window);
    /* draw through the damage list */
    /* into the layer or window */
    EndRefresh(window, FALSE);              /* keep the damage list */

    old_region = InstallClipRegion(win->WLayer, new_region);

    BeginRefresh(window);
    /* draw through the damage list and the new_region */
    /* into the layer or window */
    EndRefresh(window, FALSE);              /* keep the damage list */

    /* put back the old region */
    new_region = InstallClipRegion(win->WLayer, old_region);

    BeginRefresh(window);
    EndRefresh(window, TRUE);               /* remove the damage list */

    old_region = InstallClipRegion(win->WLayer, new_region);

    BeginRefresh(window);
    /* draw through the new_region only into the layer or window */
    EndRefresh(window, FALSE);

    /* finally get rid of the new region, old_region still installed */
    if (NULL != (new_region = InstallClipRegion(win->WLayer, old_region)))
        DisposeRegion(new_region) ;

@ENDNODE

@NODE 30-2-3 "30 / Regions / Changing a Region"
Regions may be modified by performing logical operations with rectangles,
or with other regions.

    Reuse Your Rectangles.
    ----------------------
    In all of the rectangle and region routines the clipping rectangle
    is copied into the region.  This means that a single clipping
    rectangle (@{"Rectangle" link ADCD_v1.2:Reference_Library/Libraries/Lib_29/29-3 49} structure) may be used many times by simply
    changing the x and y values.  The application need not create a
    new instance of the Rectangle structure for each rectangle added
    to a region.

For instance:

    extern struct Region *RowRegion;  /* created elsewhere */

    WORD ktr;
    struct Rectangle rect;

    for (ktr = 1; ktr < 6; ktr++)
        {
        rect.MinX = 50;
        rect.MaxX = 315;
        rect.MinY = (ktr * 10) - 5;
        rect.MaxY = (ktr * 10);

        if (!OrRectRegion(RowRegion, &rect))
            clean_exit(RETURN_WARN);
        }

@{" Rectangles and Regions " link 30-2-3-1}  @{" Regions and Regions " link 30-2-3-2}

@ENDNODE

@NODE 30-2-3-1 "30 / / Changing a Region / Rectangles and Regions"
There are four functions for changing a region through logical operations
with a rectangle.

    BOOL OrRectRegion   ( struct Region *region,
                          struct Rectangle *rectangle );
    void AndRectRegion  ( struct Region *region,
                          struct Rectangle *rectangle );
    BOOL XorRectRegion  ( struct Region *region,
                          struct Rectangle *rectangle );
    BOOL ClearRectRegion( struct Region *region,
                          struct Rectangle *rectangle );

@{"OrRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/OrRectRegion()} modifies a region structure by or'ing a clipping rectangle
into the region.  When the application draws through this region (assuming
that the region was originally empty), only the pixels within the clipping
rectangle will be affected. If the region already has drawable areas, they
will still exist, this rectangle is added to the drawable area.

@{"AndRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/AndRectRegion()} modifies the region structure by and'ing a clipping
rectangle into the region.  Only those pixels that were already drawable
and within the rectangle will remain drawable, any that are outside of it
will be clipped in future.

@{"XorRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/XorRectRegion()} applies the rectangle to the region in an exclusive-or
mode.  Within the given rectangle, any areas that were drawable become
clipped, any areas that were clipped become drawable.  Areas outside of
the rectangle are not affected.

@{"ClearRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/ClearRectRegion()} clears the rectangle from the region.  Within the given
rectangle, any areas that were drawable become clipped.  Areas outside of
the rectangle are not affected.

@ENDNODE

@NODE 30-2-3-2 "30 / / Changing a Region / Regions and Regions"
As with rectangles and regions, there are four layers library functions
for combining regions with regions:

    BOOL AndRegionRegion( struct Region *srcRegion,
                          struct Region *destRegion );
    BOOL OrRegionRegion ( struct Region *srcRegion,
                          struct Region *destRegion );
    BOOL XorRegionRegion( struct Region *srcRegion,
                          struct Region *destRegion );
    void ClearRegion    ( struct Region *region );

@{"AndRegionRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/AndRegionRegion()} performs a logical and operation on the two regions,
leaving the result in the second region.  The operation leaves drawable
areas wherever the regions drawable areas overlap.  That is, where there
are drawable areas in both region 1 and region 2, there will be drawable
areas left in the result region.

@{"OrRegionRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/OrRegionRegion()} performs a logical or operation on the two regions,
leaving the result in the second region. The operation leaves drawable
areas wherever there are drawable areas in either region. That is, where
there are drawable areas in either region 1 or region 2, there will be
drawable areas left in the result region.

@{"XorRegionRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/XorRegionRegion()} performs a logical exclusive-or operation on the two
regions, leaving the result in the second region.  The operation leaves
drawable areas wherever there are drawable areas in either region but not
both.  That is, where there are drawable areas in either region 1 or
region 2, there will be drawable areas left in the result region.  But
where there are drawable areas in both region 1 and region 2, there will
not be drawable areas left in the result region.

@{"ClearRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/ClearRegion()} puts the region back to the same state it was in when the
region was created with @{"NewRegion()" link 30-2 23}, that is, no areas are drawable.

@ENDNODE

@NODE 30-3 "30 Layers Library / Function Reference"
The following are brief descriptions of the layers library functions and
related routines from the graphics library.  See the Amiga ROM Kernel
Reference Manual: Includes and Autodocs for details on each function call.


                  Table 30-5: Layers Library Functions
  ______________________________________________________________________
 |                                                                      |
 |              Function                   Description                  |
 |======================================================================|
 |              @{"NewLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/NewLayerInfo()}  Allocating a @{"Layer_Info" link ADCD_v1.2:Inc&AD2.1/includes/graphics/Layers.h/MAIN 33} structure.      |
 |          @{"DisposeLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/DisposeLayerInfo()}  Deallocating a Layer_Info structure.    |
 |----------------------------------------------------------------------|
 |        @{"CreateUpfrontLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/CreateUpfrontLayer()}  Make a new layer in front of others.    |
 |         @{"CreateBehindLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/CreateBehindLayer()}  Make a new layer behind others.         |
 |               @{"DeleteLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/DeleteLayer()}  Remove and delete an existing layer.    |
 |----------------------------------------------------------------------|
 |                 @{"MoveLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/MoveLayer()}  Change the position (not depth) of a    |
 |                              layer.                                  |
 |                 @{"SizeLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/SizeLayer()}  Change the size of a layer.             |
 |               @{"ScrollLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/ScrollLayer()}  Change the internal coordinates of a    |
 |                              layer.                                  |
 |----------------------------------------------------------------------|
 |               @{"BehindLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/BehindLayer()}  Depth arrange a layer behind others.    |
 |              @{"UpfrontLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UpfrontLayer()}  Depth arrange a layer in front of       |
 |                              others.                                 |
 |        @{"MoveLayerInFrontOf()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/MoveLayerInFrontOf()}  Depth arrange a layer to a specific     |
 |                              position.                               |
 |----------------------------------------------------------------------|
 |                @{"WhichLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/WhichLayer()}  Find the frontmost layer at a position. |
 |----------------------------------------------------------------------|
 |  @{"SwapBitsRastPortClipRect()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/SwapBitsRastPortClipRect()}  Fast, non-layered and non-damaging      |
 |                              display operation.                      |
 |----------------------------------------------------------------------|
 |               @{"BeginUpdate()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/BeginUpdate()}  Synchronize optimized refreshing for    |
 |                              layer.                                  |
 |                 @{"EndUpdate()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/EndUpdate()}  End optimized layer refresh.            |
 |----------------------------------------------------------------------|
 |                 @{"LockLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayer()}  Lock out rendering in a single layer.   |
 |               @{"UnlockLayer()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayer()}  Release LockLayer() lock.               |
 |                @{"LockLayers()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayers()}  Lock out rendering in all layers of a   |
 |                              display.                                |
 |              @{"UnlockLayers()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayers()}  Release LockLayers() lock.              |
 |             @{"LockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/LockLayerInfo()}  Gain exclusive access to the display's  |
 |                              layers.                                 |
 |           @{"UnlockLayerInfo()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/UnlockLayerInfo()}  Release LockLayerInfo() lock.           |
 |----------------------------------------------------------------------|
 |         @{"InstallClipRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/layers/InstallClipRegion()}  Add a clipping region to a layer.       |
 |______________________________________________________________________|


The following routines from graphics library are also required for certain
layers library functions:

  ______________________________________________________________________
 |                                                                      |
 |            Routine                        Description                |
 |======================================================================|
 |         @{"LockLayerRom()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/LockLayerRom()}  Same as LockLayer(), from layers library.    |
 |       @{"UnlockLayerRom()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/UnlockLayerRom()}  Release LockLayerRom() lock.                 |
 |  @{"AttemptLockLayerRom()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/AttemptLockLayerRom()}  Lock layer only if it is immediately         |
 |                         available.                                   |
 |----------------------------------------------------------------------|
 |            @{"NewRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/NewRegion()}  Create a new, empty region.                  |
 |        @{"DisposeRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/DisposeRegion()}  Dispose of an existing region and its        |
 |                         rectangles.                                  |
 |----------------------------------------------------------------------|
 |        @{"AndRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/AndRectRegion()}  AND a rectangle into a region.               |
 |         @{"OrRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/OrRectRegion()}  OR a rectangle into a region.                |
 |        @{"XorRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/XorRectRegion()}  Exclusive-OR a rectangle into a region.      |
 |      @{"ClearRectRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/ClearRectRegion()}  Clear a region.                              |
 |      @{"AndRegionRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/AndRegionRegion()}  AND two regions together.                    |
 |       @{"OrRegionRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/OrRegionRegion()}  OR two regions together.                     |
 |      @{"XorRegionRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/XorRegionRegion()}  Exclusive-OR two regions together.           |
 |          @{"ClearRegion()" link ADCD_v1.2:Inc&AD2.1/autodocs/graphics/ClearRegion()}  Clear a region.                              |
 |______________________________________________________________________|

@ENDNODE
