Components of a Custom Display Host

View Context: Initializing and Drawing the Interface

The custom display host notifies your custom display every time something changes in Softimage using a ViewContext object. This ViewContext object is also available when your custom display gets initialized.

In the example below, the custom display creates a Win32 dialog and parents it to the Softimage window using the ViewContext.GetParentWindowHandle call. As mentioned above, you receive a ViewContext object upon notification. Use the ViewContext to retrieve the relevant notification information. For more information about this class, see "ViewContext" in the C++ API Reference.

The ViewContext class contains a function (GetParentWindowHandle) that enables you to access the top-level Windows handle (hWnd).

Initializing on Windows

The following is an example of initializing the custom display and getting the Windows handle. Here, a dialog is created as a child of the Windows handle specified by the view context.

LRESULT	CCustomUI::Init( XSI::CRef& in_pViewCtx )
{
	XSI::ViewContext l_vViewContext = in_pViewCtx;
	l_hWnd = CreateDialog(  __gInstance ,  MAKEINTRESOURCE(IDD_CUSTOMUI_EXAMPLE), (HWND)l_vViewContext.GetParentWindowHandle(), (DLGPROC)_view_proc);

	return S_OK;
}

The view context also gets the notification data (GetNotificationData).

LRESULT CCustomUI::Notify ( XSI::CRef& in_pViewCtx )
{
	using namespace XSI;

	// Convert the CRef into a ViewContext

	XSI::ViewContext l_vViewContext = in_pViewCtx;

	// Retrieve the notification information from the view context
	
	XSI::siEventID in_eNotifcation;
	void*	in_pData;

	l_vViewContext.GetNotificationData ( in_eNotifcation, &in_pData );

Initializing on Linux

Here's an example of how to properly initialize a custom display under Motif:

void XWindowExample_Init (XSI::CRef in_pViewCtx)
{
// Get the view context object
XSI::ViewContext l_vViewContext = in_pViewCtx; 

// Ask Softimage for the Top Level Widget
Widget g_TopLevel = (Widget)l_vViewContext.GetTopLevelWidget(); 

// Initialize our Widget from class 
XtInitializeWidgetClass ( xmFormWidgetClass ); 

// Create a form widget and parent it to the Top Level Widget Softimage has provided
g_MyWindow = XtVaCreateManagedWidget ( "main_form",
			xmFormWidgetClass,
			g_TopLevel,
				XmNwidth, 300,
			XmNheight, 300,
		NULL ); 

// Create a button and parent it to the form
g_theWidget = XtVaCreateManagedWidget("main_button",
			xmPushButtonWidgetClass,
			g_MyWindow,
			XmNlabelString, XmStringCreate ("Push Me", XmSTRING_DEFAULT_CHARSET),
			NULL ); 

// Create a second button and parent it to the form
g_theWidget2 = XtVaCreateManagedWidget("main_button2",
			xmPushButtonWidgetClass,
			g_MyWindow,
			XmNx,100,
			XmNy,100,
			XmNlabelString, XmStringCreate ("Dont Push Me", XmSTRING_DEFAULT_CHARSET),
			NULL );

XtSetMappedWhenManaged(g_TopLevel, 0); 

// Add callback functions
XtAddEventHandler( g_theWidget, ButtonPressMask, FALSE, ButtonCB, NULL );
XtAddEventHandler( g_theWidget2, ButtonPressMask, FALSE, ButtonCB2, NULL ); 

XtRealizeWidget(g_TopLevel); 

// This will register our form class (our shell object) with Softimage Custom Display
// Architecture. It is VERY IMPORTANT that this is done at the end of the
// initialization and after the widgets have been Realized.
// 
// Internally, this will start the Xt main loop and will start broadcasting 
// messages
l_vViewContext.SetXWindowTopLevel ( (void*)XtWindowOfObject(g_MyWindow) );
}

View Notification

Once the custom display is initialized, several classes are available to notify you of changes in the Softimage scene:

CSelectionChangeNotification: When the selection changes on a component in Softimage, the display host returns the new selection list as an array of CRef objects.
CTimeChangeNotification: When the timeline changes in Softimage, the display host can return the current time and its state (stop, pause, step, scrub, etc.)
CValueNotification: When a component or object's value changes, the display host returns the changed value. Note that what it returns depends on what the object or component is. For example, if the position of an object in the scene changes, the display host will send the global and local KinematicState state objects in 2 separate notifications.If the value represents a point or polygon or any other kind of primitive, it returns the Primitive. Refer to the C++ API Reference for more information about the return values available in its classes.

For more information about the classes and functions defined specifically for the custom display host, see the C++ API Class Reference.

Callbacks

Custom displays must define five callbacks to properly connect to Softimage it as well as to register the .dll with the plug-in registrar.

This section contains the following topics:

Custom View Callbacks

Init

Called by Softimage when the plug-in is first initialized. This callback is required.

void			MyPluginName_Init (XSI::CRef in_pViewCtx)

Term

Called by Softimage when the plug-in is terminated (when the top-level window is destroyed). This callback is required.

void			MyPluginName_Term (XSI::CRef in_pViewCtx)

Notify

Called by Softimage when something occurs in the scene, such as a parameter change or selection change. This callback is not mandatory.

void			MyPluginName_Notify	( XSI::CRef in_pViewCtx )

Plug-in Registrar Callbacks

Custom displays take advantage of Softimage's self-installing plug-in mechanism. The following gives a brief description of these callbacks. For detailed information about self-installing plug-ins, see Building and Deploying Customizations.

Registering and Defining the Custom Display Host

The following shows how a custom display host is registered (XSILoadPlugin) and defined as a self-installing item (RegisterCustomView).

XSI::CStatus XSILoadPlugin( XSI::PluginRegistrar& in_reg )
{
	in_reg.PutAuthor( L"SoftimageUser" );
		in_reg.PutName( L"MyPluginName" );
	in_reg.PutVersion( 1, 0 );

	in_reg.RegisterCustomView( L"MyPluginName" );

	return XSI::CStatus::OK;

Unloading the Custom Display Host

Softimage performs its own maintenance routines when unloading any plug-in; however, you can add your own activities, such as writing to message logs, freeing used memory and releasing used SDK objects, etc.

XSI::CStatus XSIUnloadPlugin( const XSI::PluginRegistrar& in_reg )
{
	return XSI::CStatus::OK;
}

Loading Custom Display Host Applications in Softimage

Viewport

Once defined, Softimage automatically creates a menu entry item in the viewport menu.

Floating Window

To display in a floating window, choose ApplicationViewsCustom Display Host.

A floating window appears. Right-click and choose from the contextual menu.