Blitz3D+ Command Reference

MaskImage image,red,green,blue

Parameters

image - handle of the image to change

red - red component of the colour to make transparent, 0 to 255

green - green component, 0 to 255

blue - blue component, 0 to 255

Description

Chooses which colour in an image is treated as transparent.

Every image starts out masked on black, RGB 0,0,0 - so a sprite drawn on a black background just works with DrawImage. The trouble comes when your artwork contains black you want to keep, such as an outline or a shadow: those pixels vanish too. Draw the background in a colour that appears nowhere in the sprite, bright magenta (255,0,255) being the traditional choice, and tell the engine about it with this command.

The match is exact. 254,0,255 is not the same colour as 255,0,255, so save your art in a format that does not resample it - PNG rather than JPEG, which will smear the key colour along every edge and leave a fringe of almost-magenta that does not mask.

The new mask applies to every frame of an animated image at once, and it sticks with the image, so call it once after loading rather than every time you draw. A copy made with CopyImage inherits it.

The mask is more than a drawing trick: the pixel-perfect collision commands ImagesCollide and ImageRectCollide skip masked pixels too, so changing the mask changes the sprite's collision shape. DrawBlock ignores the mask entirely and draws the image solid.

See also: DrawImage, DrawBlock, LoadImage, ImagesCollide, Color.

Example

; MaskImage Example
; -----------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; Spark animstrip - its background pixels are bright pink (255,0,255)
spark=LoadAnimImage("media/spark.bmp",32,32,0,3)

; Images start with black (0,0,0) as the mask colour; use pink instead
MaskImage spark,255,0,255
masked=1

frame=0
timer=MilliSecs()

While Not KeyDown(1)

    Cls

    ; Space swaps between the pink mask and the default black mask
    If KeyHit(57) Then
        masked=1-masked
        If masked=1 Then
            MaskImage spark,255,0,255
        Else
            MaskImage spark,0,0,0
        End If
    End If

    ; Animate the sparks
    If MilliSecs()>timer+120 Then
        timer=MilliSecs()
        frame=(frame+1) Mod 3
    End If

    ; A blue panel behind the sparks makes the transparency obvious
    Color 0,60,130
    Rect 200,160,240,160,True
    For i=0 To 2
        DrawImage spark,240+i*60,220,frame
    Next

    Text 0,0,"Space: toggle the mask colour   Esc: exit"
    If masked=1 Then
        Text 0,20,"MaskImage spark,255,0,255 - pink is now transparent"
    Else
        Text 0,20,"MaskImage spark,0,0,0 - default black mask, pink shows as a box"
    End If

    Flip

Wend

End

Index