@database "layers"

@Node Main "layers.doc"
@toc "Includes_&_Autodocs/Main"
    @{" 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()"}
    @{" InitLayers() " Link "InitLayers()"}
    @{" InstallClipRegion() " Link "InstallClipRegion()"}
    @{" InstallLayerHook() " Link "InstallLayerHook()"}
    @{" InstallLayerInfoHook() " Link "InstallLayerInfoHook()"}
    @{" LockLayer() " Link "LockLayer()"}
    @{" LockLayerInfo() " Link "LockLayerInfo()"}
    @{" LockLayers() " Link "LockLayers()"}
    @{" MoveLayer() " Link "MoveLayer()"}
    @{" MoveLayerInFrontOf() " Link "MoveLayerInFrontOf()"}
    @{" MoveSizeLayer() " Link "MoveSizeLayer()"}
    @{" NewLayerInfo() " Link "NewLayerInfo()"}
    @{" ScrollLayer() " Link "ScrollLayer()"}
    @{" SizeLayer() " Link "SizeLayer()"}
    @{" SwapBitsRastPortClipRect() " Link "SwapBitsRastPortClipRect()"}
    @{" ThinLayerInfo() " Link "ThinLayerInfo()"}
    @{" UnlockLayer() " Link "UnlockLayer()"}
    @{" UnlockLayerInfo() " Link "UnlockLayerInfo()"}
    @{" UnlockLayers() " Link "UnlockLayers()"}
    @{" UpfrontLayer() " Link "UpfrontLayer()"}
    @{" WhichLayer() " Link "WhichLayer()"}
@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 "includes/exec/types.h/Main" 35} BeginUpdate( struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *);

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

@{b}    SEE ALSO@{ub}
	@{"EndUpdate()" Link "EndUpdate()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/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 "includes/exec/types.h/Main" 35} BehindLayer( @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *);

@{b}    FUNCTION@{ub}
	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 "includes/graphics/layers.h/Main" 30} 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 "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME                                                              (V36)@{ub}
	CreateBehindHookLayer -- Create a new 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 "includes/graphics/clip.h/Main" 26} *CreateBehindHookLayer(struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *, struct @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} *,
	    @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *, ... );

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

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"InstallLayerHook()" Link "InstallLayerHook()"}, @{"DeleteLayer()" Link "DeleteLayer()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0},
	@{"graphics/gfx.h" Link "includes/graphics/gfx.h/Main" 0}, @{"utility/hooks.h" Link "includes/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 "includes/graphics/clip.h/Main" 26} *CreateBehindLayer(struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *, struct @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} *,
	    @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, ... );

@{b}    FUNCTION@{ub}
	Create a new @{"Layer" Link "includes/graphics/clip.h/Main" 26} 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 "includes/graphics/gfx.h/Main" 45} 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 "includes/graphics/layers.h/Main" 0} )
	bm2 - pointer to optional Super @{"BitMap" Link "includes/graphics/gfx.h/Main" 45}

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

@{b}    BUGS@{ub}

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

@EndNode

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

@{b}    NAME                                                              (V36)@{ub}
	CreateUpfrontHookLayer -- Create a new 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 "includes/graphics/clip.h/Main" 26} *CreateUpfrontHookLayer(struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *, struct @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} *,
	    @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *, ... );

@{b}    FUNCTION@{ub}
	Create a new @{"Layer" Link "includes/graphics/clip.h/Main" 26} 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 "includes/graphics/gfx.h/Main" 45} 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 "includes/utility/hooks.h/Main" 27} (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 "includes/graphics/gfx.h/Main" 45}

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"InstallLayerHook()" Link "InstallLayerHook()"}, @{"DeleteLayer()" Link "DeleteLayer()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0},
	@{"graphics/gfx.h" Link "includes/graphics/gfx.h/Main" 0}, @{"utility/hooks.h" Link "includes/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 "includes/graphics/clip.h/Main" 26} *CreateUpfrontLayer(struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *, struct @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} *,
	    @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, ... );

@{b}    FUNCTION@{ub}
	Create a new @{"Layer" Link "includes/graphics/clip.h/Main" 26} 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 "includes/graphics/gfx.h/Main" 45} 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 "includes/graphics/gfx.h/Main" 45}

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
       @{"DeleteLayer()" Link "DeleteLayer()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}, @{"graphics/gfx.h" Link "includes/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 "includes/exec/types.h/Main" 35} DeleteLayer( @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *);

@{b}    FUNCTION@{ub}
	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 "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/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 "includes/graphics/layers.h/Main" 30} *);

@{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 "includes/graphics/layers.h/Main" 30}
	    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 "includes/graphics/layers.h/Main" 30} structure --

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

	-- see documentation 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 "includes/graphics/layers.h/Main" 30} structure itself --
	DisposeLayerInfo(li);


