Components of a Custom Display Host

 
 
 

This section contains the following topics:

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:

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.