|
camera - source camera handle plane_entity - entity whose local XZ plane defines the reflector; local +Y is its front normal |
|
Returns a managed reflection handle for a mirror or calm water surface. The reflected view can include objects outside the source camera image. A pivot is a convenient plane definition: it needs no visible geometry. Camera and plane must belong to the same world and have finite, nonsingular transforms. Parenting, rotation and non-uniform scale are supported. Creation starts enabled, at half the source viewport width and height, with a clip bias of .02 scene units. Assign builtin:planar-reflection or builtin:water to a supported receiver first, then associate it using EntityPlanarReflection. Loading the material alone does not capture a view. There may be at most two enabled reflection handles per camera. Disable an existing handle before creating another. Coplanar receivers can share one handle. Reflection is one-sided: the source camera must be on the local +Y side of the plane. A vertical mirror facing world -Z uses an X rotation of -90 degrees. The service captures one bounce, with its own scene lighting, shadows and clipping. It excludes its own receivers; other planar receivers use their fallback inside that view. It has no reflection-view post effects, highlights, temporal history or multisampling. Opaque-background refraction limits still apply to reflected water, glass and heat haze. Custom raw shaders need the view-clip capability. Deleting the camera, plane or world invalidates the handle and detaches its receivers. Release the remaining handle with FreePlanarReflection. These associations are transient and are not saved in worlds. Existing CreateMirror keeps its established behaviour; this service is a separate GPU reflection path. For parameters and worked scenes, see the shader parameter reference and the illustrated reflection study. See also: EntityPlanarReflection, PlanarReflectionSettings, PlanarReflectionEnabled, FreePlanarReflection, CreateMirror. |
; CreatePlanarReflection Example
; ------------------------------
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
camera=CreateCamera()
PositionEntity camera,3,2.7,-7
light=CreateLight()
RotateEntity light,35,-25,0
AmbientLight 65,65,65
; An invisible pivot declares the mirror plane (local +Y faces the camera)
plane=CreatePivot()
PositionEntity plane,0,1.8,3
RotateEntity plane,-90,0,0
PointEntity camera,plane
; A finite mirror quad lying on that plane
mirror=CreateMesh()
surface=CreateSurface(mirror)
AddVertex surface,-2,0,-1.5,0,0
AddVertex surface,2,0,-1.5,1,0
AddVertex surface,2,0,1.5,1,1
AddVertex surface,-2,0,1.5,0,1
AddTriangle surface,0,3,1
AddTriangle surface,1,3,2
UpdateNormals mirror
PositionEntity mirror,0,1.8,3
RotateEntity mirror,-90,0,0
; The receiver material must be assigned before the view is useful
material=LoadShader("builtin:planar-reflection")
ShaderColor material,"FallbackColor",35,65,80
EntityShader mirror,material
; Create the managed reflection and associate the mirror with it
reflection=CreatePlanarReflection(camera,plane)
EntityPlanarReflection mirror,reflection
; A marker to watch in the mirror
marker=CreateCone(16)
ScaleEntity marker,0.55,1.2,0.55
PositionEntity marker,-1.4,1,-4
EntityColor marker,240,160,35
arm=CreateCylinder(12,True,marker)
ScaleEntity arm,0.12,0.9,0.12
RotateEntity arm,0,0,90
PositionEntity arm,0.7,0.4,0
EntityColor arm,50,170,190
floor=CreatePlane()
PositionEntity floor,0,-0.3,0
EntityColor floor,40,50,65
active=True
While Not KeyDown(1)
TurnEntity marker,0,1,0
; Space shows the difference between the capture and its fallback
If KeyHit(57)
active=Not active
PlanarReflectionEnabled reflection,active
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: enable/disable Esc: exit"
Text 0,20,"CreatePlanarReflection(camera,plane) enabled: "+active
Flip
Wend
FreePlanarReflection reflection
FreeShader material
End