.

Rhino 4.0 C++ SDK Getting Started Guide

Summary

The following information is provided to assist Rhino plug-in developers in porting their projects to Rhino 4.0.

First Time Users

Follow these 3 steps to make your first Rhino 4.0 plug-in.

1. Install the Rhino 4.0 SDK. The last step of the installation process takes you to this web page.
2. Make sure you are using Visual C++ 2005.
3. Use the Rhino 4.0 plug-in Project Wizard to make your first plug-in.

Visual C++ 2005

Rhino 4.0 is built using Visual C++ 2005 in Visual Studio 2005 (version 8.0). Rhino 4.0 C++ plug-ins must be built using this compiler.

Visual C++ 2005 Service Pack 1

If you are using Visual C++ 2005 Service Pack 1, then you will need to redistribute the Visual C++ 2005 Service Pack 1 version of the C-Runtime libraries with your plug-in. For more information, see the following link:

http://en.wiki.mcneel.com/default.aspx/McNeel/SdkVc2005Sp1.html

Rhino 4.0 plug-in Project Wizard

The Rhino 4.0 SDK installs a Visual Studio project wizard to help you create plug-in projects. To use the wizard select "Rhino Plug-in" from those listed by the Visual C++ 2005 New->Project... menu. Detailed step-by-step instruction are available on the Rhino 4.0 plug-in Project Wizard page.

Command Wizard

The command Wizard is a handy tool for adding new commands to your plug-in. The Rhino 4.0 SDK command wizard is a stand alone Windows application, named RhinoCommandWizard.exe, that copies new class definitions to the Windows clipboard (similar to Guidgen.exe). It can be found in the SDK's CmdWizard folder. See the Visual Studio help file for details on adding tools to its Tools menu.

Migrating Plug-in Projects

As mentioned above, to build plug-ins for Rhino 4.0, you will need to use a different compiler - Visual C++ 2005. There have also been a number of changes in the project settings (e.g. compiler, linker, etc) required by V4 plug-ins. Because of these changes, we recommend that you do not try to migrate V3 plug-in projects to V4 by just opening Visual Studio 6.0 projects or workspaces (DSP, DSW) in Visual Studio 2005.

Instead, we recommend that you run the new plug-in project wizard that comes with the V4 SDK to build new plug-in projects. Then, copy your project specific code from your V3 projects to your new V4 projects. In doing this, you can be assured that your compiler settings will agree with what is required by Rhino 4.0.

New Debug Rhino and Project Configuration

The Rhino 4.0 SDK includes a debug version of both Rhino (Rhino4_d.exe) and openNURBS (opennurbs_d.dll). The debug version of Rhino is installed in the same location as the production version of Rhino 4.0.

The Debug project configuration, generated by the V4 project wizard, has been modified so as to be a true Debug configuration, not a "pseudo-debug" configuration as provided in V3. By providing a full Debug version of Rhino and a true Debug configuration, you will be able to get better debugging infomation and hopefully detect more memory leaks.

Also, the V4 project wizard generates a new PseudoDebug configuration which is equivalent to the V3 Debug configuration - Release mode with Debug info. The Release configuration has not changed.

Note, if you build a Debug version of your plug-in, it will only load in the debug version of Rhino (Rhino4_d.exe) installed with the SDK. If you want to load a plug-in in a release version of Rhino (Rhino4.exe), you will need to build either a Release or PseudoDebug version of your plug-in.

Unicode

Rhino 4.0 is a true Unicode application. As a result, plug-ins written for Rhino 4.0 are required to be compiled using the Unicode character set.

• In Unicode builds, your project should define UNICODE and _UNICODE. and it should not define MBCS and _MBCS. These definitions can be handled automatically if you use the Visual Studio IDE and the .vcproj file to configure your project.

• Most programmers are accustomed to using the char type to contain character data. A string is typically defined using a char * (pointer to char) or a char[] (array of type char). Unicode text handling requires use of the wchar_t type, which is the ANSI C++ standard keyword for the Unicode type. wchar_t is a 16-bit value in Visual C++ and is usually defined as an unsigned short. Strings are typically wchar_t* pointers or wchar_t[] arrays.

• Microsoft Visual Studio supports the wchar_t type as both a native built-in type and as a typedef for unsigned short. By default, the C++ compiler resolves wchar_t as an unsigned short. However, if you compile with the /Zc:wchar_t flag, the compiler assumes the native wchar_t type. The use of the /Zc:wchar_t flag is required for Rhino 4.0 plug-ins.

• You can keep your code clean and simple by using the following data types, classes and runtime functions:

 wchar_t*
 const wchar_t*
 L"...."
 CString
 ON_wString
 wcslen
 wcscmp
 wcsncmp, etc...


 *If you need an ASCII string, then use:
 char*
 const char*
 "..."
 ON_String
 strlen
 strcmp
 strncmp, etc...

• You MUST NOT use sizeof() to return the number of characters in a TCHAR or wchar_t string. The following is the proper method for using the sizeof operator when using Unicode text strings.

 wchar_t wszBuffer[24];
 GetWindowText( hWnd, wszBuffer, sizeof(wszBuffer)/sizeof(wchar_t) );

• Use ON_UuidToString() and ON_UuidFromString() to convert between strings and uuids. The Windows ::UuidToString() has a flaw in the way the system header declares the function.

• More on this subject to come.

User Data

For general information about user data see Rhino4PlugInUserData.

An important change from V3 to V4 is that you must put your plug-in's id in the ON_UserData::m_application_uuid field. Please see Rhino4PlugInUserData for complete details and an example.

If you want a V4 plug-in to save information in V3 files or you want a V4 plug-in to read information from V3 files, then instruction are available in Rhino4MultiVersionUserDataSupport. Be aware that adding robust multi-version support for plug-in user data requires expert skills and careful testing.

Automation

We have changed what happens when you create the Rhino4 application object. When automating Rhino 3.0, when you created the Rhino3 application object, using CreateObject(), if an instance of Rhino was already running, you were given a reference to the existing Rhino3 application object. According to Microsoft and many of our 3rd party developers, this is incorrect behavior for a single document application. This has been fixed in Rhino 4.0. When you automate Rhino 4.0, creating a Rhino4 application object, using CreateObject(), will result in a new running instance of Rhino 4.0.

For details, see the following wiki page:

http://en.wiki.mcneel.com/default.aspx/McNeel/Rhino4Automation.html