Blitz3D+ Command Reference

CreateDecal ( texture[,parent] )

Parameters

texture - texture to project onto the scenery

parent (optional) - parent entity for the new decal; 0 for no parent (default)

Description

Creates a decal entity that projects a texture onto the scenery it touches.

Decals are how games stamp marks onto the world: bullet holes, scorch marks, paint splats, blood, footprints, tyre tracks. A decal does not add geometry - it projects its texture onto whatever surfaces sit inside its projection volume, wrapping naturally over edges and bumps.

The returned handle is an ordinary entity. Position and rotate it, parent it, duplicate it with CopyEntity, remove it with FreeEntity. EntityColor tints the stamp and EntityAlpha fades it (nice for marks that wear away over time). EntityBlend supports alpha blending (the default) and add; other blend modes fall back to alpha with a warning in diagnostics. When decals overlap, EntityOrder controls which one draws on top.

The projection volume covers width by height across the decal's local XY plane and reaches depth units behind that plane, along its local -Z axis - sizes set with DecalSize (1 x 1 x 0.25 to start). The easiest way to place one on a surface is AlignDecal, which sits it flush against a point and normal, typically straight from a pick. Surfaces nearly parallel to the projection direction fade out automatically so the texture does not smear into streaks.

Every entity receives decals by default; opt out characters or water with EntityReceivesDecals. Each RenderWorld draws at most the 256 visible projectors nearest the camera - extras are skipped with a warning in diagnostics - so free old decals (or recycle them) rather than piling them up forever.

For the full story, see the Prototyping and Diagnostics guide.

Requires Extended mode.

See also: AlignDecal, DecalSize, EntityReceivesDecals, RenderDecals, LoadTexture, CopyEntity.

Example

; CreateDecal Example
; -------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,0,-6

light=CreateLight()
RotateEntity light,45,45,0

; A wall to shoot paint splats at
wall=CreateCube()
ScaleEntity wall,4,2.5,0.2
PositionEntity wall,0,0,3
EntityColor wall,110,120,135

; Paint an orange splat texture in memory
splat=CreateTexture(64,64,3)
SetBuffer TextureBuffer(splat)
ClsColor 0,0,0
Cls
Color 255,80,20
Oval 6,6,52,52,True
SetBuffer BackBuffer()
Color 255,255,255

; The aiming reticle sweeps across the wall on its own
sight=CreateSphere()
ScaleEntity sight,0.1,0.1,0.1
EntityColor sight,255,255,0

While Not KeyDown(1)

    ; Sweep the reticle over the wall face
    angle#=angle+2
    aim_x#=3*Sin(angle)
    aim_y#=1.5*Sin(angle*1.7)
    PositionEntity sight,aim_x,aim_y,2.6

    ; Space fires: CreateDecal makes a projector entity that stamps the wall
    If KeyHit(57) Then
        decal=CreateDecal(splat)
        PositionEntity decal,aim_x,aim_y,2.8
        shots=shots+1
    EndIf

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Arrow keys: move camera   Space: fire paint splat   Esc: exit"
    Text 0,20,"CreateDecal(splat) called "+shots+" times - each decal is an ordinary entity"

    Flip

Wend

End

Index