.

Developer

C++

Overview

This hands-on tutorial is designed to show you how to build a functioning Rhino plug-in.

Requirements

In order to complete this tutorial, you will need to have Microsoft Visual C++ 2005 installed on your system. You will also need to have downloaded and installed the Rhino 4.0 SDK.

What’s a Plug-In?

From a user’s standpoint, a Rhino plug-in is a software module that extends the functionality of Rhino by adding new commands, features, or capabilities. From a programmer’s perspective, a Rhino plug-in is a regular Windows Dynamic Link Libraries, or DLL that links with the Rhino SDK libraries. Examples of Rhino plug-ins include Bongo, Flamingo, and Penguin.

Plug-in Type

There are five different types of Rhino plug-ins.

1. General Utility. A general utility plug-in is a general purpose extension that can contain one or more commands.
2. File Import. A file import plug-in is an extension that imports data from other file formats into Rhino. A single file import plug-in can support more that one file type.
3. File Export. A file export plug-in is an extension that exports data from Rhino to other file formats. A single file export plug-in can support more than one file type.
4. Custom Rendering. A custom rendering plug-in applies materials, textures, and lights to a scene to produce rendered images.
5. 3-D Digitizing. A 3-D digitizing plug-in interfaces with 3-D digitizing and measurement devices.

The "Do-Nothing" Plug-in

The Rhino SDK includes a Visual Studio Wizard. The wizard program generates the code a functioning plug-in. Follow these steps to build the plug-in:

1. Run Wizard to Generate Plug-in Source Code.

Choose New->Project… from the Visual Studio File menu. From the New Project dialog, select the Rhino plug-in template from the list of installed templates.

 

 

Type the project name as show. You can enter a different name if you want, but the wizard uses the project name when it creates files and classes. If you enter a different name, your files and classes will have a name different from that of the files and classes mentioned in this tutorial.

Don’t forget to choose a location to store the project. When finished, click the OK button.

 

 

Upon clicking OK, the Overview page of the Rhino Plug-In Wizard dialog will appear. This page gives you a summary of the type of project that the wizard is going to create. By default, the wizard will do the following:

• Create a general utility plug-in
• Include source file comments.
• Include support for online help.

If you are satisfied with the default settings, just click the Finish button. If you want to change any of these settings, just click the Next button.

 

 

The Plug-in Settings page allows you to modify a number of settings used by the wizard when generating the plug-in source code.

• Plug-in name. Modify this field if you want to change the name of the plug-in. Note, modifying this field does not modify the project name but rather the name of the plug-in as listed in Rhino’s PlugInManager dialog box.
• Plug-in type. Select the type of plug-in that you want the wizard to create.
• Source file comments. Select this option if you want the wizard to add verbose comments to the generated source files.
• Online help. Select this option if you want your plug-in to support online help. If selected, a menu item will be displayed on Rhino's help menu.
• Automation. Select this option to allow your program to manipulate objects implemented in another program. Selecting this option also exposes your program to other Automation client plug-ins.
• Windows sockets. Select this option to indicate that your program supports Windows sockets. Windows sockets allow you to write programs that communicate over TCP/IP networks.

For this tutorial, just accept the default settings. Click the Finish button, and the wizard begins to generate your plug-in project’s folders, files, and classes. When the wizard is finished, look through the plug-in project using Visual Studio’s Solution Explorer. The following files are of interest:

• cmdTest.cpp - Sample "Test" Rhino command source code.
• Resource.h - #define constant definitions.
• Test.def – Windows module definition file.
• Test.rc – Resource script file.
• Test.vcproj – Project file that allows Visual C++ to build your plug-in.
• TestApp.h – Application class header file that contains the CTestApp class declaration.
• TestApp.cpp – Application class implementation file that contains the CTestApp member functions.
• TestPlugIn.h – Plug-in class header file that contains the CTestPlugIn class declaration.
• TestPlugIn.cpp - Plug-in class implementation file that contains the CTestPlugIn member functions.

2. Compile and Link the Generated Code

The Rhino plug-in wizard, in addition to generating code, creates a custom project file for your plug-in. This file, Test.vcproj, specifies all of the file dependencies together with the compile and link option flags.

Before we can build our project, we need to fill in the Rhino plug-in developer declarations. These declarations will let the user of our plug-in know who produced the plug-in and where they can support information if needed. Open TestPlugIn.cpp and modify the following lines of code, providing your company name and other support information.

  RHINO_PLUG_IN_DEVELOPER_ORGANIZATION( L"My Company Name" );
  RHINO_PLUG_IN_DEVELOPER_ADDRESS( L"123 Developer Street\r\nCity State 12345-6789" );
  RHINO_PLUG_IN_DEVELOPER_COUNTRY( L"My Country" );
  RHINO_PLUG_IN_DEVELOPER_PHONE( L"123.456.7890" );
  RHINO_PLUG_IN_DEVELOPER_FAX( L"123.456.7891" );
  RHINO_PLUG_IN_DEVELOPER_EMAIL( L"support@mycompany.com" );
  RHINO_PLUG_IN_DEVELOPER_WEBSITE( L"http://www.mycompany.com" );
  RHINO_PLUG_IN_UPDATE_URL( L"http://www.mycompany.com/support" );

When finished, delete the following line of source code as the #error directive will prevent the project from building.

  #error Developer declarations block is incomplete!

If you do not delete this line, the plug-in will build. You are now ready to build the project by picking Build Test from the Build menu. If the build was successful, a plug-in file named Test_d.rhp is created in the project’s Debug folder.

3. Test the Resulting Plug-in.

Choose Start Debugging from the Debug menu. This will load Rhino. The version of Rhino that is launched depends on the configuration that you build. The wizard adds the following configurations to your project.

• Debug - This is a regular debug configuration. This configuration will link with debug MFC, Rhino, and openNURBS libraries. Plug-ins built with this configuration can only be used in the debug version of Rhino, Rhino4_d.exe, that is installed with the Rhino SDK.
• Pseudo-Debug - This is a release configuration that also includes debug information. This configuration will link with release MFC, Rhino, and ""openNURBS" libraries, thus is will have limited debugging capabilities. Plug-ins built with this configuration can only be used in the release version of Rhino, Rhino4.exe, that is installed from your Rhino CD.
• Release - This is a regular release configuration. This configuration will link with release MFC, Rhino, and openNURBS libraries. Plug-ins built with this configuration can only be used in the release version of Rhino, Rhino4.exe, that is installed from your Rhino CD.

For this tutorial, build the debug configuration.

From within Rhino, select Options from the Tools menu. Navigate to the Plug-ins page under Rhino Options and install your plug-in. Note, being that the debug version of Rhino will only load debug plug-ins, no other plug-ins will show up in the list.

 

 

Once your plug-in is loaded, close the options dialog and run your Test command. You have finished creating your first plug-in.