SolidKit.Forms.Control3D class

From Solid Graphics Wiki

Jump to: navigation, search
SolidKit.Forms.Control3D class
Namespace: SolidKit.Forms
Base type: System.Windows.Forms.Control
Assembly: SolidKit.dll
Platform: .NET

The Control3D class can be used to create a window with 3D capabilities or to create 3D rendering context for off-screen rendering. The Control3D 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 Control3D class is not intended to be used as main application form. For main application form use SolidKit.Forms.MainForm3D class instead.

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

Contents

Features

The Control3D 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 Control3D 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 limits. 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 angles. 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 Control3D class also supports features, such as:

  • customization of shortcut keys for view navigation (using the SolidKit.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 Control3D class manipulates the view's rendering context's projection and modelview matrices based on user's mouse pointer or keyboard interaction with the view depending on currently selected 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 implemented by providing the object's position and rotation information to the Control3D class using the SolidKit3D.ObjectPosInfo class objects. The Control3D then interprets user's mouse pointer and keyboard actions in the view and updates object position and rotation information of provided ObjectPosInfo class instance.

How to use the Control3D class

See Using the Control3D class main article ...

Constructors

See Control3D class constructors for details.

Fields

DefaultSettings Static variable which's settings are copied into Control3D object during it's construction. The DefaultSettings variable controls properties such as initial window projection (ortho or perspective), interaction mode, clipping distances, antialiasing quality.
SolidKit.Forms.Control3D.ViewControlInfo.Default Static variable which's settings are copied into Control3D object during it's construction. It controls properties such as mouse sensitivity and command shortcuts.
SolidKit.Forms.Control3D.ViewMovementInfo.Default Static variable which's settings are copied into Control3D object during it's construction. It provides properties such as shortcuts-controlled pan and rotation speed.

Properties

Handles, projection and clip distance settings

Property name Description
HWND Window's handle.
OpenGLContext Window's device context - HDC and HGLRC.
FrameBufferClearFlags Framebuffer clear options used before rendering each displayed frame.
AntialiasingQuality Antialiasing quality used. The property is used by Control3D.PrepareNextAntialiasedRenderingPass and Control3D.ResetAntialiasingPassInfo antialiasing support methods.
DisplayOptions Display options used for rendering each frame. The options controls for example rendering of coordinate system axes or a floor plane.
PerspectiveProjection Gets or sets control's projection mode.
OrthoProjection Gets or sets control's projection mode.
NearClipDistance Gets/sets near clip distance value used by the control.
FarClipDistance Gets/sets far clip distance value used by the control.
NearClipDistanceRatio Gets/sets near clip distance ration value used by the control.
PixelFormat Pixel format used by the control.

View navigation

Property name Description
InteractionMode Gets/sets control's interaction mode. The interaction mode determines how mouse actions in the object's window are interpreted (scene/object pan, rotation or zoom).
PreviousInteractionMode Gets previous interaction mode.
ManipulationMode Gets/sets control's manipulation mode. The manipulation mode determines whether the mouse actions can affect scene view only, scene objects, or both.
FloorNavigation Enables/disables control's floor navigation mode.
TargetPosition Gets/sets view's camera target position.
EyePosition Gets/sets view's camera eye position.
UpDirection Gets/sets view's camera up direction.
LookDirection Gets current camera direction.
LookRotation Get current control's view rotation angles vector.
LookDistance Get/sets distance between eye position and target position.
GetLookXDirection Returns current look X direction.
Scale Property get returns scale of the scene objects displayed at the target position. Property set moves eye position so the scene objects in target position are displayed in specified scale.
VerticalViewAngle Gets/sets view's camera vertical view angle.
HorizontalViewAngle Gets view's camera horizontal view angle.
HasSceneBoundingBoxInfo Returns true if scene bounding box information was provided to the Control3D object.
HasSelectedObjectsBoundingBoxInfo Returns true if selected objects bounding box information was provided to the Control3D object.
SceneBoundingBoxInfo Gets or sets information to the Control3D object about scene's bounding box.
SelectedObjectsBoundingBoxInfo Gets or sets into the Control3D object's information about selected objects bounding box.
DisplayBoundingBoxInfo Get or sets 'display bounding box' information to the Control3D 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.

Callbacks and Events

Property name Description
QueryObjectPosInfoCallback Sets or clears callback function to be called to query scene object position from associated window's screen coordinates. )
QueryObjectsPosInfoByVolumeCallback Sets or clears callback function to be used to query scene objects lying in selected volume.
SelectionChangeCallback Sets or clears callback function to be used when object selection is changed.
ObjectPosChangeCallback Sets or clears callback function to be called when scene object position is changed as result of interaction with Control3D's window.
ObjectPosChangeBeginCallback Sets or clears callback function to be called when scene object position is about to be changed as result of interaction with Control3D's window.
ObjectPosChangeEndCallback Sets or clears callback function to be called when changing scene object's position as result of interaction with the Control3D window is finished.
CameraPosChangeCallback Sets or clears callback function to be called when view's camera position is changed.
InteractionModeChanged Sets or clears event function to be called when view's interaction mode is changed.
AntialiasingQualityChanged Sets or clears event function to be called when view's antialiasing quality setting is changed.
FloorNavigationModeChanged Sets or clears event function to be called when view's floor navigation mode is changed.
DisplayOptionsChanged Sets or clears event function to be called when view's display options are changed.
VerticalViewAngleChanged Sets or clears event function to be called when view's vertical view angle is changed.

Other properties

Property name Description
ScreenShot Returns screenshot of current frame as an System.Drawing.Bitmap object.
CommandTrigger Gets or sets CommandTrigger for the Control3D object.

Settings control

Method name Description
ViewControlInfo_ Gets or sets object's Control3D.ViewControlInfo reference.
ViewMovementInfo_ Retrieves object's Control3D.ViewMovementInfo reference .


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 Control3D object. The off-screen rendering allows to render images in memory without need to immediately display rendered content onto the computer screen.
Close Closes window's rendering context resources.

Overridable command handlers

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

Rendering methods

Method name Description
RenderBegin Prepares the Control3D object for rendering a frame.
RenderEnd Ends rendering of a frame.
DrawScene Overridable method for rendering a frame content. Control3D 's implementation of this method does nothing. Override this method to render your scene.
DisplayCoordinateSystemOrigin 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.
DisplayCoordinateSystemAxes Overridable method which displays view's coordinate system axes.
GetClipDistances Returns clipping distances currently used in the view projection.

Antialiasing support (using accumulation buffer) methods

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

The Antialiasing methods below use value of AntialiasingQuality property.

Method name Description
ResetAntialiasingPassInfo Resets antialiasing pass information and sets the Control3D object for running first antialiasing pass.
PrepareNextAntialiasedRenderingPass Prepares the Control3D object for next antialiasing pass.

View interaction control methods

Method name Description
OnStartInteraction Overridable callback which is called by the Control3D object on start of each interaction (pan, rotate etc).
OnEndInteraction Overridable callback which is called by the Control3D 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.
SelectedObjectsCount 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 Control3D 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 (Control3D objects).
HasExternalSelectedObjectsSetInfoContainer Returns true is the Control3D object uses external selected objects set container, otherwise false.
SetPickingVolumeSize Gets/sets picking volume size. Increasing the picking volume allows to select objects by clicking mouse pointer into the object vicinity.
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 (Control3D objects).
UnregisterFromViewGroup Removes the Control3D object from the specified group.

View navigation API methods

Method name Description
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.
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 Control3D 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.
SetUnits Add information about used coordinate system units (metres, feets, etc) to the Control3D object.
GetUnits Returns information about coordinates system units (metres, feets, etc) used by the Control3D object.

Animation mode support methods

Method name Description
StartAnimation Starts animation mode for the Control3D 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
Print Prints frame into provided printer's device context.
IsPrinting Returns true if printing for the Control3D object is in progress.

Overridable message handlers

Method name Description
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.

OpenGL-specific wrapper methods

Method name Description
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.
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.

Other methods

Method name Description
Redraw Initiates redraw of the windows' content.
TextureFont Returns texture font associated with the control.
DrawText Draw 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.
GrabPoint Gets or sets grab object point.
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/SolidKit.Forms.Control3D_class"
Personal tools