Blitz3D+ Command Reference

VertexAlpha# ( surface,index )

Parameters

surface - handle of the surface the vertex belongs to

index - vertex number, 0 to CountVertices(surface)-1

Description

Returns a vertex's alpha value, from 0 (invisible) to 1 (solid).

Vertex alpha is the per-corner transparency you set with the last argument of VertexColor. It is what gives you a force field that fades out at the top, grass cards that dissolve into the ground, a water surface that goes clear at the shoreline, or a beam that thins out along its length - effects that a single EntityAlpha, which fades a whole entity evenly, simply cannot do. VertexAlpha is the read-back half of that: it tells you what a vertex is currently set to.

For any of it to be visible the entity has to be told to use vertex colours and to blend: EntityFX mesh,2 turns on vertex colouring and EntityBlend mesh,1 switches on alpha blending. Classic Blitz3D also wanted FX flag 32 for vertex alpha specifically; that flag is accepted and harmless here but no longer does anything, so EntityFX mesh,2+32 stays portable between the two. The final transparency is the vertex alpha multiplied by the entity's own EntityAlpha.

Values are stored as a single byte per vertex, so what you read back is quantised to steps of 1/255. Set 0.5 and VertexAlpha returns 0.498039 - close enough for anything visual, but never compare it with = against the number you wrote. A vertex you have never coloured reads 1.0, which is the sensible default of "completely solid".

Reading vertices one at a time is fine for a handful of them and slow across a whole model, so keep it out of your inner loop when a mesh has thousands. If you are animating a fade, it is usually cheaper to keep the value in your own variable and just write it with VertexColor each frame.

See also: VertexColor, VertexRed, VertexGreen, VertexBlue, EntityAlpha, EntityBlend.

Example

; VertexAlpha Example
; -------------------

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

camera=CreateCamera()
PositionEntity camera,0,1.5,-5

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

; Something solid behind the panel, so the see-through part is obvious
crate=CreateCube()
PositionEntity crate,0,1,3
EntityColor crate,200,150,80

; A hologram panel built by hand, so we can set alpha per vertex
panel=CreateMesh()
surf=CreateSurface(panel)
AddVertex surf,-1.5,0,0
AddVertex surf,1.5,0,0
AddVertex surf,1.5,3,0
AddVertex surf,-1.5,3,0
AddTriangle surf,0,1,2
AddTriangle surf,0,2,3

; Full-bright, vertex-coloured, and alpha blended into the scene
EntityFX panel,1+2+32
EntityBlend panel,1

top#=0.0

While Not KeyDown(1)

    ; [ and ] fade the top edge of the panel
    If KeyDown(26) And top>0 Then top=top-0.01
    If KeyDown(27) And top<1 Then top=top+0.01

    ; VertexColor's last argument is the alpha VertexAlpha reads back
    VertexColor surf,0,60,180,255,1
    VertexColor surf,1,60,180,255,1
    VertexColor surf,2,60,180,255,top
    VertexColor surf,3,60,180,255,top

    ; A slow rock, so the panel is never a flat rectangle
    RotateEntity panel,0,Sin(MilliSecs()/12.0)*25,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,"[ / ]: fade the top of the panel   Arrows: camera   Esc: exit"
    Text 0,20,"VertexAlpha(surf,0) = "+VertexAlpha(surf,0)+"   (bottom left, always solid)"
    Text 0,40,"VertexAlpha(surf,3) = "+VertexAlpha(surf,3)+"   (top left)"
    Text 0,60,"Alpha reads back as 0 to 1, in 1/255 steps - 0.5 comes back as 0.498039"

    Flip

Wend

End

Index