Sets OpenGL projection matrix, based on MainScene's currently bound Viewpoint, NavigationInfo and used Camera. Viewport's Camera, if not assigned, is automatically created here, see Camera and CreateDefaultCamera. If scene manager's MainScene is not assigned, we use some default sensible perspective projection.
Render one pass, with current camera and parameters. All current camera settings are saved in RenderingCamera, and the camera matrix is already loaded to OpenGL.
If you want to display something 3D during rendering, this is the simplest method to override. (Or you can use OnRender3D event, which is called at the end of this method.) Alternatively, you can create new T3D descendant and add it to the GetItems list.
Parameters
Params
Parameters specify what lights should be used (Params.BaseLights, Params.InShadow), and which parts of the 3D scene should be rendered (Params.Transparent, Params.ShadowVolumesReceivers — only matching 3D objects should be rendered by this method).
procedure RenderShadowVolume; virtual;
Render shadow quads for all the things rendered by Render3D. You can use here ShadowVolumeRenderer instance, which is guaranteed to be initialized with TGLShadowVolumeRenderer.InitFrustumAndLight, so you can do shadow volumes culling.
procedure RenderFromViewEverything; virtual;
Render everything from current (in RenderingCamera) camera view. Current RenderingCamera.Target says to where we generate the image. Takes method must take care of making many rendering passes for shadow volumes, but doesn't take care of updating generated textures.
Prepare lights shining on everything. BaseLights contents should be initialized here.
The implementation in this class adds headlight determined by the Headlight method. By default, this looks at the MainScene, and follows NavigationInfo.headlight and KambiNavigationInfo.headlightNode properties.
function Headlight(out CustomHeadlight: TAbstractLightNode): boolean; virtual;
Headlight used to light the scene. Returns if headlight is present, and if it has some custom light node. When it returns True, and CustomHeadlight is set to Nil, we simply use default directional light for a headlight.
Default implementation of this method in TCastleAbstractViewport looks at the MainScene headlight. We return if MainScene is assigned and TCastleSceneCore.HeadlightOn is True. (HeadlightOn in turn looks at information in VRML/X3D file (NavigationInfo.headlight) and you can also always set HeadlightOn explicitly by code.) The custom light node is obtained from TCastleSceneCore.CustomHeadlight.
You can override this method to determine the headlight in any other way.
Render the 3D part of scene. Called by RenderFromViewEverything at the end, when everything (clearing, background, headlight, loading camera matrix) is done and all that remains is to pass to OpenGL actual 3D world.
This will change Params.Transparent, Params.InShadow and Params.ShadowVolumesReceivers as needed. Their previous values do not matter.
Information about the 3D world. For scene maager, these methods simply return it's own properties. For TCastleViewport, these methods refer to scene manager.
function GetMainScene: TCastleScene; virtual; abstract;
function PointingDeviceMove(const RayOrigin, RayDirection: TVector3Single): boolean; virtual; abstract;
Pass pointing device (mouse) move event to 3D world.
function PointingDeviceActivate(const Active: boolean): boolean; virtual; abstract;
Pass pointing device (mouse) activation/deactivation event to 3D world.
function CameraMoveAllowed(ACamera: TWalkCamera; const ProposedNewPos: TVector3Single; out NewPos: TVector3Single; const BecauseOfGravity: boolean): boolean; virtual; abstract;
Handle camera events.
Scene manager implements collisions by looking at 3D scene, custom viewports implements collisions by calling their scene manager.
function CameraHeight(ACamera: TWalkCamera; const Position: TVector3Single; out AboveHeight: Single; out AboveGround: P3DTriangle): boolean; virtual; abstract;
function CameraRayCollision(const RayOrigin, RayDirection: TVector3Single): TRayCollision; virtual; abstract;
function CreateDefaultCamera(AOwner: TComponent): TCamera; virtual; abstract; overload;
Create default TCamera suitable for navigating in this scene. This is automatically used to initialize Camera property when Camera is Nil at ApplyProjection call.
The implementation in base TCastleSceneManager uses MainScene.CreateCamera (so it will follow your VRML/X3D scene Viewpoint, NavigationInfo and such). If MainScene is not assigned, we will just create a simple TUniversalCamera in (initially) Examine mode.
The implementation in TCastleViewport simply calls SceneManager.CreateDefaultCamera. So by default all the viewport's cameras are created the same way, by refering to the scene manager. If you want you can override it to specialize CreateDefaultCamera for specific viewport classes.
Overloaded version without any parameters just uses Self as owner of the camera.
Current Camera is created by CreateDefaultCamera if not assigned yet at this point. (And the animation isn't done, since such camera already stands at the default position.) This makes this method consistent: after calling it, you always know that Camera is assigned and going to the default position.
function ScreenEffectsCount: Integer; virtual;
function ScreenEffectsNeedDepth: boolean; virtual;
function ScreenSpaceAmbientOcclusionAvailable: boolean;
Does the graphic card support our ScreenSpaceAmbientOcclusion shader. This does not depend on the current state of ScreenSpaceAmbientOcclusion property. You can use it e.g. to disable the menu item to switch SSAO in 3D viewer.
procedure GLContextOpen; override;
procedure GLContextClose; override;
function HeadlightInstance(out Instance: TLightInstance): boolean;
Instance for headlight that should be used for this scene. Uses Headlight method, applies appropriate camera position/direction. Returns True only if Headlight method returned True and a suitable camera was present.
Instance should be considered undefined ("out" parameter) when we return False.
Base lights used for rendering. Uses InitializeLights, and returns instance owned and managed by this scene manager. You can only use this outside PrepareResources or Render, as they may change this instance.
When PerspectiveView is True, then PerspectiveViewAngles specify angles of view (horizontal and vertical), in degrees. When PerspectiveView is False, then OrthoViewDimensions specify dimensions of ortho window (in the order: -X, -Y, +X, +Y, just like X3D OrthoViewpoint.fieldOfView).
Note that ProjectionFar may be ZFarInfinity, which means that no far clipping plane is used. For example, shadow volumes require this.
If you really need to know "what would be projection far, if it could not be infinite" look at ProjectionFarFinite. ProjectionFarFinite is calculated just like ProjectionFar (looking at scene size, NavigationInfo.visibilityLimit and such), except it's never changed to be ZFarInfinity.
Screen effects are shaders that post-process the rendered screen. If any screen effects are active, we will automatically render screen to a temporary texture, processing it with each shader.
Background color, displayed behind the 3D world. Unless the MainScene has a Background node defined, in which case the Background (colored and/or textured) of the 3D scene is used.
Viewport dimensions where the 3D world will be drawn. When FullSize is True (the default), the viewport always fills the whole container (like TCastleWindow or TCastleControl), and the values of Left, Bottom, Width, Height are ignored here.
Cannot be Nil when rendering. If you don't assign anything here, we'll create a default camera object at the nearest ApplyProjection call (this is the first moment when we really must have some camera). This default camera will be created by CreateDefaultCamera.
This camera should not be inside some other container (like on TCastleWindowCustom.Controls or TCastleControlCustom.Controls list). Scene manager / viewport will handle passing events to the camera on it's own, we will also pass our own Container to Camera.Container. This is desired, this way events are correctly passed and interpreted before passing them to 3D objects. And this way we avoid the question whether camera should be before or after the scene manager / viewport on the Controls list (as there's really no perfect ordering for them).
Scene manager / viewport will "hijack" some Camera events: TCamera.OnVisibleChange, TWalkCamera.OnMoveAllowed, TWalkCamera.OnHeight, TCamera.OnCursorChange. We will handle them in a proper way.
For TCastleViewport only: The TCastleViewport's camera is slightly less important than TCastleSceneManager.Camera, because TCastleSceneManager.Camera may be treated as a "central" camera. Viewport's camera may not (because you may have many viewports and they all deserve fair treatment). So e.g. headlight is done only from TCastleSceneManager.Camera (for mirror textures, there must be one headlight for your 3D world). Also VRML/X3D ProximitySensors receive events only from TCastleSceneManager.Camera.
TODO: In the future it should be possible (even encouraged) to assign one of your custom viewport cameras also to TCastleSceneManager.Camera. It should also be possible to share one camera instance among a couple of viewports. For now, it doesn't work (last viewport/scene manager will hijack some camera events making it not working in other ones).
For scene manager: you can pause everything inside your 3D world, for viewport: you can make the camera of this viewpoint paused (not responsive).
For scene manager:
"Paused" means that no events (key, mouse, Update) are passed to any TCastleSceneManager.Items or the Camera. This is suitable if you really want to totally, unconditionally, make your 3D world view temporary still (for example, useful when entering some modal dialog box and you want 3D scene to behave as a still background).
You can of course still directly change some scene property, and then 3D world will change. But no change will be initialized automatically by scene manager events.
See also: For less drastic pausing methods, there are other methods of pausing / disabling some events processing for the 3D world:
You can set TCastleScene.TimePlaying or TCastlePrecalculatedAnimation.TimePlaying to False. This is roughly equivalent to not running their Update methods. This means that time will "stand still" for them, so their animations will not play. Although they may still react and change in response to mouse clicks / key presses, if TCastleScene.ProcessEvents.
You can set TCastleScene.ProcessEvents to False. This means that scene will not receive and process any key / mouse and other events (through VRML/X3D sensors). Some animations (not depending on VRML/X3D events processing) may still run, for example MovieTexture will still animate, if only TCastleScene.TimePlaying.
For cameras, you can set TCamera.Input := [] to ignore key / mouse clicks.
Should we render with shadow volumes. You can change this at any time, to switch rendering shadows on/off.
This works only if OpenGL context actually can render shadow volumes, checked by GLFeatures.ShadowVolumesPossible, which means that you have to initialize OpenGL context with stencil buffer.
The shadow volumes algorithm is used only if shadow caster is 2-manifold, that is has a correctly closed volume. Also you need a light source marked as the main shadow volumes light (shadowVolumes = shadowVolumesMain = TRUE). See [http://castle-engine.sourceforge.net/x3d_extensions.php#section_ext_shadows] for details.
Actually draw the shadow volumes to the color buffer, for debugging. If shadows are rendered (see GLFeatures.ShadowVolumesPossible and ShadowVolumes), you can use this to actually see shadow volumes, for debug / demo purposes. Shadow volumes will be rendered on top of the scene, as yellow blended polygons.
If yes then the scene background will be rendered wireframe, over the background filled with BackgroundColor.
There's a catch here: this works only if the background is actually internally rendered as a geometry. If the background is rendered by clearing the screen (this is an optimized case of sky color being just one simple color, and no textures), then it will just cover the screen as normal, like without wireframe. This is uncertain situation anyway (what should the wireframe look like in this case anyway?), so I don't consider it a bug.
Useful especially for debugging when you want to see how your background geometry looks like.
If yes then we will not draw any background, letting the window contents underneath be visible (in places where we do not draw our own 3D geometry, or where our own geometry is transparent, e.g. by Material.transparency). For this to make sense, make sure that you always place some other 2D control under this viewport, that actually draws something predictable underneath.
When True then headlight is always rendered from custom viewport's (TCastleViewport) camera, not from central camera (the one in scene manager). This is meaningless in TCastleSceneManager.
By default this is False, which means that when rendering custom viewport (TCastleViewport) we render headlight from TCastleViewport.SceneManager.Camera (not from current viewport's TCastleViewport.Camera). On one hand, this is sensible: there is exactly one headlight in your 3D world, and it shines from a central camera in SceneManager.Camera. When SceneManager.Camera is Nil (which may happen if you set SceneManager.DefaultViewport := false and you didn't assign SceneManager.Camera explicitly) headlight is never done. This means that when observing 3D world from other cameras, you will see a light shining from SceneManager.Camera. This is also the only way to make headlight lighting correctly reflected in mirror textures (like GeneratedCubeMapTexture) — since we render to one mirror texture, we need a knowledge of "cental" camera for this.
When this is True, then each viewport actually renders headlight from it's current camera. This means that actually each viewport has it's own, independent headlight (althoug they all follow VRML/X3D NavigationInfo.headlight and KambiNavigationInfo settings). This may allow you to light your view better (if you only use headlight to "just make the view brighter"), but it's not entirely correct (in particular, mirror reflections of the headlight are undefined then).
Let MainScene.GlobalLights shine on every 3D object, not only MainScene. This is an easy way to lit your whole world with lights defined inside MainScene file. Be sure to set lights global=TRUE.
Note that for now this assumes that MainScene coordinates equal world coordinates. This means that you should not transform the MainScene, it should be placed inside TCastleSceneManager.Items without wrapping in any T3DTransform.
Help user to activate pointing device sensors and pick items. Every time you press or release Input_Interact (by default just left mouse button), we look if current mouse position hits 3D object that actually does something on activation. 3D objects may do various stuff inside T3D.PointingDeviceActivate, generally this causes various picking/interaction with the 3D object (like pulling a level, opening a door), possibly dragging, possibly with the help of VRML/X3D pointing device and drag sensors.
When this is True, we try harder to hit some 3D object that handles PointingDeviceActivate. If there's nothing interesting under mouse, we will retry a couple of other positions arount the current mouse.
This should be usually used when you use TWalkCamera.MouseLook, or other navigation when mouse cursor is hidden. It allows user to only approximately look at interesting item and hit interaction button or key. Otherwise, activating a small 3D object is difficult, as you don't see the mouse cursor.
property DefaultVisibilityLimit: Single
read FDefaultVisibilityLimit write FDefaultVisibilityLimit default 0.0;
Visibility limit of your 3D world. This is the distance the far projection clipping plane.
Our ApplyProjection calculates the final visibility limit as follows:
First of all, if (GLFeatures.ShadowVolumesPossible and ShadowVolumes), then it's infinity.
Then we look NavigationInfo.visibilityLimit value inside MainScene. This allows your 3D data creators to set this inside VRML/X3D data.
Only if MainScene is not set, or doesn't contain NavigationInfo node, or NavigationInfo.visibilityLimit is left at (default) zero, we look further.
We use this property, DefaultVisibilityLimit, if it's not zero.
Finally, as a last resort we calculate something suitable looking at the 3D bounding box of items inside our 3D world.