Window3D class

From Solid Graphics Wiki

(Redirected from Window3d)
Jump to: navigation, search
Window3D class
Namespace: SKL3D
Base type: Window class
Include: Skl3DWindow.h
Lib (Release): SKL.lib
Lib (Debug): SKL_D.lib

The Window3D class can be used to create a window with 3D capabilities or to create 3D rendering context for a window created for example by MFC framework. The Window3D class then provides datamodel-independent 3D view navigation capabilities (such as view pan, rotate, zoom or walk functions), 3D objects manipulation capabilities (moving the objects or rotating them) to the window by handling mouse and keyboard actions in the window and translating them into corresponding window view projection changes.

The Window3D class is not intended to be used directly in MFC applications. For MFC applications use C3DView or C3DWindow classes instead.

See SolidKit Library sample projects for more information about how to use the Window3D class.

Contents

Features

The Window3D class provides provide these data-model-independent scene view navigation modes:

  • rotate - freely rotate around xyz axes, or around any specified vector (axis)
  • pan - freely move in xyz space, or in any specified plane
  • zoom - zoom in, out, to specified window rectangle, to whole scene, to selected object
  • fly view - change view direction using mouse or keyboard
  • free look view (this is the same mode as used in first person shooter games) - walk move with "keeping the head-up direction)
  • view angle control

The Window3D class allows this datamodel-independent manipulations of selected 3D scene objects:

  • moving object freely in xyz space, or along a plane, or along specified vector. It is possible to set moving constraints, such as prohibiting to move an object beyond a specified limit. Moving objects in steps (snap to grid) is also supported.
  • rotate objects freely along xyz axis, or around any specified vector. It is possible to set ratation constraints such as to prohibit to rotate object more or less than certain angle. Rotating objects in discrete steps (for example in 5 degree steps) is also supported.
  • multiple objects can be selected, the moving or rotating is applied to all selected objects

The Window3D class also supports features, such as:

  • view navigation shortcut keys customization (using the CommandTrigger class)
  • printing of the 3D renders
  • simple texture-based text printing
  • antialiasing (accumulation buffer based)
  • 3D objects selections and manipulation

How it works

The Window3D class achieves the view navigation by setting-up the view rendering context's projection and modelview matrices based on user's mouse pointer or keyboard interaction with the view and current view's interaction mode. The view can be also navigated programatically by using navigation functions such as LookAt, Pan or Rotate.

The 3D scene objects manipulation is achieved by providing the object's position and rotation information to the Window3D class by using the ObjectPosInfo struct. The Window3D object then interprets user's mouse pointer and keyboard actions in the view into updating the position and rotation information in the provided ObjectPosInfo struct instance.

How to use the Window3D class

See Using the Window3D class main article ...

Constructors

See Window3D class constructors for details.

Fields

defaultSettings Static variable which's settings are copied into Window3D object during it's construction. The defaultSettings variable controls things such as initial window projection (ortho or perspective), interaction mode, clipping distances, antialiasing quality.
defaultPixelFormat Static variable which's settings are used when OpenGL rendering context for the Window3D object is created.
defaultControlInfo Static variable which's settings are copied into Window3D object during it's construction. The defaultControlInfo variable controls things such as mouse sensitivity and command shortcuts.
defaultMovementInfo Static variable which's settings are copied into Window3D object during it's construction. The defaultMovementInfo controls properties such as shortcuts-controlled pan and rotation speed.

Methods

Rendering context creation / close / information methods

Method name Description
CreateRenderingContext Creates OpenGL rendering context for given window.
CreateOffScreenWindow Creates off screen based rendering context for the Window3D object. The off-screen rendering allows to render images in memory without need to immediately display rendered content onto the computer screen.
Close Closes the Window3D object's associated window.
GetWindowHandle Return's window's handle.
GetWindowDC Returns window's device context handle.
GetWindowRC Returns window's OpenGL rendering context handle.
Width Returns height of the window in pixels.
Height Returns width of the window in pixels.

Overridable command handlers

Method name Description
OnWindow3DCommand Overridable method used to handle commands (suh as move camera left, right, up, down; zoom in, zoom out; etc) send to the Window3D object.

Rendering methods

