Public Member Functions
ToolContext Class Reference

Detailed Description

ToolContext is used for accessing/handling tool data. Instances of this object can pass information to the C++ API callbacks that implement the custom tool plug-in item.

A custom tool must be registered at startup time using PluginRegistrar::RegisterTool. A scripting command with the same name as the custom tool is also registered. Calling this command will invoke the tool. A custom shortcut key may also be assigned to the tool using the keyboard mapping dialog.

Tool Callbacks
All tool callbacks are optional so tools only need to implement the callbacks they are interested in receiving.
Callback names must be formatted as 
 {plugin_item_name}_{callback_name}
where plugin_item_name is the string passed to PluginRegistrar::RegisterTool to identify the tool plug-in item and callback_name is the name of the callback.
Each callback receives a reference to the ToolContext which is used to retrieve callback specific information and change the tool state.
Note: Callbacks that require a return value will be documented in the callback description. Return values for all other callbacks are ignored.
Setup
    CStatus MyTool_Setup( ToolContext &in_context )
This callback is called when the tool is created and can be used to setup initial tool state.
Cleanup
    CStatus MyTool_Cleanup( ToolContext &in_context )
This callback is called when the tool is destroyed and can be used to free up memory or release drawing resources like textures.
Activate
    CStatus MyTool_Activate( ToolContext &in_context )
This callback is called when the tool takes control of the view. Tools can be temporarily deactivated when another tool is invoked by holding down a (supra) hotkey. The original tool will be reactivated when the hotkey is released.
Deactivate
    CStatus MyTool_Deactivate( ToolContext &in_context )
This callback is called when another tool takes control of the view. Tools can be temporarily deactivated when another tool is invoked by holding down a (supra) hotkey. The original tool will be reactivated when the hotkey is released.
Draw
    CStatus MyTool_Draw( ToolContext &in_context )
This callback is called when the view is drawn and the tool can perform its own drawing in this callback. The default drawing coordinates are world-space but tools can draw in 2D screen-space by calling ToolContext::BeginViewDraw and ToolContext::EndViewDraw.
The callback will be called once for each visible view that needs to be redrawn. If the tool only wants to draw in a single view or during interaction then ToolContext::IsActiveView and ToolContext::IsInteracting can be used to detect these conditions. A tool can also be asked to draw when the user is interacting with a camera tool in supra mode and ToolContext::IsNavigating will return true when this happens.
MouseDown
    CStatus MyTool_MouseDown( ToolContext &in_context )
This callback is called when a mouse button is pressed on a 3D view.
Mouse position and button/modifier key state can be accessed through the tool context. The tool can then convert the mouse coordinates to 3D using the ToolContext coordinate conversion methods.
The tool must return CStatus::OK if it wants to proceed with the interaction. If any other value is returned then the interaction will be aborted and no subsequent MouseDrag or MouseUp events will be received.
MouseDrag
    CStatus MyTool_MouseDrag( ToolContext &in_context )
This callback is called when the user is dragging with a mouse button is pressed in a 3D view.
MouseUp
    CStatus MyTool_MouseUp( ToolContext &in_context )
This callback is called when the user releases a mouse button to end interaction in a 3D view.
If ToolContext::WasAborted is true then the tool interaction was aborted because the user pressed Esc or the interaction was interrupted.
MouseMove
    CStatus MyTool_MouseMove( ToolContext &in_context )
This callback is called when the user moves the mouse cursor in a 3D view and no mouse buttons are pressed. This could be used to highlight on-screen controls or provide feedback on what is under the cursor.
MouseEnter
    CStatus MyTool_MouseEnter( ToolContext &in_context )
This callback is called when the mouse cursor enters a 3D view.
MouseLeave
    CStatus MyTool_MouseLeave( ToolContext &in_context )
This callback is called when the mouse cursor leaves a 3D view.
ModifierChanged
    CStatus MyTool_ModifierChanged( ToolContext &in_context )
This callback is called when a mouse modifier key changes. ToolContext::IsShiftKeyDown and ToolContext::IsControlKeyDown can be used to determine the current state of the modifier keys.
SelectionChanged
    CStatus MyTool_SelectionChanged( ToolContext &in_context )
This callback is called when the selection changes.
SnapValid
    CStatus MyTool_SnapValid( ToolContext &in_context )
This callback is called during snapping to allow the tool to reject unsuitable snap candidates. For example, when translating an object you would generally not want to snap to the object being moved.
For this callback to be triggered the tool must enable snapping and call one of ToolContext::GetWorldPosition or ToolContext::GetWorldRay. Alternatively, the tool may call ToolContext::Snap directly.
Information about the snap candidate can be accessed using ToolContext::GetSnapType, ToolContext::GetSnapObject and ToolContext::GetSnapComponent. Note: These methods may also be called from the mouse callbacks to get the overall result of the latest snap operation.
Note: This callback can be called numerous times during a single snap operation so it should try to minimize the amount of work it does and test the snap type first before attempting to access the object or components.
If the callback returns CStatus::OK the snap candidate will be allowed. Otherwise, the snap candidate will be ignored for snapping purposes.
KeyDown
    CStatus MyTool_KeyDown( ToolContext &in_context )
