BeginLayer - ProGUI Reference Manual

Syntax

BeginLayer(x.d, y.d, Width.d, Height.d, Opacity.f=1, OpacityBrush=#Null, Border=#Null)

Description

Pushes a layer onto the drawing stack. Subsequent drawing operations are rendered into an intermediate off-screen surface bounded by the specified dimensions. When EndLayer() is called, the content of this intermediate surface is blended onto the underlying drawing target, optionally applying the specified opacity, opacity brush (for alpha masking), and border.

Parameters

x.d
The horizontal coordinate of the layer's top-left corner in device-independent pixels (DIPs) relative to the current drawing context's origin.

y.d
The vertical coordinate of the layer's top-left corner in DIPs relative to the current drawing context's origin.

Width.d
The width of the layer in DIPs.

Height.d
The height of the layer in DIPs.

Opacity.f (optional)
A value between 0.0 (fully transparent) and 1.0 (fully opaque) representing the opacity to apply when blending the layer back onto the target. Default is 1.0.

OpacityBrush (optional)
A brush handle (usually created from an image with an alpha channel using CreateBrushImg()). The alpha channel of this brush is used as a mask when blending the layer. Default is #Null (no mask).

Border (optional)
A border handle created using CreateBorder() or CreateBorderImg(). If provided, this border is drawn *after* the layer content is blended, effectively framing the layer. Default is #Null.

Return Value

This command does not return a value.

Remarks

Layers are useful for applying effects like opacity or masking to a group of drawing operations without affecting elements drawn before or after the layer. They can also improve performance in some scenarios by rendering complex groups off-screen once. The coordinate system for drawing commands between BeginLayer() and EndLayer() is relative to the layer's top-left corner (x, y). Every call to BeginLayer() must be balanced with a call to EndLayer(). Borders specified here are drawn *after* the layer content is composited, effectively framing the composited result. If a border *and* an opacity brush are used, the opacity mask is applied first, then the layer content is drawn, and finally the border is drawn on top.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

Global AlphaMaskBrush

Procedure DrawHandler(Window, EventType, *EventData.PG_EventDraw, *UserData)
  DrawClear(RGB(200, 200, 200), 1)

  ; Draw something underneath
  DrawBox(10, 10, 380, 280, RGB(0, 155, 0))

  ; Begin a layer with 50% opacity and an alpha mask
  BeginLayer(50, 50, 300, 200, 0.5, AlphaMaskBrush)

  ; Draw content within the layer (coordinates are relative to layer origin 50,50)
  DrawClear(RGB(255, 255, 0), 1) ; Layer background (yellow)
  DrawBox(10, 10, 100, 100, RGB(255, 0, 0), 1) ; Red box inside layer
  DrawTxt(*UserData, 120, 50, RGB(0, 0, 0), 1) ; Text inside layer

  ; End the layer - its content will be blended onto the window
  EndLayer()
EndProcedure

; Create an alpha mask image (simple gradient)
MaskImage = CreateImg(300, 200, #PG_Img_Transparent, #PG_Img_Format_A8)
If BeginDraw(OutputImg(MaskImage))
  Gradient = CreateBrushGradientLinear(0, 0, 0, 200, 0, 1.0, 0, 0.0) ; Black (opaque) to Transparent
  DrawBoxFill(0, 0, 300, 200, Gradient)
  FreeBrush(Gradient)
  EndDraw()
  AlphaMaskBrush = CreateBrushImg(MaskImage)
  BrushSetInterpolationMode(AlphaMaskBrush, #PG_InterpolationMode_Nearest)
EndIf

MyWindow = CreateWindow(0, 0, 400, 300, "Layer Example")
MyText = CreateText("Layer Content", "Arial", 14)

If MyWindow
  AddEventHandler(MyWindow, #PG_Event_Draw, @DrawHandler(), MyText)
  WindowShow(MyWindow, #True, #PG_WindowShow_ScreenCentered)

  Repeat
    Event = WaitWindowEvent()
  Until Event = #PB_Event_CloseWindow
EndIf

If AlphaMaskBrush : FreeBrush(AlphaMaskBrush) : EndIf
If MaskImage : FreeImg(MaskImage) : EndIf
FreeText(MyText)

StopProGUI()

Supported OS

Windows, Linux