Blending & Compositing API

Layer Management

EnableLayers()
Enables the layer system for the current context

GetLayerManager() *LayerManager
Returns the layer manager for the current context

AddLayer(name string) *Layer
Creates and adds a new layer with the specified name

SetActiveLayer(index int)
Sets the active layer for drawing operations

// Enable layer system
dc.EnableLayers()
lm := dc.GetLayerManager()

// Create layers
backgroundLayer := lm.GetActiveLayer()
backgroundLayer.Name = "Background"

overlayLayer := lm.AddLayer("Overlay")
overlayLayer.SetBlendMode(advancegg.BlendModeMultiply)
overlayLayer.SetOpacity(0.8)

// Draw on specific layers
lm.SetActiveLayer(0) // Background
dc.SetRGB(0.2, 0.4, 0.8)
dc.DrawRectangle(0, 0, 400, 300)
dc.Fill()

lm.SetActiveLayer(1) // Overlay
dc.SetRGB(1, 0.3, 0.3)
dc.DrawCircle(200, 150, 100)
dc.Fill()

// Composite all layers
result := lm.Composite()

Blend Modes

AdvanceGG supports 13 professional blend modes with accurate color mathematics:

Normal

Default blending mode. Top layer completely covers bottom layer.

BlendModeNormal

Result = Source

Multiply

Multiplies colors, resulting in darker output. White has no effect.

BlendModeMultiply

Result = Source × Destination

Screen

Inverts, multiplies, and inverts again. Results in lighter output.

BlendModeScreen

Result = 1 - (1-S) × (1-D)

Overlay

Combines multiply and screen. Enhances contrast.

BlendModeOverlay

If D < 0.5: 2×S×D
Else: 1-2×(1-S)×(1-D)

Soft Light

Subtle lighting effect. Darkens or lightens based on source.

BlendModeSoftLight

Complex formula using
dodge and burn operations

Hard Light

Strong lighting effect. Like overlay but with source and destination swapped.

BlendModeHardLight

If S < 0.5: 2×S×D
Else: 1-2×(1-S)×(1-D)

Color Dodge

Brightens destination based on source. Creates bright, saturated colors.

BlendModeColorDodge

Result = D / (1 - S)

Color Burn

Darkens destination based on source. Creates dark, saturated colors.

BlendModeColorBurn

Result = 1 - (1-D) / S

Darken

Selects the darker of the two colors for each pixel.

BlendModeDarken

Result = min(S, D)

Lighten

Selects the lighter of the two colors for each pixel.

BlendModeLighten

Result = max(S, D)

Difference

Subtracts colors, creating high contrast effects.

BlendModeDifference

Result = |S - D|

Exclusion

Similar to difference but with lower contrast.

BlendModeExclusion

Result = S + D - 2×S×D

Layer Properties

SetBlendMode(mode BlendMode)
Sets the blend mode for the layer

SetOpacity(opacity float64)
Sets the layer opacity (0.0 to 1.0)

SetVisible(visible bool)
Sets the layer visibility

GetBlendMode() BlendMode
Returns the current blend mode

// Layer properties
layer := lm.AddLayer("Effect Layer")

// Set blend mode
layer.SetBlendMode(advancegg.BlendModeMultiply)

// Set opacity (50% transparent)
layer.SetOpacity(0.5)

// Hide/show layer
layer.SetVisible(false)
layer.SetVisible(true)

// Get current properties
mode := layer.GetBlendMode()
opacity := layer.GetOpacity()
visible := layer.IsVisible()

Advanced Compositing

// Complex layer composition example
func createComplexComposition(dc *advancegg.Context) {
    // Enable layers
    dc.EnableLayers()
    lm := dc.GetLayerManager()
    
    // Background layer
    bg := lm.GetActiveLayer()
    bg.Name = "Background"
    lm.SetActiveLayer(0)
    
    // Create gradient background
    gradient := advancegg.NewLinearGradient(0, 0, 400, 300)
    gradient.AddColorStop(0, color.RGBA{100, 150, 200, 255})
    gradient.AddColorStop(1, color.RGBA{200, 100, 150, 255})
    dc.SetFillStyle(gradient)
    dc.DrawRectangle(0, 0, 400, 300)
    dc.Fill()
    
    // Multiply layer for shadows
    shadowLayer := lm.AddLayer("Shadows")
    shadowLayer.SetBlendMode(advancegg.BlendModeMultiply)
    shadowLayer.SetOpacity(0.6)
    lm.SetActiveLayer(1)
    
    dc.SetRGBA(0, 0, 0, 0.5)
    dc.DrawCircle(220, 170, 80)
    dc.Fill()
    
    // Screen layer for highlights
    highlightLayer := lm.AddLayer("Highlights")
    highlightLayer.SetBlendMode(advancegg.BlendModeScreen)
    highlightLayer.SetOpacity(0.8)
    lm.SetActiveLayer(2)
    
    dc.SetRGBA(1, 1, 1, 0.7)
    dc.DrawCircle(180, 130, 60)
    dc.Fill()
    
    // Overlay layer for main content
    contentLayer := lm.AddLayer("Content")
    contentLayer.SetBlendMode(advancegg.BlendModeOverlay)
    lm.SetActiveLayer(3)
    
    dc.SetRGB(1, 0.5, 0.2)
    dc.DrawCircle(200, 150, 70)
    dc.Fill()
    
    // Composite all layers
    result := lm.Composite()
    return result
}

Performance Considerations

Optimization Tips

Layer Count: Keep the number of layers reasonable (typically < 20)
Blend Modes: Normal mode is fastest, complex modes like Soft Light are slower
Opacity: Fully opaque layers (1.0) are faster than transparent ones
Compositing: Call Composite() only when needed, not every frame
Memory: Large layers consume more memory; consider layer size optimization