layers.library Reference

Comprehensive function reference for layers.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/layers).

This page documents 38 functions of layers.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

AllocClipRect()

AllocClipRect -- build a ClipRect

Synopsis

cliprect = AllocClipRect( li ) d0 a0

ClipRect*AllocClipRect(Layer_Info*);

Function

This function allocates a new ClipRect from a Layer_Info structure and returns a pointer to the ClipRect. The ClipRect is inialized up to the cliprect bounds. NOTE THAT THIS FUNCTION IS PRIVATE. You should never play with layer cliprects yourself and never attach this cliprect to a layer yourself. This cliprect belongs to the given Layer_Info structure and must be released before the Layer_Info gets released.

Inputs

li - pointer to a Layer_Info to allocate the ClipRect from.

Results

cliprect - a pointer to a ClipRect structure or NULL in case the system run out of memory.

See also

FreeClipRect()

BeginUpdate()

BeginUpdate -- Prepare to repair damaged layer.

Synopsis

result = BeginUpdate( l ) d0 a0

LONG BeginUpdate(Layer*);

Function

Convert damage list to ClipRect list and swap in for programmer to redraw through. This routine simulates the ROM library environment. The idea is to only render in the "damaged" areas, saving time over redrawing all of the layer. The layer is locked against changes made by the layer library.

Inputs

l - pointer to a layer

Results

result - TRUE if damage list converted to ClipRect list successfully. FALSE if list conversion aborted. (probably out of memory)

Bugs

If BeginUpdate returns FALSE, programmer must abort the attempt to refresh this layer and instead call EndUpdate( l, FALSE ) to restore original ClipRect and damage list.

See also

EndUpdate()

BehindLayer()

BehindLayer -- Put layer behind other layers.

Synopsis

result = BehindLayer( dummy, l ) d0 a0 a1

LONG BehindLayer( LONG,Layer*);

Function

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

   Note: this operation may generate refresh events in other layers
      associated with this layer's Layer_Info structure.

Inputs

dummy - unused l - pointer to a layer

Results

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

CreateBehindHookLayer()

Synopsis

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

Layer*CreateBehindHookLayer(Layer_Info*,BitMap*, LONG, LONG, LONG, LONG, LONG,Hook*, ... );

Function

Create a new Layer of position and size (x0,y0)->(x1,y1) 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. If this layer is a backdrop layer then place it behind all other layers including other backdrop layers. If this is not a backdrop layer then place it behind all nonbackdrop layers.

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

Inputs

li - pointer to LayerInfo structure bm - pointer to common BitMap 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 ) hook - Layer->BackFill callback Hook (see 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

Results

result - pointer to Layer structure if successful NULL if not successful

See also

InstallLayerHook(), DeleteLayer()

CreateBehindLayer()

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

Synopsis

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

Layer*CreateBehindLayer(Layer_Info*,BitMap*, LONG, LONG, LONG, LONG, LONG, ... );

Function

Create a new Layer of position and size (x0,y0)->(x1,y1) Make this layer of type found in flags. If SuperBitMap, use bm2 as pointer to real SuperBitMap, and copy contents of Superbitmap into display layer. If this layer is a backdrop layer then place it behind all other layers including other backdrop layers. If this is not a backdrop layer then place it behind all nonbackdrop layers.

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

Inputs

li - pointer to LayerInfo structure bm - pointer to common BitMap 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 ) bm2 - pointer to optional Super BitMap

Results

result - pointer to Layer structure if successful NULL if not successful

See also

DeleteLayer()

CreateUpfrontHookLayer()

Synopsis

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

Layer*CreateUpfrontHookLayer(Layer_Info*,BitMap* , LONG, LONG, LONG, LONG, LONG,Hook*, ... );

Function

Create a new Layer 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.

Inputs

