Blitz3D+ Command Reference

CreateSurface ( mesh[,brush] )

Parameters

mesh - mesh handle

brush (optional) - brush whose appearance the new surface starts with; 0 for a plain default surface (default)

Description

Creates an empty surface attached to a mesh and returns the surface's handle.

A surface is a batch of vertices and triangles that share one appearance. A mesh needs at least one surface before it can show anything, and every AddVertex and AddTriangle call targets a specific surface.

Splitting a mesh into several surfaces lets each section have its own colour, texture and effects - paint them individually with PaintSurface, or find them again later with GetSurface and FindSurface. A car model might use one surface for the body and another for the glass, for example.

Don't go overboard, though: each surface is a separate batch of work for the renderer, so hundreds of tiny surfaces are much slower than a few big ones. Group triangles that share a material into the same surface.

The optional brush parameter paints the new surface with the brush's properties straight away, exactly like calling PaintSurface afterwards.

See also: CreateMesh, AddVertex, AddTriangle, PaintSurface, GetSurface, CountSurfaces.

Example

; CreateSurface Example
; ---------------------

; A mesh is only a container: its triangles actually live in surfaces.
; Each surface has ONE material (brush), so a two-colour object needs
; two surfaces. Here we build a warning sign from two diamonds.

Graphics3D 640,480
SetBuffer BackBuffer()

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

sign=CreateMesh()

; Brushes give each surface its own colour
red_brush=CreateBrush()
BrushColor red_brush,255,60,60
yellow_brush=CreateBrush()
BrushColor yellow_brush,255,220,0

; Surface 1: outer diamond, created with the red brush
outer=CreateSurface(sign,red_brush)
v0=AddVertex(outer,0,1.8,0)
v1=AddVertex(outer,1.8,0,0)
v2=AddVertex(outer,0,-1.8,0)
v3=AddVertex(outer,-1.8,0,0)
AddTriangle outer,v0,v1,v2
AddTriangle outer,v0,v2,v3

; Surface 2: inner diamond, created with the yellow brush,
; nudged slightly towards the camera so it draws on top
inner=CreateSurface(sign,yellow_brush)
v0=AddVertex(inner,0,1.2,-0.01)
v1=AddVertex(inner,1.2,0,-0.01)
v2=AddVertex(inner,0,-1.2,-0.01)
v3=AddVertex(inner,-1.2,0,-0.01)
AddTriangle inner,v0,v1,v2
AddTriangle inner,v0,v2,v3

; Fullbright (1) + two-sided (16) so the sign shows while spinning
EntityFX sign,17

While Not KeyDown(1)

    TurnEntity sign,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,"Arrow keys: move camera   Esc: exit"
    Text 0,20,"CreateSurface: this mesh has "+CountSurfaces(sign)+" surfaces - one per colour"

    Flip

Wend

End

Index