Site Tools


Creating Your First Rhino 5 Plug-in

Developer: C++
Summary: This hands-on tutorial is designed to show you how to build a functioning Rhino 5 plug-in. If you are using the Rhino 4.0 C++ SDK, see Creating Your First Rhino 4.0 Plug-in.

Requirements

In order to complete this tutorial, you will need to have the following installed on your system:

  • Microsoft Visual C++ 2010 (for Rhino 5 64-bit)
  • Microsoft Visual C++ 2005 (for Rhino 5 32-bit)

What is 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 DLLs that links with the Rhino SDK libraries.

Examples of Rhino plug-ins include:

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.
Note: File Import, File Export, Custom Rendering and 3-D Digitizing plug-ins are all specialized enhancements to the General Utility plug-in. Thus, all plug-in types can contain one or more commands.

The "Do-Nothing" Plug-in

The Rhino SDK includes a Visual Studio Project 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

Launch Visual Studio 20100 and select File → New → Project…. From the New Project dialog, select the Rhino 5.0 Plug-in template from the list of installed templates.



Type the project name as shown. You can enter a different name if you want. 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 5.0 Plug-In Wizard dialog will appear. This page gives you an overview 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:

  • Test.vcxproj – Project file that allows Visual C++ to build your plug-in.
  • stdafx.h - Main project header.
  • stdafx.cpp - Used to generate precompiled header.
  • TestApp.h – Application class header that contains the CTestApp class declaration.
  • TestApp.cpp – Application class implementation that contains the CTestApp member functions.
  • TestPlugIn.h – Plug-in class header that contains the CTestPlugIn class declaration.
  • TestPlugIn.cpp - Plug-in class implementation that contains the CTestPlugIn member functions.
  • cmdTest.cpp - Sample “Test” Rhino command.
  • Resource.h - #define constant definitions for resources.
  • Test.rc – Resource script.
  • Test.def – Module definition.

2. Examining Project Settings

With Visual Studio 2010, a project can target a different version of the Visual C++ libraries and compiler. This is done by configuring the project use a different Platform toolset.

Reviewing the above image, you can see that the Rhino 5 plug-in project wizard configures 32-bit builds to use the v80rhinos platform toolset, which equates to using Visual Studio 2005's libraries and compiler. This platform toolset configuration is installed on your system by the Rhino C++ SDK Installer.

If you change the active platform from Win32 to x64, you will see that 64-bit builds will use v100, or Visual Studio 2010.

The advantage that platform toolsets provide is that they enable you to take advantage of the IDE enhancements in Visual Studio 2010 while you continue to use an older version of the Visual C++ libraries and compiler.

The Rhino plug-in wizard, in addition to generating code, creates a custom project file for your plug-in. This file, Test.vcxproj, 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.

4. Test the Resulting Plug-in

From Visual Studio, select Debug → Start Debugging. 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 - The Debug configuration of your program is compiled with full symbolic debug information and no optimization. Optimization complicates debugging, because the relationship between source code and generated instructions is more complex. The Debug configuration also links with debug runtime libraries. Plug-ins built with the Debug configuration will only load in the debug version of Rhino included with the Rhino C++ SDK.
  • PseudoDebug - The PseudoDebug project is a Release project that disables optimizations and generates debugging information using the compiler’s Program Database (/Zi) option and the linker’s Generate Debug Information (/DEBUG) option. These option settings allow you to use the debugger while you are developing your custom plug-in. The PseudoDebug configuration also links with release runtime libraries. Plug-ins built with the PseudoDebug configuration will only load in the release version of Rhino that was installed from your Rhino CD.
  • Release - The Release configuration of your program contains no symbolic debug information and is fully optimized. Debug information can be generated in PDB Files (C++) depending on the compiler options used. Creating PDB files can be very useful if you later need to debug your release version. The Release configuration also links with release runtime libraries. Plug-ins built with the Release configuration will only load in the release version of Rhino that was installed from your Rhino CD.

For this tutorial, build the Debug configuration.

From within Rhino, select Tools → Options. 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.


developer/sdksamples/rhino5pluginwiz.txt · Last modified: 2014/06/26 (external edit)