@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"DeleteLayer()" Link "DeleteLayer()"}, @{"graphics/layers.h" Link "includes/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 "includes/utility/hooks.h/Main" 27} *,struct @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} *,struct @{"Rectangle" Link "includes/graphics/gfx.h/Main" 26} *);

@{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, the cliprects are bounded to
	the rectangle given.

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

	       This hook should fill the @{"Rectangle" Link "includes/graphics/gfx.h/Main" 26} in the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}
	       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 "includes/graphics/rastport.h/Main" 53} that is to be operated on.
	       This function will lock the layer if the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} is
	       layered...
	       If the rport is non-layered your hook will be called with
	       the rectangle as passed, the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}, and a 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, no bounding will take place.
	       *MUST* not be NULL if the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} is non-layered!

@{b}    NOTES@{ub}
	The @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} you are passed back is the same one passed to the
	function.  You should *not* use "layered" rendering functions
	on this @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}.  Generally, you will wish to do @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} 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 "includes/graphics/rastport.h/Main" 53}, make sure you use a copy of the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} and NULL the
	@{"Layer" Link "includes/graphics/clip.h/Main" 26} pointer.

@{b}    SEE ALSO@{ub}
	@{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0} @{"utility/hooks.h" Link "includes/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 "includes/graphics/clip.h/Main" 26} *, 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}

@{b}    SEE ALSO@{ub}
	@{"BeginUpdate()" Link "BeginUpdate()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/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 "includes/exec/types.h/Main" 35} FattenLayerInfo( struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *);
	OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    FUNCTION@{ub}
	V1.1 software and any later releases need to have more info in the
	@{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} structure. To do this in a 1.0 supportable manner requires
	allocation and deallocation of the memory whenever most
	layer library functions are called.  To prevent unnecessary
	allocation/deallocation FattenLayerInfo will preallocate the
	necessary data structures and fake out the layer library into
	thinking it has a LayerInfo gotten from @{"NewLayerInfo" Link "layers/NewLayerInfo()"}.
	@{"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 "NewLayerInfo()"}, @{"ThinLayerInfo()" Link "ThinLayerInfo()"}, @{"DisposeLayerInfo()" Link "DisposeLayerInfo()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}

@EndNode

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

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

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

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

@{b}    FUNCTION@{ub}
	Initialize @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} 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 "NewLayerInfo()"}, @{"DisposeLayerInfo()" Link "DisposeLayerInfo()"}, @{"graphics/layers.h" Link "includes/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 "includes/graphics/regions.h/Main" 26} *InstallClipRegion( struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, struct @{"Region" Link "includes/graphics/regions.h/Main" 26} *);

@{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 if no previous ClipRegion installed.

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

@{b}    BUGS@{ub}
	If the system runs out of memory during normal layer operations,
	the @{"ClipRect" Link "includes/graphics/clip.h/Main" 56} list may get swept away and not restored.
	As soon as there is enough memory and the layer library
	gets called again the @{"ClipRect" Link "includes/graphics/clip.h/Main" 56} list will be rebuilt.

@{b}    SEE ALSO@{ub}
	@{"BeginUpdate()" Link "BeginUpdate()"} @{"EndUpdate()" Link "EndUpdate()"},
	@{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}, @{"graphics/regions.h" Link "includes/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 "includes/utility/hooks.h/Main" 27} *InstallLayerHook( struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *);

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

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

	        This hook should fill the @{"Rectangle" Link "includes/graphics/gfx.h/Main" 26} in the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}
	        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 "includes/utility/hooks.h/Main" 27} that was previously
	          active.  Returns 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 "includes/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 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 "includes/graphics/rastport.h/Main" 53} you are passed back is the same one passed to the
	function.  You should *not* use "layered" rendering functions
	on this @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}.  Generally, you will wish to do @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} 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 "includes/graphics/rastport.h/Main" 53}, make sure you use a copy of the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} and NULL the
	@{"Layer" Link "includes/graphics/clip.h/Main" 26} pointer.

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0} @{"utility/hooks.h" Link "includes/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 "includes/utility/hooks.h/Main" 27} *InstallLayerInfoHook(struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *,struct @{"Hook" Link "includes/utility/hooks.h/Main" 27} *);

@{b}    FUNCTION@{ub}
	This function will install a backfill hook for the @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30}
	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 "includes/graphics/rastport.h/Main" 53} 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 "includes/utility/hooks.h/Main" 27} which will be called
	        with object == (struct @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} *) result->RastPort
	        and message == [ (ULONG) undefined, (struct Rectangle) bounds ]

	        This hook should fill the @{"Rectangle" Link "includes/graphics/gfx.h/Main" 26} in the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}
	        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 "includes/graphics/layers.h/Main" 30}.
	          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 "includes/graphics/clip.h/Main" 26}
	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 "includes/graphics/rastport.h/Main" 53} you are passed back is the same one passed to the
	function.  You should *not* use "layered" rendering functions
	on this @{"RastPort" Link "includes/graphics/rastport.h/Main" 53}.  Generally, you will wish to do @{"BitMap" Link "includes/graphics/gfx.h/Main" 45} 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 "includes/graphics/rastport.h/Main" 53}, make sure you use a copy of the @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} and NULL the
	@{"Layer" Link "includes/graphics/clip.h/Main" 26} pointer.

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