li - pointer to LayerInfo structure bm - pointer to common BitMap 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 (see 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

Results

result - pointer to Layer structure if successful NULL if not successful

See also

InstallLayerHook(), DeleteLayer()

CreateUpfrontLayer()

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

Synopsis

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

Layer*CreateUpfrontLayer(Layer_Info*,BitMap*, LONG, LONG, LONG, LONG, LONG, ... );

Function

Create a new Layer of position and size (x0,y0)->(x1,y1) and place it on top of all other layers. Make this layer of type found in flags if SuperBitMap, use bm2 as pointer to real SuperBitMap. and copy contents of Superbitmap into display layer.

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

Inputs

li - pointer to LayerInfo structure bm - pointer to common BitMap 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

Results

result - pointer to Layer structure if successful NULL if not successful

See also

DeleteLayer()

DeleteLayer()

DeleteLayer -- delete layer from layer list.

Synopsis

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

LONG DeleteLayer( LONG,Layer*);

Function

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

Inputs

dummy - unused l - pointer to a layer

Results

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

DisposeLayerInfo()

DisposeLayerInfo -- Return all memory for LayerInfo to memory pool

Synopsis

DisposeLayerInfo( li ) a0

void DisposeLayerInfo(Layer_Info*);

Function

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

   Note: if you wish to delete the layers associated with this Layer_Info
       structure, remember to call DeleteLayer() for each of the layers
       before calling DisposeLayerInfo().

Inputs

li - pointer to LayerInfo structure

Example

-- delete the layers associated this Layer_Info structure --

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

   -- see docs on DeleteLayer about deleting SuperBitMap layers --
   my_super_bitmap_ptr = super_layer->SuperBitMap;
   DeleteLayer(li,super_layer);

   -- now dispose of the Layer_Info structure itself --
   DisposeLayerInfo(li);

See also

DeleteLayer()

DoHookClipRects()

DoHookClipRects - Do the given hook for each of the ClipRects (V39)

Synopsis

DoHookClipRects(hook,rport,rect) a0 a1 a2

void DoHookClipRects(Hook*,RastPort*, Rectangle*);

Function

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.

Inputs

hook - pointer to layer callback Hook which will be called with object == (struct RastPort ) result->RastPort and message == [ (Layer ) layer, (struct Rectangle) bounds, (LONG) offsetx, (LONG) offsety ]

          This hook should fill the Rectangle in the RastPort
          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 that is to be operated on.
          This function will lock the layer if the RastPort is
          layered...
          If the rport is non-layered your hook will be called with
          the rectangle as passed, the RastPort, 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 is non-layered!

Notes

The RastPort you are passed back is the same one passed to the function. You should not use "layered" rendering functions on this RastPort. Generally, you will wish to do BitMap operations such as BltBitMap(). The callback is a raw, low-level rendering call-back. If you need to call a rendering operation with a RastPort, make sure you use a copy of the RastPort and NULL the Layer pointer.

EndUpdate()

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

Synopsis

EndUpdate( l, flag ) a0 d0

void EndUpdate(Layer*, UWORD);

Function

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

   Note: use flag = FALSE if you are only making a partial update.
   You may use the other region functions (graphics functions such as
   OrRectRegion, AndRectRegion, and XorRectRegion ) to clip adjust
   the DamageList to reflect a partial update.

Inputs

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

Example

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

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

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

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

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

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

Bugs

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

See also

BeginUpdate()

FattenLayerInfo()

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

Synopsis

OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE FattenLayerInfo( li ) a0

LONG FattenLayerInfo(Layer_Info*); OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

Function

As of V45, this function does nothing and returns TRUE. V45 no longer requires additional information in the Layers_Info, but nevertheless, this function MUST NOT be used for new code. In case the system (Intuition, namely) must roll its own Layer_Info, it is mandatory to call ThinLayerInfo() if you are done with it as it releases some additional internal buffers. NewLayerInfo is the approved method for getting this structure. When a program needs to give up the LayerInfo structure it must call ThinLayerInfo before freeing the memory. ThinLayerInfo is not necessary if New/DisposeLayerInfo are used however.

Inputs

li - pointer to LayerInfo structure

See also

NewLayerInfo(), ThinLayerInfo(), DisposeLayerInfo()

FreeClipRect()

FreeClipRect -- release a ClipRect build by AllocClipRect

Synopsis

FreeClipRect( li, cliprect ) a0 a1

void FreeClipRect(Layer_Info*li,ClipRect*cr);

Function

Disposes a ClipRect that is no longer required by the caller. The ClipRect is either released immedately into the free memory pool, or gets recycled by layers as soon as clipping operations are performed in the same Layer_Info.

   This function also releases the BitMap linked to by the ClipRect.
   In case you disposed this bitmap already, make sure that you
   NULL cr->BitMap before calling this function.

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

Inputs

li - pointer to a Layer_Info the ClipRect has been allocated from by means of AllocClipRect()

See also

AllocClipRect()

HideLayer()

HideLayer -- Make layer invisible (V45)

Synopsis

result = HideLayer( l ) d0 a0

LONG HideLayer(Layer*);

Function

Move this layer behind the bottommost layer and make all of its cliprects invisible. For LAYERSMART layers, copy all image data into the backing store of the layer. This operation may generate refresh events in other layers associated with this layer's Layer_Info structure.

Inputs

l - pointer to a layer

Results

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

InitLayers()

InitLayers -- Initialize Layer_Info structure OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

Synopsis

OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE InitLayers( li ) a0

void InitLayers(Layer_Info*); OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

Function

Initialize Layer_Info structure in preparation to use other layer operations on this list of layers. Make the Layers unlocked (open), available to layer operations.

Inputs

li - pointer to LayerInfo structure

See also

NewLayerInfo(), DisposeLayerInfo()

InstallClipRegion()

InstallClipRegion -- Install clip region in layer

Synopsis

oldclipregion = InstallClipRegion( l, region ) d0 a0 a1

Region*InstallClipRegion(Layer*,Region*);

Function

Installs a transparent Clip region in the layer. All subsequent graphics calls will be clipped to this region. You MUST remember to call InstallClipRegion(l,NULL) before calling DeleteLayer(l) or the Intuition function CloseWindow() if you have installed a non-NULL ClipRegion in l.

Inputs

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

Results

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

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

Notes

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

Bugs

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

See also

BeginUpdate(), EndUpdate()

InstallLayerHook()

InstallLayerHook -- safely install a new Layer->BackFill hook.(V36)

Synopsis

oldhook = InstallLayerHook( layer, hook ) d0 a0 a1

Hook*InstallLayerHook(Layer*,Hook*);

Function

Installs a new Layer->Backfill Hook, waiting until it is safe to do so. Locks the layer while substituting the new Hook and removing the old one. If a new Hook is not provided, will install the default layer BackFill Hook.

Inputs

layer - pointer to the layer in which to install the Backfill Hook. hook - pointer to layer callback Hook which will be called with object == (struct RastPort ) result->RastPort and message == [ (Layer ) layer, (struct Rectangle) bounds, (LONG) offsetx, (LONG) offsety ]

           This hook should fill the Rectangle in the RastPort
           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).