Method name Description
RenderBegin Prepares the Window3D object for rendering a frame.
RenderEnd Ends rendering of a frame.
DrawScene Overridable method for rendering a frame content. Window3D 's implementation of this method does nothing. Override this method to render your scene.
DisplayOrigin Overridable method which renders coordinate system origin into a frame content.
DisplayTargetPosition Overridable method which renders target position's location into rendered frame
DisplayFloorPlane Overridable method which displays currently active floor plane.
DisplayWorldAxes Overridable method which displays coordinate system axes into currently rendered frame.
DisplaySelectedObjectsEditOptions Overridable method which displays editing options for currently selected set of objects into currently rendered frame.
DisplayGrabObjectEditOptions Overridable method which displays grab object's edit options into currently rendered frame.
DisplaySelectedObjectsPointMark Overridable method which displays point marks for set of selected objects into currently rendered frame.
DisplaySelectedObjectsBoxes Overridable method which displays bounding boxes of selected objects into currently rendered frame.
DisplayZoomSelectionArea Overridable method which displays zoom selection area during zoom area window selection by mouse in the Zoom Window interaction mode.
Set3DDisplayOptions Use this method to tell the Window3D object which auxiliary objects (such as coordinate system axes, target point, etc) should be displayed into rendered frames.
Get3DDisplayOptions This method returns information about currently selected Window3D object's display options.

Antialiasing support (using accumulation buffer) methods

Note: the Window3D class supports antialiasing with using accumulation buffer only.

Method name Description
SetAntialiasingQuality Sets antialiasing quality for Window3D::PrepareNextAntialiasedRenderingPass and Window3D::ResetAntialiasingPassInfo antialiasing support methods.
GetAntialiasingQuality Returns current antialiasing quality settings.
ResetAntialiasingPassInfo Resets antialiasing pass information and sets the Window3D object for running first antialiasing pass.
PrepareNextAntialiasedRenderingPass Prepares the Window3D object for next antialiasing pass.

View interaction control methods

Method name Description
SetInteractionMode Sets window's interaction mode. The interaction mode determines how mouse actions in the object's window are interpreted (scene/object pan, rotation or zoom).
GetInteractionMode Retrieves current interaction mode settings.
SetManipulationMode Set's window manipulation mode. The manipulation mode determines whether the mouse actions can affect scene view only, scene objects, or both.
GetManipulationMode Returns current manipulation mode settings.
SetFloorNavigationMode Sets object into floor navigation mode, or cancels the floor navigation mode.
GetFloorNavigationModeInfo Returns current floor navigation mode settings.
IsInFloorNavigationMode Returns true if floor navigation mode is active, otherwise returns false.
GetFloorGridUnitSize Returns unit size for floor currently displayed in the associated window.
GetFloorDisplayPlaneBoundingBox Calculates floor display plane bounding box. This method is overridable to allow customization of displayed floor plane.
OnStartInteraction Overridable callback which is called by the Window3D object on start of each interaction (pan, rotate etc).
OnEndInteraction Overridable callback which is called by the Window3D object on end of each interaction.

Objects selection support

Method name Description
SelectObject Adds a scene object into the selection set. The function can be also used to remove all scene objects from the selection set by specifying selected object information as NULL.
UnselectObject Removes single scene object from the selection set.
UnselectAllObjects Removes all objects from the selected objects set.
FindSelectedObject Determines whether an scene object is part of selected objects set.
GetSelectedObjectsCount Returns number of scene objects in the selected objects set.
GetSelectedObject Returns selected object's information from object index.
SetSelectedObjectsEditOption Sets or clears specified edit option for selected scene objects.
GetSelectedObjectsEditOption Retrieves information about an edit option for selected scene objects.
IsInAddOrRemoveSelectionMode Returns true if the Window3D object is in add/remove-scene-object-to/from-selection-set mode.
SetSelectedObjectsSetInfoContainer Allows to specify external container for the selected objects set. This allows to share the selected objects set between multiple scene views (Window3D objects).
IsExternalSelectedObjectsSetInfoContainer Returns true is the Window3D object uses external selected objects set container, otherwise false.
SetPickingVolumeSize Sets picking volume size. Increasing the picking volume allows to select objects by clicking mouse pointer into the object vicinity.
GetPickingVolumeSize Returns current pick volume size settings.
SetSnapToGridInfo Allows to set or clear snap grid for manipulating scene objects.
SetRotationStepInfo Allows to rotate scene objects in discreete steps.
RegisterIntoViewGroup Allows to share selected objects set and interaction mode between multpile scene views (Window3D objects).
UnregisterFromViewGroup Removes the Window3D object from the specified group.

View navigation API methods