@EndNode

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

@{b}    NAME@{ub}
	LockLayer -- Lock layer to make changes to ClipRects.

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

	void LockLayer( @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *);

@{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 "UnlockLayer()"}, @{"LockLayerInfo()" Link "LockLayerInfo()"}, @{"UnlockLayerInfo()" Link "UnlockLayerInfo()"},
	@{"graphics.library/LockLayerRom()" Link "graphics/LockLayerRom()"}, @{"graphics/layers.h" Link "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
	LockLayerInfo -- Lock the LayerInfo structure.

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

	void LockLayerInfo( struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *);

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

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"UnlockLayerInfo()" Link "UnlockLayerInfo()"}, @{"graphics/layers.h" Link "includes/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 "includes/graphics/layers.h/Main" 30} *);

@{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 "includes/graphics/layers.h/Main" 30} structure

@{b}    BUGS@{ub}

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

@EndNode

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

@{b}    NAME@{ub}
	MoveLayer -- Move layer to new position in @{"BitMap" Link "includes/graphics/gfx.h/Main" 45}.

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

	@{"LONG" Link "includes/exec/types.h/Main" 35} MoveLayer( @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}    FUNCTION@{ub}
	Move this layer to new position in shared @{"BitMap" Link "includes/graphics/gfx.h/Main" 45}.
	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 "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/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 "includes/exec/types.h/Main" 35} MoveLayerInFrontOf( struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *);

@{b}    FUNCTION@{ub}
	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 "includes/graphics/layers.h/Main" 30} 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 "includes/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 "includes/exec/types.h/Main" 35} MoveSizeLayer( struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

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

@{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 "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}

@EndNode

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

@{b}    NAME@{ub}
	NewLayerInfo -- Allocate and Initialize full @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} structure.

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

	struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *NewLayerInfo( void );

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

@{b}    INPUTS@{ub}
	None

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"graphics/layers.h" Link "includes/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 "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, LONG);

@{b}    FUNCTION@{ub}
	For a SuperBitMap Layer:
	Update the SuperBitMap from the layer display, then copy bits
	between @{"Layer" Link "includes/graphics/clip.h/Main" 26} 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 "includes/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 "includes/exec/types.h/Main" 35} SizeLayer( @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *, @{"LONG" Link "includes/exec/types.h/Main" 35}, 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 "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}

@EndNode

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

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

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

	void SwapBitsRastPortClipRect( struct @{"RastPort" Link "includes/graphics/rastport.h/Main" 53} *, struct @{"ClipRect" Link "includes/graphics/clip.h/Main" 56} *);

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

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

@{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.

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"graphics/clip.h" Link "includes/graphics/clip.h/Main" 0}, @{"graphics/rastport.h" Link "includes/graphics/rastport.h/Main" 0}, @{"graphics/clip.h" Link "includes/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 "includes/graphics/layers.h/Main" 30} *);
	OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

@{b}    FUNCTION@{ub}
	return the extra memory needed that was allocated with
	@{"FattenLayerInfo" Link "layers/FattenLayerInfo()"}. This is must be done prior to freeing
	the @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} structure itself. V1.1 software should be
	using @{"DisposeLayerInfo" Link "layers/DisposeLayerInfo()"}.

@{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 "includes/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 "includes/graphics/clip.h/Main" 26} *);

@{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 "includes/graphics/layers.h/Main" 0}, @{"graphics/clip.h" Link "includes/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 "includes/graphics/layers.h/Main" 30} *);

@{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 "includes/graphics/layers.h/Main" 30} structure

@{b}     BUGS@{ub}

@{b}     SEE ALSO@{ub}
	@{"LockLayerInfo()" Link "LockLayerInfo()"}, @{"graphics/layers.h" Link "includes/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}
	UnlockLayers( li )
	              a0

	void UnlockLayers( struct @{"Layer_Info" Link "includes/graphics/layers.h/Main" 30} *);

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

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

@{b}    BUGS@{ub}

@{b}    SEE ALSO@{ub}
	@{"LockLayers()" Link "LockLayers()"}, @{"UnlockLayer()" Link "UnlockLayer()"}, @{"graphics/layers.h" Link "includes/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 "includes/exec/types.h/Main" 35} UpfrontLayer( @{"LONG" Link "includes/exec/types.h/Main" 35}, struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *);

@{b}    FUNCTION@{ub}
	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 "includes/graphics/layers.h/Main" 30} 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 "includes/graphics/layers.h/Main" 0}

@EndNode

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

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

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

	struct @{"Layer" Link "includes/graphics/clip.h/Main" 26} *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 if there is no layer at this point.

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

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

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

@EndNode