Results

oldhook - pointer to the Layer->BackFill Hook that was previously active. Returns NULL if it was the default hook. In V39, it could return 1 if there was no hook.

Notes

The RastPort you are passed back is the same one passed to the function. You should not use "layered" rendering functions on this RastPort. Generally, you will wish to do BitMap operations such as BltBitMap(). The callback is a raw, low-level rendering call-back. If you need to call a rendering operation with a RastPort, make sure you use a copy of the RastPort and NULL the Layer pointer.

Example

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
                   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         ; Do the backfill-0
   *
   HookDone:       movem.l (sp)+,d2-d7/a3-a6 ; Restore
                   rts

InstallLayerInfoHook()

InstallLayerInfoHook - Install a backfill hook for non-layer (V39)

Synopsis

oldhook=InstallLayerInfoHook(li,hook) d0 a0 a1

Hook*InstallLayerInfoHook(Layer_Info*,Hook*);

Function

This function will install a backfill hook for the Layer_Info structure passed. This backfill hook will be used to clear the background area where no layer exists. The hook function is passed the RastPort and the bounds just like the layer backfill hook. Note that this hook could be called for any layer.

Inputs

li - pointer to LayerInfo structure

   hook -  pointer to layer callback Hook which will be called
       with object == (struct RastPort *) result->RastPort
       and message == [ (ULONG) undefined, (struct Rectangle) bounds ]

           This hook should fill the Rectangle in the RastPort
           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).

Results

oldhook - Returns the backfill hook that was in the Layer_Info. 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.

Notes

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 you are passed back is the same one passed to the
   function.  You should *not* use "layered" rendering functions
   on this RastPort.  Generally, you will wish to do BitMap operations
   such as BltBitMap().  The callback is a raw, low-level rendering
   call-back.  If you need to call a rendering operation with a
   RastPort, make sure you use a copy of the RastPort and NULL the
   Layer pointer.

Example

See the example in InstallLayerHook. Note that both the Layer pointer and the OffsetX/Y values are not available in the LayerInfo backfill hook.

See also

InstallLayerHook()

LayerOccluded()

LayerOccluded -- Is Layer occluded by any other layer (V45)

Synopsis

occluded = LayerOccluded( l ) d0 a0

LONG LayerOccluded(Layer*);

Function