Method name Description
SetOrthoProjection Sets up ortho projection for the view displayed by the associated window.
IsOrthoProjection Returns true if the view is using ortho projection, otherwise false.
SetPerspectiveProjection Sets up perspective projection for the view displayed by the associated window.
IsPerspectiveProjection Returns true if the view is using perspective projection, otherwise false.
SetVerticalViewAngle Sets associated window view's vertical view angle.
GetVerticalViewAngle Returns associated window view's vertical view angle.
GetHorizontalViewAngle Returns associated window view's horizontal view angle.
SetLookRotation Sets associated window view's look rotations.
GetLookRotation Returns associated window view's current look rotation values.
GetLookDirection Returns current look direction.
GetLookXDirection Returns current look X direction.
SetUpDirection Sets view's up direction.
GetUpDirection Returns view's current up direction.
SetLookDistance Moves eye position to specified distance from the target position.
GetLookDistance Returns current distance between eye position and target position.
SetTargetPosition Sets view's target position.
GetTargetPosition Returns view's target position.
SetEyePosition Sets view's eye position.
GetEyePosition Returns view's eye position.
GetPointerRay Returns line segment specified by current eye position and point specified by view window's pixel (2D) coordinates. The pixel coordinates are translated into world coordinates.
LookAt Moves view's eye position, target position, up direction to specified values.
SetCamera Sets view's camera.
GetCamera Retrieves view's camera information.
ZoomIn Moves eye position closer to the target position by specified factor.
ZoomOut Moves eye position away from target position using specified factor.
FitSceneToView Sets eye position and target position so the whole scene is visible in the associated window's view.
FitSelectedObjectsToView Sets eye position and target position so all selected scene objects are fully visible in the associated window's view.
FitBoundingBoxToView Sets eye position and target position so the specified BoundingBox is fully visible in the associated window's view.
SetSceneBoundingBoxInfo Informs the Window3D object about scene's bounding box.
HasSceneBoundingBoxInfo Returns true if scene bounding box information was provided to the Window3D object.
SetSelectedObjectsBoundingBoxInfo Informs the Window3D object about selected objects bounding box.
HasSelectedObjectsBoundingBoxInfo Returns true if selected objects bounding box information was provided to the Window3D object.
SetDisplayBoundingBoxInfo Sets 'display bounding box' information to the Window3D object. It allows to include bounding box for view's auxiliary objects, such as floor plane or orientation marks, when view's clipping distances are calculated.
HasDisplayBoundingBoxInfo Returns current 'display bounding box' settings.
PanScene Pans the scene view by specified vector.
PanObject Pans the specified object by specified vector.
RotateScene Rotates scene view by specified rotation angles.
RotateObject Rotates specified object by specified rotation angles.
FreeLookRotate Performs free look rotation using specified rotation angles.
FlyRotate Performs fly rotation using specified rotation angles.
SetWindowResizeMode Tells the Window3D object how the associated window view's projection should be updated when window is resized - whether scale of the objects should be kept or view content should be kept.
GetWindowResizeMode Returns current resize mode settings.
SetScale Moves eye position so the scene objects in target position are displayed in specified scale.
GetScale Returns scale of the scene objects displayed at the target position.
SetUnits Add information about used coordinate system units (metres, feets, etc) to the Window3D object.
GetUnits Returns information about coordinates system units (metres, feets, etc) used by the Window3D object.

Clip distances control methods

Method name Description
SetNearClipDistance Specifies the near clipping distance to be used when setting up view's projection.
SetFarClipDistance Specifies the far clipping distance to be used when setting up view's projection.
GetNearClipDistanceSetting Returns the near clipping distance settings.
GetFarClipDistanceSetting Returns the far clipping distance settings.
SetNearClipDistanceRatio Sets ratio for calculating near clipping distance from the look distance.
GetNearClipDistanceRatio Returns current near-clip-distance-calculating-ratio value.
GetClipDistances Returns clipping distances currently used in the view projection.

Animation mode support methods

Method name Description
StartAnimation Starts animation mode for the Window3D object.
StopAnimation Ends the window's animation mode.
IsAnimationStarted Returns true if animaton mode is started, otherwise false.
GetFrameRenderingTime Returns number of seconds since drawing the last frame.

Printing support methods

Method name Description
OnWindow3DBeginPrinting Prepares the Window3D object for printing a frame.
OnWindow3DPrint Prints frame into provided printer's device context.
OnWindow3DEndPrinting Finishes the printing frame process.
IsInPrintingMode Returns true if printing process started and is not finished yet for the Window3D object, otherwise returns false.
SetMaxPrintResolution Set's maximum resolution for an image internally used by the Window3D object for printing the frame.
GetMaxPrintResolution Returns current maximum resolution settings for an image internally used by the Window3D object to print frame.

Overridable message handlers