This callback is called on key down for shortcuts keys registered by the tool using ToolContext::RegisterShortcutKey.
Key information can be accessed using ToolContext::GetShortcutKey and ToolContext::GetShortcutKeyModifiers. Alternatively, the state of registered shortcut keys can be tested in other callbacks using ToolContext::IsShortcutKeyDown.
KeyUp
    CStatus MyTool_KeyUp( ToolContext &in_context )
This callback is called on key up for shortcuts keys registered by the tool using ToolContext::RegisterShortcutKey.
Key information can be accessed using ToolContext::GetShortcutKey and ToolContext::GetShortcutKeyModifiers. Alternatively, the state of registered shortcut keys can be tested in other callbacks using ToolContext::IsShortcutKeyDown.
MenuInit
    CStatus MyTool_MenuInit( ToolContext &in_context )
This callback is called by ToolContext::ShowContextMenu to set the contents of the menu. The Menu is accessed within the callback using Context::GetSource.
Example:
Simple plugin tool that uses picking to identify the object under the cursor. For a more detailed example see the CustomTools/netview_CustomTools SpotLightCreateTool custom tool example Tools can also be created from the Plugin Manager by flicking the File button and then chosing New > Tool. 
    #ifndef linux
    #define WIN32_LEAN_AND_MEAN
    #include <windows.h> // Needed for OpenGL on windows
    #endif
    #include <GL/gl.h>
    #include <xsi_status.h>
    #include <xsi_argument.h>
    #include <xsi_toolcontext.h>
    #include <xsi_pluginregistrar.h>
    #include <xsi_math.h>
    
    using namespace XSI; 
    using namespace XSI::MATH; 
    
    class MyPickInfoTool {
    private: // Data
        LONG        m_cursorX;
        LONG        m_cursorY;
        CRefArray   m_picked;
    
    public: // Methods
        MyPickInfoTool() {}
    
        ~MyPickInfoTool() {}
    
        CStatus MouseMove( ToolContext& in_ctxt )
        {
            m_picked.Clear();
            in_ctxt.GetMousePosition( m_cursorX, m_cursorY );
    
            CLongArray l_points;
            l_points.Add( m_cursorX );
            l_points.Add( m_cursorY );
    
            // Check for object under the cursor
            in_ctxt.Pick( l_points, siPickSingleObject, siPickRaycast, L"", CRefArray(), m_picked );
            in_ctxt.Redraw( false );
            return CStatus::OK;
        }
    
        CStatus Draw( ToolContext& in_ctxt )
        {
            if ( in_ctxt.IsActiveView() && m_picked.GetCount() > 0 )
            {
                CString l_Str = m_picked.GetAsText();
                if ( l_Str.Length() > 0 )
                {
                    in_ctxt.BeginViewDraw();
    
                    LONG width = 0, height = 0, descent = 0;
                    in_ctxt.GetTextSize( l_Str, width, height, descent );
                    GLint x = (GLint)m_cursorX - width/2, y = (GLint)m_cursorY + 20;
    
                    // Draw text
                    glColor3d( 0, 0, 0 );
                    glRasterPos2i( x, y );
                    in_ctxt.DrawTextString( l_Str );
                }
            }
            return CStatus::OK;
        }
    };
        
    SICALLBACK XSILoadPlugin( PluginRegistrar& in_reg )
    {
        in_reg.PutAuthor(L"Autodesk Ltd");
        in_reg.PutName(L"Simple Tool Plugin");
        in_reg.PutVersion(1, 0);
        in_reg.RegisterTool(L"MyPickInfoTool");
        //RegistrationInsertionPoint - do not remove this line
        return CStatus::OK;
    }

    SICALLBACK MyPickInfoTool_Init( CRef& in_ctxt )
    {
        ToolContext l_ctxt( in_ctxt );
        PickInfoTool *l_pTool = new PickInfoTool;
        if ( !l_pTool ) return CStatus::Fail;
        l_ctxt.PutUserData( CValue((CValue::siPtrType)l_pTool) );
        return CStatus::OK;
    }
    
    SICALLBACK MyPickInfoTool_Term( CRef& in_ctxt )
    {
        ToolContext l_ctxt( in_ctxt );
        PickInfoTool *l_pTool = (PickInfoTool *)(CValue::siPtrType)l_ctxt.GetUserData();
        if ( !l_pTool ) return CStatus::Fail;
        delete l_pTool;
        l_ctxt.PutUserData( CValue((CValue::siPtrType)NULL) ); // Clear user data
        return CStatus::OK;
    }
    
    #define DECLARE_TOOL_CALLBACK(TOOL,CALLBACK) \
    SICALLBACK TOOL##_##CALLBACK( ToolContext& in_ctxt ) { \
        TOOL *l_pTool = (TOOL *)(CValue::siPtrType)in_ctxt.GetUserData(); \
        return ( l_pTool ? l_pTool->CALLBACK( in_ctxt ) : CStatus::Fail ); }
    
    DECLARE_TOOL_CALLBACK( MyPickInfoTool, MouseMove );
    DECLARE_TOOL_CALLBACK( MyPickInfoTool, Draw );