This function checks whether the indicated layer is occluded by any other layer of the same layer info. It returns FALSE in case the layer is fully visible, or returns TRUE if parts of this layer are covered by any other layer of the same Layer_Info.

Inputs

l = pointer to Layer structure

Results

occluded - a boolean TRUE/FALSE indicator

Notes

You should at least lock the Layer_Info of the layer or the result is unpredictable as the layer arrangement may change while this function is running.

See also

LockLayerInfo()

LockLayer()

LockLayer -- Lock layer to make changes to ClipRects.

Synopsis

LockLayer( dummy, l ) a0 a1

void LockLayer( LONG,Layer*);

Function

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

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

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

Inputs

dummy - unused l - pointer to a layer

See also

UnlockLayer(), LockLayerInfo(), UnlockLayerInfo(), LockLayerRom()

LockLayerInfo()

LockLayerInfo -- Lock the LayerInfo structure.

Synopsis

LockLayerInfo( li ) a0

void LockLayerInfo(Layer_Info*);

Function

Before doing an operation that requires the LayerInfo structure, make sure that no other task is also using the LayerInfo structure. LockLayerInfo() returns when the LayerInfo belongs to this task. There should be an UnlockLayerInfo for every LockLayerInfo.

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

Inputs

li - pointer to Layer_Info structure

See also

UnlockLayerInfo()

LockLayers()

LockLayers -- lock all layers from graphics output.

Synopsis

LockLayers( li ) a0

void LockLayers(Layer_Info*);

Function

First calls LockLayerInfo() Make all layers in this layer list locked.

Inputs

li - pointer to Layer_Info structure

Bugs

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

See also

UnlockLayer(), LockLayerInfo()

MoveLayer()

MoveLayer -- Move layer to new position in BitMap.

Synopsis

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

LONG MoveLayer( LONG,Layer*, LONG, LONG);

Function

Move this layer to new position in shared BitMap. If any refresh layers become revealed, collect damage and set REFRESH bit in layer Flags.

Inputs

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

Bugs

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

MoveLayerInFrontOf()

MoveLayerInFrontOf -- Put layer in front of another layer.

Synopsis

result = MoveLayerInFrontOf( layertomove, targetlayer ) a0 a1

LONG MoveLayerInFrontOf(Layer*,Layer*);

Function

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

   Note: this operation may generate refresh events in other layers
       associated with this layer's Layer_Info structure.

Inputs

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

Results

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

MoveSizeLayer()

Synopsis

result = MoveSizeLayer( layer, dx, dy, dw, dh ) d0 a0 d0 d1 d2 d3

LONG MoveSizeLayer(Layer*, LONG, LONG, LONG, LONG);

Function

Change upperleft and lower right position of Layer.

Inputs

dummy - unused l - pointer to a nonbackdrop layer dx,dy - change upper left corner by (dx,dy) dw,dy - change size by (dw,dh)

NewLayerInfo()

NewLayerInfo -- Allocate and Initialize full Layer_Info structure.

Synopsis

result = NewLayerInfo() d0

Layer_Info*NewLayerInfo( void );

Function

Allocate memory required for full Layer_Info structure. Initialize Layer_Info structure in preparation to use other layer operations on this list of layers. Make the Layer_Info unlocked (open).

Inputs

None

Results

result- pointer to Layer_Info structure if successful NULL if not enough memory

ScrollLayer()

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

Synopsis

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

void ScrollLayer( LONG,Layer*, LONG, LONG);

Function

For a SuperBitMap Layer: Update the SuperBitMap from the layer display, then copy bits between Layer 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 to simulate Intuition GZZWindows without the overhead of an extra layer.

Inputs

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

Bugs

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

SetLayerInfoBounds()

SetLayerInfoBounds -- define clipping bounds for all layers (V45)

Synopsis

ok = SetLayerInfoBounds( li, bounds ); d0 a0 a1

LONG SetLayerInfoBounds(Layer_Info*,Rectangle*r);

Function

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

Inputs

li = pointer to Layer_Info structure r = rectangle describing hard clipping bounds for this Layer_Info. The contents of the rectangle is copied, and "r" may be re-used as soon as SetLayerInfoBounds returns.

Results

ok - a boolean success/failure indicator. TRUE on success.

Notes

This function absolutely MUST be called before the first layer gets installed into this Layer_Info. It will not affect clipping of already existing layers. Default Layer_Info clipping is MIN_WORD to MAX_WORD, i.e. no clipping takes place. This is V40 behaivour.