Method name Description
ProcessWindowMessage Function which receives all associated window messages. Note that this function receives the messages only if the window was created by Window::Create function.
OnWindow3DCreate Handler for processing WM_CREATE message.
OnWindow3DDestroy Handler for processing WM_DESTROY message.
OnWindow3DSetFocus Handler for processing WM_SETFOCUS message.
OnWindow3DKillFocus Handler for processing WM_KILLFOCUS message.
OnWindow3DKeyDown Handler for processing WM_KEYDOWN message.
OnWindow3DKeyUp Handler for processing WM_KEYUP message.
OnWindow3DLButtonDown Handler for processing WM_LBUTTONDOWN message.
OnWindow3DLButtonUp Handler for processing WM_LBUTTONUP message.
OnWindow3DRButtonDown Handler for processing WM_RBUTTONDOWN message.
OnWindow3DRButtonUp Handler for processing WM_WM_RBUTTONUP message.
OnWindow3DMButtonDown Handler for processing WM_MBUTTONDOWN message.
OnWindow3DMButtonUp Handler for processing WM_MBUTTONUP message.
OnWindow3DMouseMove Handler for processing WM_MOUSEMOVE message.
OnWindow3DMouseWheel Handler for processing WM_MOUSEWHEEL message.
OnWindow3DSize Handler for processing WM_SIZE message.
PreCreateWindow MFC specific function for handling MFC's CWnd::PreCreateWindow message call.

Callbacks control methods

Method name Description
SetQueryObjectPosInfoProc Sets or clears callback function to be called to query scene object position from associated window's screen coordinates. )
SetQueryObjectsPosInfoByVolumeProc Sets or clears callback function to be used to query scene objects lying in selected volume.
SetOnSelectionChangeCallbackProc Sets or clears callback function to be used when object selection is changed.
SetOnObjectPosChangeCallbackProc Sets or clears callback function to be called when scene object position is changed as result of interaction with Window3D's window.
SetOnObjectPosChangeBeginCallbackProc Sets or clears callback function to be called when scene object position is about to be changed as result of interaction with Window3D's window.
SetOnObjectPosChangeEndCallbackProc Sets or clears callback function to be called when changing scene object's position as result of interaction with the Window3D window is finished.
SetOnCameraPosChangeCallbackProc Sets or clears callback function to be called when view's camera position is changed.
SetOnInteractionModeChangeCallbackProc Sets or clears callback function to be called when view's interaction mode is changed.

OpenGL-specific wrapper methods

Method name Description
wglMakeCurrent The function makes associated window's OpenGL rendering context the calling thread's current rendering context.
SetFrameBufferClearFlagsValue Specifies what part of OpenGL frame buffer should be cleared during RenderBegin method call.
GetFrameBufferClearFlagsValue Returns current Window3D object's instructions for clearing the frame buffer during each RenderBegin method call.
GetSelectionHitsCount Returns selection buffer hits count after the QueryObjectId method call.
GetSelectionBuffer Returns the selection buffer pointer for reading the selection buffer after the QueryObjectId method call.

Coordinates transformations methods

Method name Description
WorldToEye Transforms world (scene) coordinates to coortinates relative to view's eye position.
EyeToWorld Transforms eye position relative coordinates to world (scene) coordinates.
ScreenToWorld Transforms screen coordinates to world (scene) coordinates.
ScreenToBasePlanePoint Transforms screen coordinates at target position depth to world (scene) coordinates.

Settings control

Method name Description
GetViewControlInfo Retrieves object's ViewControlInfo reference so it can be read or modified.
GetViewMovementInfo Retrieves object's ViewMovementInfo reference so it can be read or modified.
GetCommandTrigger Retrieves current object's CommandTrigger object pointer.
SetCommandTrigger Sets CommandTrigger for the Window3D object.

Other methods

Method name Description
Redraw Initiates redraw of the windows' content.
DefaultFont Returns objects' default font.
PrintText Prints text into the window.
SaveScreenShot Saves screenshot of current frame to a file.
GetPixelDimensions Retrieves pixel's dimensions at target position's plane.
GetViewAreaSize Retrieves size of the views rectangle at for specified distance from the eye position.
GetBasePlaneViewAreaSize Retrieves size of the view rectangle at target position plane.
GetBasePlaneViewAreaXSize Retrieves X size of the view rectangle at target position plane.
GetBasePlaneViewAreaYSize Retrieves Y size of the view rectangle at target position plane.
GetGrabPoint Retrieves ObjectPosInfoArray pointer for the current grab object.
SetGrabPoint Sets window's grab object
QueryObjectId Queries ID of an object at specified window's X, Y pixel coordinates.
GetViewVolumePoints Retrieves eight points which define current window's view volume.
UpdateViewProjection Refreshes window's projection and modelview matrices using current camera parameters.

Operators

The class has no operators.

See Also

   

SolidKit Library Documentation

Retrieved from "http://wiki.solidgraphics.com/wiki/Window3D_class"
Personal tools