This section is dedicated to third party software developers who wish to write plug-in modules for Okino's NuGraf and PolyTrans software packages (import/export modules will also be usable within the special native versions of PolyTrans such as PolyTrans-for-MAX and PolyTrans-for-Maya).
The following information will provide a cursory overview of the Okino Plug-Ins SDK, what kind of plug-ins can be created and what APIs are exposed to third party developers. To view what other developers have written using this SDK, and have wished to openly publish, please
click here to visit the Okino Third Party Plug-In Modules WEB page.
If you are interested in writing a plug-in module then please send an email to sdk_support@okino.com. There is no charge to using the SDK. However we do require that every developer read and sign off on our normal SDK usage agreement.
The SDK comes with reams of API documentation and a number of well thought out examples. The stock 3D exporter, in particular, is a complete exporter solution which you only need to tear down (and not build up by yourself) then merge with your own file format information - we have used too many third party SDKs ourselves to know how daunting the task of writing a converter can be without a good foundation of example code and related documentation.
Overview of the Various Plug-In Types and APIs
Okino's plug-in SDK has evolved over a long period of time to the point today where the shipping versions of
the PolyTrans and NuGraf software allow for 3 major types of plug-in modules:
All compiled modules are stored in the "vcplugin" directory of the stand-alone PolyTrans/NuGraf software and are associated with 3 file extensions:
The core executable is contained in the .dll file.
The "run time information" is contained in the .rti file.
And the optional help file is contained in the .chm or .hlp file.
When the software starts up it sorts the plug-ins according to the prefix on each of them and also the contents of the .rti files. Import converters begin with the letters "imp_", export converters begin with the letters "exp_" and the system-level plug-ins begin with the letters "ui_". Each converter is considered "unique" based on the GUID number contained in the .rti file, as well as some GUIDs used within the system-level plug-ins.
The 3D model import and export converters will show up inside the user interface in the File/Import and File/Export menus (for NuGraf) or Translate!/Import and Translate!/Export for PolyTrans. The system-level plug-ins optionally can have custom menu items added to any major main menu (the "Plug-Ins" menu is default) as their main method of execution by the user, and they can add custom docking or MDI-document windows to the user interface, or custom panels to the "Selector Window". Import/export converter plug-ins can also run inside PolyTrans-for-MAX, PolyTrans-for-Maya, PolyTrans-for-Macromedia-Director, etc. However, the system-level plug-ins can only run within the NuGraf or PolyTrans stand-alone Windows software.
The "Big" Picture
The following block diagram shows the basic interrelationship of the various components and APIs which make up the major Okino software (external modules such as PolyTrans-for-MAX, PolyTrans-for-Maya and PolyTrans-for-Director are not shown).
The NuGraf Developer's 3D Toolkit. This forms the heart and core of all Okino software. In general terms, the toolkit is used for all 3d scene graph management functions, Okino .bdf file I/O management, bitmap import/export/conversion, and as a framework of 3D functionality for the higher-level Microsoft Windows user interface.
The stand-alone PolyTrans/NuGraf software. This can be considered the Microsoft Windows user interface layer to the NuGraf 3D Toolkit core software. For the simplistic explanation provided in this section, the user interface component hosts the mechanisms to load/execute/control the system-level, import and export plug-in modules. The NuGraf 3D Toolkit plays no role in the management of the plug-in modules since plug-ins are Microsoft Windows dependent and the toolkit is purely operating system independent.
As further explanations of the above block diagram:
The "Okino User Interface API" (Ok-UI-API) is an exposed C++ class from the main stand-alone PolyTrans/NuGraf software. It allows system-level plug-ins to make callbacks into the main Microsoft Windows user interface for such tasks as adding menu items, finding program state and so forth. A pointer to this class is provided to the system-level plug-in module to allow it to access these functions. Import/export plug-ins do not have access to these functions.
The "Import/Export Cover Function Helper Library" is a generic set of routines which can be utilized by any plug-in module or the stand-alone NuGraf/PolyTrans software itself. This library provides routines that help bridge the higher level user interface levels of Okino software with the lower level NuGraf 3D Toolkit functions. For example, some routines provide cover functions which makes it much easier to import 3D geometry data to the 3D Toolkit from import plug-ins and system-level plugins. Other routines provide common Microsoft Windows functions to the plug-in modules (such as allowing users to interactively choose a file directory, or to modify dialog box controls), and yet other routines provide a simple framework for import/export plug-ins to show status/feedback/cancel dialog boxes inside the main PolyTrans/NuGraf stand-alone software.
The "System Plug-In Modules" are loaded by the main stand-alone PolyTrans/NuGraf software at start-up and are executed by an end-user through custom menu items added to the main user interface (or via custom Selector Window panels, or plug-in created docking/MDI-document windows), then unloaded when the stand-alone software terminates. Most of the interaction from the system-level plug-in module is between it and the NuGraf 3D Toolkit. The plug-in module has full access to the toolkit, so it can be used for such tasks as creating third-party rendering systems, generic modeling programs, import converters, export converters and much more; import/export plug-ins are similar to system-level plug-ins except that they do not remain in memory between executions and they do not have access to the I/O Cover Function Helper Library. The plug-in may also utilize the functions from the "I/O Cover Function Helper Library" as well as make callbacks via the "Okino User Interface API".
The "3D Model Import converters" are loaded by the main stand-alone PolyTrans/NuGraf software when an end-user selects one from the File/Import or Translate!/Import menus, and automatically unloaded after the import process has completed. The prime job of an import converter is to parse a 3D file and send the 3D scene data to the NuGraf 3D Toolkit via its API. The plug-in may also utilize the functions from the "I/O Cover Function Helper Library"; typically an import converter will use the cover function library to help with the import of mesh and NURBS data, and also use its generic framework to handle the clean-up of an import process should it abort early (one of the more important aspects of the cover function library to an import converter is to create unique handle names for the core toolkit and to keep a list of all data items imported so that they can be deleted if an abort process occurs). An import converter sends status information back to the PolyTrans/NuGraf user interface (as well as receive abort/cancel indication) via a callback mechanism handled by the I/O Cover Function Helper Library.
The "3D Model Export converters" are loaded by the main stand-alone PolyTrans/NuGraf software when an end-user selects one from the File/Export or Translate!/Export menus, and automatically unloaded after the import process has completed. The prime job of an export converter is to query the 3D scene data from the NuGraf 3D Toolkit via its API and export the data to a 3D file. The NuGraf 3D Toolkit has a very well developed export conversion pipeline and "engine", wherein a plug-in export module can set upwards of a dozen or more flags to define what kind of data it can accept and thus not have to worry too much about what type or kind of data it will be expected to handle during the export process. The plug-in may also utilize the functions from the "I/O Cover Function Helper Library"; typically an export converter will use the cover function library to help with the query of mesh and NURBS data. An export converter sends status information back to the PolyTrans/NuGraf user interface (as well as receive abort/cancel indication) via a callback mechanism handled by the I/O Cover Function Helper Library.
Integration Feedback Quotes from Okino Plug-In SDK Developers
The following are a few quotes from developers who have written plug-ins for Okino software:
"I have spearheaded the infamous IRIT modeling toolkit at the Technion,
Israel for the last 15 years. I heard about Okino's open plug-in SDK and
approached Robert Lansdale with whom I have had an ongoing series of
friendly email conversations. Okino created a customized exporter-derived
solution for me, suitable for my task and into which I integrated and
evolved my own custom IRIT exporter. Over a short period of time I was
able to export complete scene graphs, including animation, NURBS
surfaces and NURBS curves. Writing the exporter was straightforward and
the documentation complete. The software and exporter have not crashed,
even after we stretched the exporter to its limit. This is a
professional level product backed up by the friendly and caring software
developers at Okino." - Gershon Elber, Technion University.
"Getting our "Leveller" importer and exporter to integrate with PolyTrans was
nicely straightforward for the most part. The APIs do what need to be done
and Okino's help certainly smoothed over any rough spots arising from my
unfamiliarity. I don't think any developer familiar with 3D systems would
have trouble achieving their data transfer goals. Okino has obviously done a
lot of work making the system amenable to that end and have committed to
keeping it current, so it makes sense to forge relationships with a party
like that. My time, like anyone's, is precious and it helps enormously to
deal with people who are responsive and who know what they're doing." - Ray Gardener, Daylon Graphics.
The NuGraf Developer's 3D Toolkit SDK
Related references on this WEB site about the NuGraf Developer's 3D Toolkit:
The "NuGraf Developer's 3D Toolkit C API" is the all-compassing toolkit and API which forms the core of all Okino software and all technology developed by Okino since January 1988. The toolkit is documented in a separate, fully cross referenced, online help file. You will certainly make use of the toolkit manual at some point while developing an Okino plug-in module. While not used extensively by export converters (since they use cover functions mostly), the NuGraf C API will be utilized mainly for import and system-level plug-in modules.
The toolkit has most of the functionality of a full featured rendering/modeling/animation system, including geometry database support, animation, full rendering, material + texture attributes, color management, bitmap conversion, color space conversion, and much more. The 3D import/export converters and system-level plug-ins themselves are layered on top of the 3D toolkit. The toolkit has expanded over time to include more and more "conversion engines" which allow raw data from most 3D file formats and packages to be imported, stored, rendered, displayed and re-exported with little degradation. Recent additions have seen a spline cross-conversion engine, animation conversion engines, trimmed NURBS support, 13 levels of texture modulation for shaders and more.
The NuGraf Toolkit is used by plug-in developers when they want to gain access to the main 3D scene graph (geometry, instances, lights, camera, materials, textures, animation, etc.), or to a multitude of support routines to aid in 3D software programming (bitmap import/export, bitmap color quantization, math libraries, hierarchy enumeration, geometry processing routines, and much more).
The toolkit has an unusual but powerful and forgiving API based on the 'C' variable-length parameter passing protocol. This is fully described in detail in the "The NuGraf 'C' Interface" section of its respective manual. For example, the following code creates a point light source with an intensity of 0.8 and a shine-from direction of (10, 20, 10):
All parameters are passed by reference and not by value. To read the above code all you really need to know is that all parameters passed across the API interface are pointers with the special cases of Nt_CMDSEP being a "command separator" and Nt_CMDEND being a "command end" token.
Import Converter Plug-Ins
The following diagram shows a very high level structure of how import converter modules relate to the core 3D database, the NuGraf C API (as defined by the "NuGraf Developer's 3D Toolkit"), and the "Import/Export Cover Function Helper Library". As 3D model import converter modules communicate with the core 3D database using the "NuGraf 'C' API", they can potentially import all entity types which are supported by the toolkit API (everything from mesh/NURBS/quadrics, to materials/textures/bitmaps, animation and more).
An import converter is invoked from the Import sub-menu of the main PolyTrans or NuGraf host programs. At the point of execution the importer can open up a disk file, parse it and feed the data into the internal 3d database using NuGraf C API function calls, or calls made to the toolkit indirectly through the Import/Export Cover Function Helper Library. The importer is not limited to populating the database from external files, but rather it can populate the 3d database using pre-defined NuGraf 'C' API script programs as well. Basically the import converter can be considered a general purpose plug-in program which creates and defines 3d content for the core 3d database (for example, an OLE drop target could be defined as an import converter, since it would source 3d data).
The execution of the import converter module, and the handling of its status, feedback and warning/error messages is handled completely by the highest level user-interface code in the NuGraf/PolyTrans stand-alone programs, and/or by the Import/Export Cover Function Helper Library.
Export Converter Plug-Ins
The following diagram shows a very high level structure of how export converter modules relate to the core 3D database, the NuGraf C API (as defined by the "NuGraf Developer's 3D Toolkit"), and the "Import/Export Cover Function Helper Library". As export converter modules communicate with the core 3D database using the "NuGraf 'C' API", they can potentially export all entity types which are supported by the toolkit API (everything from mesh/NURBS/quadrics, to materials/textures/bitmaps, animation and more).
An export converter is invoked after the core 3D database has first been composed with a 3D scene, most often from an import conversion process. The export converter then uses a well defined sequence of events to query all the necessary data from the database, using NuGraf C API function calls, or calls made to the toolkit indirectly through the Import/Export Cover Function Helper Library. The execution of the export converter module, and the handling of its status, feedback and warning/error messages is handled completely by the highest level user-interface code in the NuGraf/PolyTrans stand-alone programs, and/or by the Import/Export Cover Function Helper Library.
System-Level Plug-Ins
System-level plug-in modules are very similar to 3D model import and 3D model export plug-in modules, but more powerful and generic. Import/export converter plug-ins have no persistence between each execution (they are deleted from memory after execution) whereas the system-level plug-ins are loaded just before the main message loop begins and are flushed from memory only when the main application is exiting. In addition, the system-level plug-ins have the added benefit of creating custom recursive menu structures (menus with child menus) to the main "Plug-Ins" menu and they are blessed with the ability to access the Okino UI API which the import/export plug-in modules cannot.
System-level plug-ins can be used for many purposes, some of which include:
Custom plug-in renderers. When the menu item is selected the plug-in would query the entire Okino core database (via the extensive NuGraf Developer's 3D Toolkit API) and then render an image. This is how SiTex Graphics plugged their "TransAIR" module into the main Okino software to interface to their AIR renderer.
Custom plug-in geometry creation tools. The plug-in could be used, for example, to create a 3D font application or a program to model any type of 3D data. Once the data has been modeled it can be dumped into the core Okino database via the NuGraf Developer's 3D Toolkit API.
Custom 3D model import and export converters. Normally a plug-in 3D model import/export converter has a slightly different calling convention such that it will appear in the File/Import or File/Export menus. However, there is no reason why it can't be called from a system-level plug-in module. The main differences is that an import or export plug-in is only loaded when the user selects the converter in the File/Import or File/Export menu (and unloaded directly afterwards) whereas a system-level plug-in module remains fully loaded during the entire duration of the main PolyTrans/NuGraf software's execution time.
Custom 2D bitmap image or video-frame "file import server" to the core Okino toolkit. This is a well developed API and method whereby system-level plug-in modules can add new image or single-frame-video file format support to the overall program capabilities.
Generic tools such as bitmap editors (such as was done for the Okino "Multimedia 3D Viewer and Editor") or file viewers.
Or, in general, any tool which can utilize the wide array of functionality provided by Okino's NuGraf Developer's 3D Toolkit API. The user interface of PolyTrans & NuGraf sits on top of this toolkit for all geometry, database, color management, hierarchy and .bdf file control. This same level of functionality is available to any system-level plug-in developer.
A system-level plug-in module can also access a wide range of user interface elements (explained in the next section below), exposed by the main Okino software, such as:
Adding custom menu items throughout the user interface,
Adding and controlling the docking window mechanism,
Adding custom .NET-style docking toolbars,
Adding managed filename display,
Adding custom panels with custom "roll up" dialog boxes to the "Selector Window",
And more!
User Interface API
The "Okino User Interface API" (Ok-UI-API) is an exposed class from the main PolyTrans/NuGraf stand-alone software that can be accessed by any system-level plug-in module. The member functions allow access to various aspects of the Microsoft Windows user interface of the stand-alone PolyTrans/NuGraf software packages, such as:
Determining UI state, redrawing windows, changing program state,
Adding custom menu items throughout the user interface,
Adding and controlling the docking window mechanism,
Adding custom panels with custom "roll up" dialog boxes to the "Selector Window",
Emulating a Win32 hMenu windows menu using a toolbar, which is needed when plug-ins need to place a menu on a child window (or any window which uses the docking/document window forms),
The Okino Import/Export Cover Function "Helper" Library
The Import/Export Helper Library is a library of common routines which are often used in many Okino import/export/system-level plug-in modules, as well as in its main stand-alone software. The library is contained in the Okino vc4_imp.dll file.
This library includes such functionality as routines to simplify import of meshes/NURBS/splines to the core NuGraf Toolkit (ie: 'cover functions'), extensive cover functions to query all major entity types from the core NuGraf Toolkit and store the parameters in easily accessible local data structures (for export converter development), Microsoft Windows cover functions (for modifying dialog boxes, finding directory paths, etc.), communication routines to allow plug-in modules to exchange status data with the main PolyTrans/NuGraf user interface (the status dialog boxes), proxy routines to handle status update displays for import and export converter modules, routines to circumvent namespace collisions, and much more.
The Evolution Of the Okino APIs and SDKs
Okino Computer Graphics' software was started in 1988 with a company mandate to develop advanced 3D rendering, data conversion and animation technology which would be accessible via 'C'-based developer APIs and then later as higher-level Windows/IRIX-based user interfaces for consumer usage.
Okino's developers have focused mainly on 'algorithm development' that lead to the creation of useful 3D software tools. At the core of all Okino end-user software tools is the "NuGraf Developer's 3D Toolkit" around which has evolved a wide variety of additional super-set APIs and SDKs.
The evolution of the various SDKs and APIs can be described as such:
From 1988 onwards Okino Computer Graphics has developed an extensive 3D Computer Graphics API encapsulated in a C interface, collectively known and sold since 1991 as the "NuGraf Developer's 3D Toolkit". This API was developed to form a clean and easily maintained C-callable API interface to the core Okino software technology assets and algorithms. The initial 700 page API manual in 1991 covered 3D photo-realistic rendering, 3D primitive generation and data transferal, color image loading/saving/conversion/quantization, a 2D bitmap import/export library, database saving/loading (Okino native .bdf files) and database update/query/retrieval services.
Also starting in 1988 Okino began developing import converters for its NuGraf software, as a means to import data from third party modeling software to be used as content for scenes to be rendered. Since the end result was to 'Load and Render' such imported 3D data with little change or tweaking necessary, emphasis has always been placed on importing complete scene data from a 3D file format, including indexed polygon meshes with full attributes (vertex normals, vertex colors, vertex uv texture coordinates and vertex UV tangents), trimmed NURBS, hierarchy, lights, cameras, high quality materials (and their numerous associated parameters), layered textures, 2D bitmap textures, texture projections and much more.
In 1993 this toolkit was used to develop Okino's first Microsoft Windows based product, NuGraf. This product formed a complete user interface to the core NuGraf Toolkit software, as well as expanded on its core functionality.
In 1995 Okino derived the PolyTrans product from the main NuGraf software, a derivation that does not include some of the more advanced rendering and data manipulation functions. PolyTrans was the first major 3D file format converter on the market in 1995/1996 to include full scene conversion, not just base level geometry conversion. Having been developed for 7 years prior as a means to import complete scenes into NuGraf for hands-free rendering, it was an ideal product to convert between popular 3D file formats with 'Load and Render' results.
By 1997 PolyTrans had become a popular staple tool in 3D content development, game development, multi-media and other 3D industry markets while NuGraf focused on the CAD rendering, visualization and data conversion markets. By 1998 and 1999 PolyTrans and NuGraf were being used by every major well known company around the world, for tasks ranging from 3D content development, to data conversion, to rendering and visualization.
R&D has always been a primary directive of the programming staff at Okino. Most of our time is spent developing "conversion engines" to be used as the connecting "glue" between the import and export converter modules. These "engines" clone the best functionality of the 3D programs which PolyTrans is to convert data between. Once an engine is fully written and tested, it can be used to import raw native data from a source 3D package; the Okino philosophy to data translation is that data should ideally be imported and stored in near-native format, then changed/modified/manipulated during the export conversion phase. For example, in 1997 a TCB/Quaternion animation "engine" was developed for PolyTrans which would allow animation data from Lightwave and 3D Studio r4 to be imported, played back, edited and exported with high fidelity; it used the same mathematics, algorithms and even "quirks" to simulate how Lightwave and 3D Studio performed their animation. Likewise in 1999 a Bezier/Euler animation system was fully implemented which would allow PolyTrans to handle native animation data from such programs as 3D Studio MAX, SoftImage and Maya; the core animation engine was also refined over time to cross-convert Bezier animation to/from TCB, and quaternion-based rotation animation to/from Euler-based rotation animation. A selection of other internal PolyTrans "engines" include: an exporter pipeline which hands off clean and guaranteed mesh/NURBS objects to an export converter (under parameter control of the exporter module), trimmed NURBS cleanser/database/tessellator, indexed polygon mesh primitive for robust import/optimization/export of mesh based data, bitmap load/save/manipulation system, database engine for complete control and maintenance of all scene content, and scanline and ray tracing renderers (NuGraf) capable of rendering the largest and most complex datasets of machines with minimal memory, to name a few.
In 1997 and 1999 Okino released its first custom designed native plug-in versions of PolyTrans for Discreet's 3ds max product (PolyTrans-for-MAX) and Alias's Maya animation product (PolyTrans-for-Maya). The third generation of PolyTrans-for-MAX (a mirror twin to the second generation PolyTrans-for-Maya) was released in 2003 which included the new Okino 'Arctic' toolkit for refined skeleton, skinning and animation conversion. This was made entirely possible by having the Okino core converter technology structured as independent DLL modules from their inception in 1988. These are highly evolved native plug-in converter solutions in which the core Okino scene graph (via the NuGraf Developer's 3D Toolkit API) talks directly with the 3DS MAX API and the Maya API, thus bypassing any form of intermediate data files that could lead to further lossy data conversion.
In 2001 Okino made it possible for third party software developers to create custom import and export plug-in modules for the PolyTrans and NuGraf products. Plug-ins are written using a sub-set of the NuGraf Developer's 3D Toolkit C API functionality. By relying on the powerful internal conversion engines, developers will find that writing reliable, robust and full featured export converters to be fairly straightforward with good results. Likewise, while harder to implement, an import converter can access a wide range of API function calls to make importing data reliable and straightforward.
In 2002 Okino released the "System Level Plug-In" mechanism whereby any developer could write generic plug-in modules for PolyTrans or NuGraf that hooked into any menu of its user interface. These plug-ins, as described in this online help manual, can be used to create such applications as third party plug-in renderers, modeling systems, font creation programs, import converters, export converters, etc. These plug-ins access the core database using the NuGraf 3D Toolkit API and the main program's user interface using the Okino-UI-API.
In early 2003 Okino released a complete replacement of the PolyTrans/NuGraf user interface. The new architecture is based on a core "file format handler" which knows "all" about every type of file format and viewer, a docking window user interface (with tabbed MDI documents or docking/expanded .NET style windows), custom programmable docking toolbars, plug-in panels for the "Selector Window" and a roll-up window handler.
Okino's prime development philosophy since 1988 has always been to be a primary 3D technology and problem solving developer. This technology is encapsulated and exposed in most cases by the NuGraf 3D Toolkit C API, and in more recent years as other higher level API interfaces. After more than a decade and a half of internal development and stabilization Okino is happy to expose all of these interfaces and technologies to third party developers for their continued uses.
This section is dedicated to third party software developers who wish to write plug-in modules for Okino's NuGraf and PolyTrans software packages (import/export modules will also be usable within the special native versions of PolyTrans such as 
Overview of the Various Plug-In Types and APIs
