Blitz3D+ Command Reference

EntityFX entity,fx

Parameters

entity - entity handle
fx - effect flags, added together:
0: none (default)
1: full-bright - ignore scene lighting
2: use vertex colours to tint the material colour
4: flat shaded
8: disable fog
16: disable backface culling - draw both sides of every triangle
32: force alpha blending - required for per-vertex alpha

Description

Sets miscellaneous rendering effects for an entity.

Flags add together, so a value of 3 (1+2) gives an entity that is both full-bright and vertex-coloured.

Flag 1 ignores scene lighting, drawing the material at full strength. It is useful for skyboxes, HUD props and glowing pickups. Flag 2 enables the colours set with VertexColor; in Blitz3D+ these multiply the entity/brush colour, so use a white material to show vertex colours unchanged. Add flag 32 if the vertex colours carry transparency. EntityAlpha and vertex alpha combine, so fading the whole mesh still works.

Flag 4 gives flat shading using each triangle's first vertex as its reference. Classic materials use that corner's lighting and colour across the triangle. Standard and the built-in surface shaders use its normal and colour while retaining texture detail and per-pixel lighting. Texture coordinates and fog continue to vary across the triangle.

Flag 8 exempts the entity from camera fog. Flag 16 switches off backface culling so triangles remain visible from either side, useful for leaves, fences, banners and grass cards. It can increase the work spent drawing hidden surfaces; the cost depends on the geometry and view.

In the Extended renderer, the same sidedness applies when casting shadows. Use flag 16 for thin cards that should cast from either side of a light; texture cutout holes still remain holes. Without it, a one-sided triangle does not cast when its back faces the light, unless its shader specifies two-sided rendering.

These commands remain supported with shaders. An unlit effect already ignores lighting, so flag 1 makes no further change. A shader with fixed culling can override flag 16 and reports a conflicting request. Custom shaders choose which material inputs and flags they support; check their documentation.

The setting replaces whatever was there before rather than adding to it, so pass the full combination each time. It applies to the entity as a whole; for effects on individual surfaces use BrushFX with PaintSurface.

See also: BrushFX, VertexColor, EntityBlend, EntityColor, PaintSurface.

Example

; EntityFX Example
; ----------------

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

camera=CreateCamera()

; Fog tints distant objects, so the disable-fog flag is easy to spot
CameraFogMode camera,1
CameraFogRange camera,1,15
CameraFogColor camera,100,100,140
CameraClsColor camera,100,100,140

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

; A green orb pickup to apply effects to
orb=CreateSphere(16)
PositionEntity orb,0,0,10
EntityColor orb,0,255,0

mode=0

While Not KeyDown(1)

    ; Space cycles through the fx modes
    If KeyHit(57) Then mode=(mode+1) Mod 7

    ; Each mode is a single flag: 0,1,2,4,8,16,32 (flags may also be added together)
    If mode=0 Then fx=0 Else fx=1 Shl (mode-1)
    fx_name$="nothing (default)"
    If fx=1 Then fx_name="full-bright"
    If fx=2 Then fx_name="use vertex colors"
    If fx=4 Then fx_name="flatshaded"
    If fx=8 Then fx_name="disable fog"
    If fx=16 Then fx_name="disable backface culling"
    If fx=32 Then fx_name="force alpha-blending"

    ; Apply the current effect to the orb
    EntityFX orb,fx

    TurnEntity orb,0,1,0

    ; 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,"Space: next fx mode   Arrows: camera   Esc: exit"
    Text 0,20,"EntityFX orb,"+fx+"  ("+fx_name+")"

    Flip

Wend

End

Index