See also:
PluginRegistrar::RegisterTool
Since:
10.0 (2012)

#include <xsi_toolcontext.h>

Inheritance diagram for ToolContext:
Inheritance graph
[legend]

List of all members.

Public Member Functions
  ToolContext ()
  ~ToolContext ()
  ToolContext (const CRef &in_ref)
  ToolContext (const ToolContext &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
ToolContext &  operator= (const ToolContext &in_obj)
ToolContext &  operator= (const CRef &in_ref)
bool  IsShortcutKeyDown (ULONG in_virtualKeycode, ULONG in_modifiers=0) const
ULONG  GetShortcutKey () const
ULONG  GetShortcutKeyModifiers () const
Mouse and Keyboard Methods
CStatus  GetMousePosition (LONG &x, LONG &y) const
bool  IsLeftButtonDown () const
bool  IsMiddleButtonDown () const
bool  IsRightButtonDown () const
bool  IsDoubleClick () const
bool  IsShiftKeyDown () const
bool  IsControlKeyDown () const
CStatus  RegisterShortcutKey (ULONG in_virtualKeycode, const CString &in_description, ULONG in_modifiers=0, bool in_repeats=false)
CStatus  UnRegisterShortcutKey (ULONG in_virtualKeycode, ULONG in_modifiers=0)
View Methods
CStatus  GetViewSize (LONG &width, LONG &height) const
CStatus  GetViewport (LONG &x, LONG &y, LONG &width, LONG &height) const
bool  IsInteracting () const
bool  IsActiveView () const
bool  IsNavigating () const
LONG  GetViewIndex () const
Camera  GetCamera () const
Tool State Methods
CStatus  SetCursor (siToolCursor in_cursorId)
CStatus  SetToolDescription (const CString &in_message)
CStatus  EnableSnapping (bool in_enable)
CStatus  GetViewPlane (MATH::CPlane &out_plane) const
CStatus  GetGridPlane (MATH::CPlane &out_plane) const
CStatus  SetManipulationPlane (const MATH::CPlane &in_plane)
CStatus  ClearManipulationPlane ()
bool  WasAborted () const
CStatus  ExitTool ()
bool  GetFlag (LONG in_flag) const
CStatus  SetFlag (LONG in_flag, bool in_enable)
Coordinate Conversion Methods
CStatus  GetWorldPosition (LONG x, LONG y, MATH::CVector3 &out_world) const
CStatus  GetWorldRay (LONG x, LONG y, MATH::CLine &out_ray) const
CStatus  WorldToView (const MATH::CVector3 &in_world, MATH::CVector3 &out_view) const
CStatus  ViewToWorld (const MATH::CVector3 &in_view, MATH::CVector3 &out_world) const
CStatus  WorldToCamera (const MATH::CVector3 &in_world, MATH::CVector3 &out_camera) const
CStatus  CameraToWorld (const MATH::CVector3 &in_view, MATH::CVector3 &out_world) const
CStatus  GetWorldToViewMatrix (MATH::CMatrix4 &out_worldToView) const
CStatus  GetWorldToCameraMatrix (MATH::CMatrix4 &out_worldToCamera) const
Drawing and Text Methods
CStatus  Redraw (bool in_allViews=true)
CStatus  DrawTextString (const CString &in_str, siAlignment in_hPos=siLeftAlign, siAlignment in_vPos=siBottomAlign)
CStatus  GetTextSize (const CString &in_str, LONG &out_width, LONG &out_height, LONG &out_descent) const
CStatus  EditTextString (CString &io_str, LONG x, LONG y, LONG width, LONG height)
CStatus  BeginViewDraw ()
CStatus  EndViewDraw ()
bool  IsViewDraw () const
CStatus  BeginPickDraw (LONG x, LONG y, LONG width, LONG height)
CStatus  EndPickDraw ()
bool  IsPickDraw () const
Interactive Data Update Methods
CStatus  BeginParameterUpdate (const Parameter &in_param, double in_time=DBL_MAX)
CStatus  UpdateParameter (const Parameter &in_param, const CValue &in_value)
CStatus  EndParameterUpdate (const Parameter &in_param)
CStatus  BeginKinematicStateUpdate (const KinematicState &in_kine, double in_time=DBL_MAX)
CStatus  UpdateKinematicState (const KinematicState &in_kine, const MATH::CTransformation &in_value)
CStatus  EndKinematicStateUpdate (const KinematicState &in_kine)
CStatus  BeginTransformUpdate (const CRefArray &in_objects, double in_time=DBL_MAX)
CStatus  UpdateTransform (const CRefArray &in_objects, const MATH::CTransformation &in_value, siTransformFilter in_srt, siRefMode in_refMode=siLocal, siDeltaMode in_delta=siRelative, siAxesFilter in_axesFilter=siXYZ, bool in_usePivot=false, const MATH::CVector3 &in_pivot=MATH::CVector3(), const MATH::CTransformation &in_reference=MATH::CTransformation())
CStatus  EndTransformUpdate (const CRefArray &in_objects)
Snapping Methods
siSnapType  GetSnapType () const
CRef  GetSnapObject () const
CRef  GetSnapComponent () const
CStatus  Snap (LONG x, LONG y, LONG size, ULONG in_snaptype, const CStringArray &in_families, const CRefArray &in_objects, MATH::CVector3 &out_world) const
Picking Methods
CStatus  Pick (const CLongArray &in_points, siPickMode in_pickMode, siPickType in_pickType, const CString &in_filter, const CRefArray &in_objects, CRefArray &out_picked) const
PickBuffer  GetPickBuffer (LONG x, LONG y, LONG width, LONG height, const CString &in_filter, const CRefArray &in_objects, siViewMode in_viewMode=siShaded) const
Context Menu Methods
CStatus  ShowContextMenu (LONG x, LONG y, siAlignment in_hPos=siLeftAlign, siAlignment in_vPos=siTopAlign)
Utility Methods
Image  LoadImageFromFile (const CString &in_filename, bool in_relativePath=true)

Constructor & Destructor Documentation

ToolContext ( )

Default constructor.

~ToolContext ( )

Default destructor.

ToolContext ( const CRef &  in_ref )

Constructor.

Parameters:
in_ref constant reference object.
ToolContext ( const ToolContext &  in_obj )

Copy constructor.

Parameters:
in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassID class type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from Context.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from Context.

ToolContext& operator= ( const ToolContext &  in_obj )

Creates an object from another object.

Parameters:
in_obj constant class object.
Returns:
The new ToolContext object.
ToolContext& operator= ( const CRef &  in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref constant class object.
Returns:
The new ToolContext object.

Reimplemented from Context.

CStatus GetMousePosition ( LONG &  x,
LONG &  y 
) const

Returns the mouse coordinates relative to the current view

Parameters:
x mouse X coordinate in pixels.
y mouse Y coordinate in pixels.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool IsLeftButtonDown ( ) const

Returns left mouse button state.

bool IsMiddleButtonDown ( ) const

Returns middle mouse button state.

bool IsRightButtonDown ( ) const

Returns right mouse button state.

bool IsDoubleClick ( ) const

Returns whether mouse button was double clicked

bool IsShiftKeyDown ( ) const

Returns shift key state.

bool IsControlKeyDown ( ) const

Returns control key state.

CStatus RegisterShortcutKey ( ULONG  in_virtualKeycode,
const CString &  in_description,
ULONG  in_modifiers = 0,
bool  in_repeats = false 
)

Register a tool keyboard shortcut.

Parameters:
in_virtualKeycode Virtual keycode for the keyboard shortcut.
in_description Shortcut key description.
in_modifiers. siKeyboardState modifier for the keyboard shortcut
in_repeats. If true key events will be continuously sent while the key is held down.
Returns:
CStatus::OK success.
CStatus::Fail error.
CStatus UnRegisterShortcutKey ( ULONG  in_virtualKeycode,
ULONG  in_modifiers = 0 
)

Unregister a tool keyboard shortcut.

Parameters:
in_virtualKeycode Virtual keycode for the keyboard shortcut.
in_modifiers. siKeyboardState modifier for the keyboard shortcut
Returns:
CStatus::OK success.
CStatus::Fail error.
bool IsShortcutKeyDown ( ULONG  in_virtualKeycode,
ULONG  in_modifiers = 0 
) const

Get current state of tool keyboard shortcut.

Parameters:
in_virtualKeycode Virtual keycode for the keyboard shortcut.
in_modifiers. siKeyboardState modifier for the keyboard shortcut
Returns:
True if shortcut key is pressed.
ULONG GetShortcutKey ( ) const

Get virtual keycode for the key being processed in KeyUp/KeyDown callback.

Returns:
Virtual keycode or 0 if called from outside KeyUp/KeyDown callbacks.
ULONG GetShortcutKeyModifiers ( ) const

Get modifiers for the key being processed in KeyUp/KeyDown callback.

Returns:
Modifier flags or 0 if called from outside KeyUp/KeyDown callbacks.
CStatus GetViewSize ( LONG &  width,
LONG &  height 
) const

Returns the size of the view in pixel coordinates.

Parameters:
width width of view in pixels
height height of view in pixels
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus GetViewport ( LONG &  x,
LONG &  y,
LONG &  width,
LONG &  height 
) const

Returns the 3D viewport in pixel coordinates. The 3D viewport can be a subset of the actual view size.

Parameters:
x horizontal offset in pixels
y vertical offset in pixels
width width of viewport in pixels
height height of viewport in pixels
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool IsInteracting ( ) const

Returns true if a MouseDown/MouseDrag/MouseUp is in progress.

bool IsActiveView ( ) const

Returns true if the view being drawn is the last view under the cursor.

bool IsNavigating ( ) const

Returns true if tool is being drawn and camera tool is currently active in supra mode.

LONG GetViewIndex ( ) const

Get index of current view. The view index may be used by the tool identify the view but the caller should not assume the index corresponds directly to the view manager (A/B/C/D) panes.

Returns:
Returns view index (greater or equal than zero) or -1 if the information is unavailable in current callback.
Camera GetCamera ( ) const

Return the camera for the current view

Returns:
Camera or invalid reference if unavailable in current callback.
CStatus SetCursor ( siToolCursor  in_cursorId )

Set tool cursor

Parameters:
in_cursorId Predefined cursor to use. Default is siArrowCursor.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus SetToolDescription ( const CString &  in_message )

Set tool description

Parameters:
in_message Tool message string with newlines separating description/left/middle/right message sections.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus EnableSnapping ( bool  in_enable )

Enable standard tool snapping behaviour

Parameters:
in_enable Enable standard control key snapping behaviour for this tool.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus GetViewPlane ( MATH::CPlane &  out_plane ) const

Get view plane

Parameters:
out_plane Get view aligned manipulation plane in this view.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus GetGridPlane ( MATH::CPlane &  out_plane ) const

Get grid plane

Parameters:
out_plane Get visible grid plane in this view.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus SetManipulationPlane ( const MATH::CPlane &  in_plane )

Set projection plane

Parameters:
in_plane New projection plane.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus ClearManipulationPlane ( )

Restore projection plane to default setting

Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool WasAborted ( ) const

Returns true if user pressed Escape to end mouse drag.

CStatus ExitTool ( )

Schedule this tool for termination

Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool GetFlag ( LONG  in_flag ) const

Returns the state of one of the various flags that affects tool behavior. You can set the value of a flag with ToolContext::SetFlag.

Parameters:
in_flag Value from the siToolCapabilities enum
CStatus SetFlag ( LONG  in_flag,
bool  in_enable 
)

Sets the state of one of the various flags that affects tool behavior. You can test the value of these flags with ToolContext::GetFlag.

Parameters:
in_flag Value from the siToolCapabilities enum
in_enable True to enable the flag and false to disable it.
Returns:
CStatus::OK success.
CStatus::Fail Unrecognized flag.
CStatus GetWorldPosition ( LONG  x,
LONG  y,
MATH::CVector3 &  out_world 
) const

Get 3D world-space point by projecting the 2D input point onto the current manipulation plane. If snapping is enabled and active then snapping will be applied to the resulting point. Detailed information about the snap target can be obtained using the snapping access methods such as ToolContext::GetSnapType following this call.

Parameters:
x view X coordinate in pixels.
y view Y coordinate in pixels.
out_world 3D world-space position.
Returns:
CStatus::OK Projection succeeded.
CStatus::Fail Unavailable in current callback or point does not intersect the projection plane.
CStatus GetWorldRay ( LONG  x,
LONG  y,
MATH::CLine &  out_ray 
) const

Get 3D world-space ray through the 2D input point. If snapping is enabled and active then snapping will be applied to the resulting ray. Detailed information about the snap target can be obtained using the snapping access methods such as ToolContext::GetSnapType following this call.

Parameters:
x view X coordinate in pixels.
y view Y coordinate in pixels.
out_ray 3D world-space ray.
Returns:
CStatus::OK Projection succeeded.
CStatus::Fail Unavailable in current callback.
CStatus WorldToView ( const MATH::CVector3 &  in_world,
MATH::CVector3 &  out_view 
) const

Convert a 3D world-space point to 2D pixel coordinates with depth. No snapping is applied to points. The X & Y coordinates of the output point represent 2D view coordinates while the Z component represents the depth.

Parameters:
in_world world-space input point
out_view view-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus ViewToWorld ( const MATH::CVector3 &  in_view,
MATH::CVector3 &  out_world 
) const

Convert a 2D pixel coordinate with depth to a 3D world-space point. No snapping is applied to points.

Parameters:
in_view view-space input point
out_view world-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus WorldToCamera ( const MATH::CVector3 &  in_world,
MATH::CVector3 &  out_camera 
) const

Convert a 3D world-space point to 3D camera-space point. No snapping is applied to points.

Parameters:
in_world world-space input point
out_camera camera-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus CameraToWorld ( const MATH::CVector3 &  in_view,
MATH::CVector3 &  out_world 
) const

Convert a 3D camera-space point to a 3D world-space point. No snapping is applied to points.

Parameters:
in_camera camera-space input point
out_world world-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus GetWorldToViewMatrix ( MATH::CMatrix4 &  out_worldToView ) const

Return matrix used to transform 3D world-space points to 2D pixel coordinates with depth.

Parameters:
out_worldToview world-to-view 4x4 matrix
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus GetWorldToCameraMatrix ( MATH::CMatrix4 &  out_worldToCamera ) const

Return matrix used to transform 3D world-space points to 3D camera-space points.

Parameters:
out_worldToCamera world-to-camera 4x4 matrix
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus Redraw ( bool  in_allViews = true )

Request redraw. In most cases the redraw happens automatically so the only place this is needed is to trigger redraw based on mouse move events. (when no mouse buttons are pressed)

Parameters:
in_allViews If true redraw all views. If false redraw current view only.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback.
CStatus DrawTextString ( const CString &  in_str,
siAlignment  in_hPos = siLeftAlign,
siAlignment  in_vPos = siBottomAlign 
)

Draw text at current raster position and with the specified alignment. Only valid during drawing.

Parameters:
in_str Text string to display.
in_hPos Horizontal text position relative to the current raster position. Default is siLeftAlign.
in_vPos Vertical text position relative to the current raster position. Default is siBottomAlign.
Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing.
CStatus GetTextSize ( const CString &  in_str,
LONG &  out_width,
LONG &  out_height,
LONG &  out_descent 
) const

Get size of text in 2D pixel coordinates. Only valid during drawing.

Parameters:
in_str Text string to measure.
out_width Width of text string in pixels.
out_height Height of text string in pixels.
out_descent Number of pixels the font extends below the baseline for the font.
Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing.
CStatus EditTextString ( CString &  io_str,
LONG  x,
LONG  y,
LONG  width,
LONG  height 
)

Display in-place text editing field at the specified 2D pixel coordinates. Only valid during mouse up.

Parameters:
io_str Text string to modify.
x left view coordinate of text editing box in pixels
y bottom view coordinate of text editing box in pixels
width width of text editing box in pixels
height height of text editing box in pixels
Returns:
CStatus::OK Success.
CStatus::False User cancelled editing.
CStatus::Fail Called from outside the mouse up callback.
CStatus BeginViewDraw ( )

Change drawing to 2D pixel coordinates. Only valid during drawing/picking.

Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing/picking.
CStatus EndViewDraw ( )

Change drawing back to 3D world-space coordinates. Only valid during drawing/picking.

Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing/picking.
bool IsViewDraw ( ) const

Returns true if view drawing is active.

CStatus BeginPickDraw ( LONG  x,
LONG  y,
LONG  width,
LONG  height 
)

Setup drawing for OpenGL picking. Only valid during mouse callbacks.

Parameters:
x left view coordinate of pick region in pixels
y bottom view coordinate of pick region in pixels
width width of pick region in pixels
height height of pick region in pixels
Returns:
CStatus::OK Success.
CStatus::Fail Called from outside mouse callbacks.
CStatus EndPickDraw ( )

Restore drawing to original state. Only valid during mouse callbacks.

Returns:
CStatus::OK Success.
CStatus::Fail Called from outside mouse callbacks.
bool IsPickDraw ( ) const

Returns true if pick drawing is active.

CStatus BeginParameterUpdate ( const Parameter &  in_param,
double  in_time = DBL_MAX 
)

Start an interaction update on a parameter. At the end of interaction a single undo event will be logged.

Parameters:
in_param The parameter to update.
in_time Time defaults to the current frame if in_time is set with DBL_MAX.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus UpdateParameter ( const Parameter &  in_param,
const CValue &  in_value 
)

Update value of parameter during interaction. At the end of interaction a single undo event will be logged.

Parameters:
in_param The parameter to set.
in_value New value for parameter.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus EndParameterUpdate ( const Parameter &  in_param )

Stop updating parameter and log undo event. At the end of interaction a single undo event will be logged.

Parameters:
in_param The parameter to stop updating.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus BeginKinematicStateUpdate ( const KinematicState &  in_kine,
double  in_time = DBL_MAX 
)

Start an interaction update on a kinematic state. At the end of interaction a single undo event will be logged.

Parameters:
in_kine The kinematic state to update.
in_time Time defaults to the current frame if in_time is set with DBL_MAX.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus UpdateKinematicState ( const KinematicState &  in_kine,
const MATH::CTransformation &  in_value 
)

Update value of kinematic state during interaction. At the end of interaction a single undo event will be logged.

Parameters:
in_kine The kinematic state to set.
in_value New value for the kinematic state.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus EndKinematicStateUpdate ( const KinematicState &  in_kine )

Stop updating kinematic state and log undo event. At the end of interaction a single undo event will be logged.

Parameters:
in_kine The kinematic state to stop updating.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus BeginTransformUpdate ( const CRefArray &  in_objects,
double  in_time = DBL_MAX 
)

Start an interaction update on a list of objects or components. At the end of interaction a single undo event will be logged.

Parameters:
in_objects List of objects or components to update.
in_time Time defaults to the current frame if in_time is set with DBL_MAX.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus UpdateTransform ( const CRefArray &  in_objects,
const MATH::CTransformation &  in_value,
siTransformFilter  in_srt,
siRefMode  in_refMode = siLocal,
siDeltaMode  in_delta = siRelative,
siAxesFilter  in_axesFilter = siXYZ,
bool  in_usePivot = false,
const MATH::CVector3 &  in_pivot = MATH::CVector3(),
const MATH::CTransformation &  in_reference = MATH::CTransformation() 
)

Update value of objects or components during interaction. At the end of interaction a single undo event will be logged.

Parameters:
in_objects List of objects or components to update.
in_value New transform values.
in_srt Type of transform that will be applied.
in_refMode Reference mode to use for the transform. Default is siLocal.
in_delta Relative or absolute transform. Default is siRelative.
in_axesFilter Used with siAbsolute to specify which transform axes to modify. Default is siXYZ.
in_usePivot Perform transform relative to a pivot. Default is false.
in_pivot Global pivot location. Default pivot is world-space origin.
in_reference Reference-to-world transform to use with siObjCtr. Default is identity which is world-space.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus EndTransformUpdate ( const CRefArray &  in_objects )

Stop updating objects or components and log an undo event. At the end of interaction a single undo event will be logged.

Parameters:
in_objects List of objects or components to update.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
siSnapType GetSnapType ( ) const

Return the siSnapType from the last snap operation or the current snap candidate if called from within the SnapValid callback. siSnapNone is returned if nothing was snapped or if this information is unavailable in the current callback.

CRef GetSnapObject ( ) const

Return the last snapped object or the current snap candidate object if called from within the SnapValid callback. Some snap types like siSnapNone and siSnapGrid do not have an associated object and in this case the returned reference will be invalid.

CRef GetSnapComponent ( ) const

Return the last snapped component or the current snap candidate if called from within the SnapValid callback. Some snap types are not associated with a component and in that case the returned reference will be invalid.

CStatus Snap ( LONG  x,
LONG  y,
LONG  size,
ULONG  in_snaptype,
const CStringArray &  in_families,
const CRefArray &  in_objects,
MATH::CVector3 &  out_world 
) const

Get 3D world-space point by snapping the 2D input point using the specified snap settings. Detailed information about the snap target can be obtained using the snapping access methods such as ToolContext::GetSnapType following this call.

Parameters:
x View X coordinate in pixels.
y View Y coordinate in pixels.
size Size of snap region in pixels.
in_snaptype Mask of siSnapType flags used to specify what types of snap targets will be considered. For example pass siSnapPoint|siSnapGrid to enable both point and grid snapping.
in_families An array of families defined by ::siFamily or an empty array if none are required. The families are used for narrowing down the search, the array can contain X3DObject families like si3DObjectFamily or primitive families such as siNurbsSurfaceMeshFamily and siNullPrimitiveFamily. Only the children objects that match one of the supplied families are considered. If primitive families are supplied then only the objects defined with a primitive that belongs to one of them are considered. The list of valid families are the following: 
                        si3DObjectFamily                        siLatticeFamily
                        siCameraFamily                          siLightPrimitiveFamily
                        siChainElementFamily                    siMeshFamily
                        siControlObjectFamily                   siNullPrimitiveFamily
                        siCurveFamily                           siNurbsCurveListFamily
                        siGeometryFamily                        siNurbsSurfaceMeshFamily
                        siGeometryShaderFamily                  siSurfaceCurveFamily
                        siImplicitGeometryFamily                siSurfaceFamily
in_objects List of objects to snap to. If empty then the entire scene will be used.
out_world 3D world-space position.
Returns:
CStatus::OK Snap succeeded.
CStatus::Fail Unavailable in current callback.
CStatus::InvalidArgument Invalid argument specified.
CStatus Pick ( const CLongArray &  in_points,
siPickMode  in_pickMode,
siPickType  in_pickType,
const CString &  in_filter,
const CRefArray &  in_objects,
CRefArray &  out_picked 
) const

Perform a pick operation on the view and return the list of objects or components that match.

Parameters:
in_points Points to use for picking. The array size should be a multiple of 2 with each pair of values representing a single 2D view point. The number of points required depends on the picking mode. For siPickRaycast a single point is required. For siPickRectangle and siPickRectangleRaycast two points are needed. For siPickLasso and siPickFreeform can use an arbitrary number of points which define a path.
in_pickMode Picking mode. For objects use siPickSingleObject or siPickMultipleObjects and for subcomponents use siPickSingleSubComponent or siPickMultipleSubComponents.
in_pickType Defines the type of picking used. One of siPickRectangle, siPickRaycast, siPickLasso, siPickFreeform or siPickRectangleRaycast.
in_filter A filter to use for picking. For object picking this can be empty but must be supplied for subcomponent picking to identify the subcomponent to pick. The list of valid filters are the following: 
                        siCameraFilter                          siBoundaryFilter
                        siChainElementFilter                    siEdgeFilter
                        siControlFilter                         siIsopointFilter
                        siCurveFilter                           siKnotFilter
                        siEffectorFilter                        siPointFilter
                        siGeometryFilter                        siPolygonFilter
                        siGroupFilter                           siUIsolineFilter
                        siImplicitFilter                        siVIsolineFilter
                        siLatticeFilter                         siUKnotCurveFilter
                        siLightFilter                           siVKnotCurveFilter
                        siModelFilter
                        siNullFilter
                        siPointCloudFilter
                        siPolyMeshFilter
                        siPrimitiveFilter
                        siSkeletonJointFilter
                        siSubSurfaceFilter
                        siSurfaceCurveFilter
                        siSurfaceMeshFilter
                        siTextureControlFilter
                        siTrimCurveFilter
in_objects List of objects to pick. When picking objects this list is optional and if empty the entire scene will be used. When picking subcomponents the list must supplied and non-empty.
out_picked List of picked objects.
Returns:
CStatus::OK Pick succeeded.
CStatus::Fail Unavailable in current callback.
CStatus::InvalidArgument Invalid argument specified.
PickBuffer GetPickBuffer ( LONG  x,
LONG  y,
LONG  width,
LONG  height,
const CString &  in_filter,
const CRefArray &  in_objects,
siViewMode  in_viewMode = siShaded 
) const

Low-level picking operation that returns a buffer that can be used to map view coordinates to objects and component indices. The pick buffer acts like a snapshot taken at the time of the call and once it has been generated objects and component indices can be retrieved from the pick buffer without any additional overhead. The pick buffer will only return information about the closest object or component and cannot return information for objects and components that are hidden behind other objects or components. Passing an empty pick region (0,0,0,0) will generate a pick buffer that covers the entire view.

Parameters:
x Left view coordinate of picking region.
y Bottom view coordinate of picking region.
width Width of picking region in view coordinates.
height Height of picking region in view coordinates.
in_filter A filter to use for picking. For object picking this can be empty but must be supplied for subcomponent picking to identify the subcomponent to pick. The list of valid filters are the following: 
                        siObjectFilter
                        siPointFilter
                        siEdgeFilter
                        siPolygonFilter
in_objects List of objects to pick. When picking objects this list is optional and if empty the entire scene will be used. When picking subcomponents the list must supplied and non-empty.
in_viewMode siViewMode to use when generating the pick buffer. Passing siAll will use the current display mode. Default is siShaded. The list of valid view modes are the following: 
                        siAll (current view mode)
                        siWireframe
                        siShaded (default)
Returns:
PickBuffer. If unavailable in the current callback or any arguments are invalid then the resulting PickBuffer will be invalid.
CStatus ShowContextMenu ( LONG  x,
LONG  y,
siAlignment  in_hPos = siLeftAlign,
siAlignment  in_vPos = siTopAlign 
)

Show a tool context menu using the specified position/alignment. Only valid during mouse down or mouse up. The context menu needs to be defined by the MenuInit callback in the tool.

Parameters:
x View X coordinate in pixels.
y View Y coordinate in pixels.
in_hPos Horizontal menu position relative to the input position. Default is siLeftAlign.
in_vPos Vertical menu position relative to the input position. Default is siTopAlign.
Returns:
CStatus::OK Success.
CStatus::False Nothing selected from menu or no menu to display.
CStatus::Fail Called from outside mouse down or mouse up callback.
Image LoadImageFromFile ( const CString &  in_filename,
bool  in_relativePath = true 
)

Load an image from a file.

Parameters:
in_filename Filename of image to load.
in_relativePath If true in_filename is relative to plugin location.
Returns:
Requested Image.
The documentation for this class was generated from the following file:
Generated on Mon Sep 12 2011 16:31:48 by doxygen 1.7.4
Please send us your comment about this page