ShowLayer()

ShowLayer -- Make invisible layer visible again (V45)

Synopsis

result = ShowLayer( l , other ) d0 a0 a1

LONG ShowLayer(Layer*,Layer* );

Function

Make this layer visible again and move it in front of the "other" layer. For LAYERSMART layers, copy the image from the backding store back on the screen, for simple layers, generate apropriate damage. If the layer is not hidden, this call does nothing. This operation may generate refresh events in other layers associated with this layer's Layer_Info structure.

Inputs

l - pointer to a layer to un-hide other - pointer to layer to move in front of. for NULL, this layer is moved into the background behind layers of similar kind, for (struct Layer *)1, this layer is moved on top of the layer stack of layers of similar kind.

Results

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

SizeLayer()

SizeLayer -- Change the size of this nonbackdrop layer.

Synopsis

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

LONG SizeLayer( LONG,Layer*, LONG, LONG);

Function

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

Inputs

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

Results

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

SortLayerCR()

SortLayerCR - Sort the layer's cliprects for scroll raster (V39)

Synopsis

SortLayerCR(layer,dx,dy) A0 D0 D1

VOID SortLayerCR(Layer*,WORD,WORD);

Function

This function will sort the give layer's cliprects such that a scroll in the direction given will be optimal.

Inputs

layer - The layer to be sorted... dx - x scroll offset dy - y scroll offset

Note

This routine is for Layers/Graphics internal use only. The layer must be locked before calling this routine.

SwapBitsRastPortClipRect()

SwapBitsRastPortClipRect -- Swap bits between common bitmap and obscured ClipRect

Synopsis

SwapBitsRastPortClipRect( rp, cr ) a0 a1

void SwapBitsRastPortClipRect(RastPort*,ClipRect*);

Function

Support routine useful for those that need to do some operations not done by the layer library. Allows programmer to swap the contents of a small BitMap with a subsection of the display. This is accomplished without using extra memory. The bits in the display RastPort are exchanged with the bits in the ClipRect's BitMap.

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

Inputs

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

Note

Because the blit operation started by this function is done asynchronously, it is imperative that a WaitBlit() be performed before releasing or using the processor to modify any of the associated structures.

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

ThinLayerInfo()

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

Synopsis

OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE ThinLayerInfo( li ) a0

void ThinLayerInfo(Layer_Info*); OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

Function

In V45, this function only flushes the cliprect scratch list of the layer info. New software MUST use DisposeLayerInfo() instead.

Inputs

li - pointer to LayerInfo structure

See also

DisposeLayerInfo(), FattenLayerInfo()

UnlockLayer()

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

Synopsis

UnlockLayer( l ) a0

void UnlockLayer(Layer*);

Function

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

Inputs

l - pointer to a layer

UnlockLayerInfo()

UnlockLayerInfo -- Unlock the LayerInfo structure.

Synopsis

UnlockLayerInfo( li ) a0

void UnlockLayerInfo(Layer_Info*);

Function

After the operation is complete that required a LockLayerInfo, unlock the LayerInfo structure so that other tasks may affect the layers.

Inputs

li - pointer to the Layer_Info structure

See also

LockLayerInfo()

UnlockLayers()

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

Synopsis

ok = UnlockLayers( li ) a0

BOOL UnlockLayers(Layer_Info*);

Function

Make all layers in this layer list unlocked. Then calls UnlockLayerInfo

Inputs

li - pointer to the Layer_Info structure

Results

returns a boolean TRUE/FALSE condition for backwards compatibility. V45 and above will always return TRUE.

Bugs

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

See also

LockLayers(), UnlockLayer()

UpfrontLayer()

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

Synopsis

result = UpfrontLayer( dummy, l ) d0 a0 a1

LONG UpfrontLayer( LONG,Layer*);

Function

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

   Note: this operation may generate refresh events in other layers
      associated with this layer's Layer_Info structure.

Inputs

dummy - unused l - pointer to a nonbackdrop layer

Results

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

WhichLayer()

WhichLayer -- Which Layer is this point in?

Synopsis

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

Layer*WhichLayer(Layer_Info*, WORD, WORD);

Function

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

Inputs

li = pointer to LayerInfo structure (x,y) = coordinate in the BitMap

Results

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

Notes

You should at least lock the Layer_Info of the layer or the result is unpredictable as the layer arrangement may change while this function is running.