RenderPlugIn

PlugIn
public abstract class RenderPlugIn : PlugIn
A Rhino rendering plugin; applies materials, textures, and lights to a scene to produce rendered images.

Constructors

RenderPlugIn

#
protected RenderPlugIn()

Properties

AddToHelpMenu

public virtual bool AddToHelpMenu { get; }
Called by Rhino to determine if the plug-in name should be added to the Rhino Help/Plug-ins menu.
inherited fromPlugIn

Assembly

public Assembly Assembly { get; }
Source assembly for this plug-in.
inherited fromPlugIn

Description

public string Description { get; }
Returns the description of the plug-in, as found in the plug-in's assembly attributes.
inherited fromPlugIn

Id

public Guid Id { get; }
Returns the Guid, or unique Id, of the plug-in.
inherited fromPlugIn

InitialChannelToDisplay

#
protected virtual Guid InitialChannelToDisplay { get; }

LicenseId

public Guid LicenseId { get; }
inherited fromPlugIn

LoadAtStartup

public virtual bool LoadAtStartup { get; }
obsoleteUse LoadTime virtual property instead
inherited fromPlugIn

LoadTime

public virtual PlugInLoadTime LoadTime { get; }
Plug-ins are typically loaded on demand when they are first needed. You can change this behavior to load the plug-in at during different stages in time by overriding this property.
inherited fromPlugIn

LocalPlugInName

protected virtual string LocalPlugInName { get; }
Optionally override this to provide a localized plug-in name
inherited fromPlugIn

Name

public string Name { get; }
Returns the name of the plug-in, as found in the plug-in's assembly attributes.
inherited fromPlugIn

PerferBasicContent

#Since v5.12
public bool PerferBasicContent { get; set; }
Set to true if you would like Rhino to quickly create a basic render content in response to 'Create New' commands. Set to false if you would prefer Rhino to display the render content chooser dialog.

Settings

public PersistentSettings Settings { get; }
Persistent plug-in settings.
inherited fromPlugIn

SettingsDirectory

public string SettingsDirectory { get; }
Get the plug-in's settings directory. This is the directory where the plug-in's persistent settings files are saved. This directory will be located in the user's profile folder. Note, this does not verify the directory exists.
inherited fromPlugIn

SettingsDirectoryAllUsers

public string SettingsDirectoryAllUsers { get; }
Get the plug-in's "all users" settings directory. This directory will be located in the system's program data folder. Note, this does not verify the directory exists.
inherited fromPlugIn

SupportedChannels

#
protected virtual Guid[] SupportedChannels { get; }
Override to communicate that the renderer supports more channels beside the default channels RGBA, Depth, Normal, Albedo. See RenderWindow.StandardChannels. RenderWindow.ChannelId can be used to get the GUIDs for the channels to support

SupportsEditProperties

#
protected virtual bool SupportsEditProperties { get; }
Override this property and return true if your plug-in supports decals and overrides ShowDecalProperties(List<NamedValue>)

Version

public string Version { get; }
Returns the version of the plug-in, as found in the plug-in's assembly attributes.
inherited fromPlugIn

WindowPositionSettings

public PersistentSettings WindowPositionSettings { get; }
inherited fromPlugIn

Methods

AllowChooseContent

#
protected virtual bool AllowChooseContent(RenderContent content)
Default implementation returns true which means the content can be picked from the content browser by the user. Override this method and return false if you don't want to allow a certain content contentType to be picked from the content browser while your render engine is current.
content (RenderContent)A render context.
true if the operation was successful.

AskUserForLicense

protected bool AskUserForLicense(LicenseBuildType productBuildType, bool standAlone, string textMask, object parentWindow, ValidateProductKeyDelegate validateProductKeyDelegate, OnLeaseChangedDelegate onLeaseChangedDelegate)
inherited fromPlugIn
productBuildType (LicenseBuildType)
standAlone (bool)
textMask (string)
parentWindow (object)
validateProductKeyDelegate (ValidateProductKeyDelegate)
onLeaseChangedDelegate (OnLeaseChangedDelegate)

CommandSettings

public PersistentSettings CommandSettings(string name)
inherited fromPlugIn
name (string)

CreateCommands

protected virtual void CreateCommands()
Called right after plug-in is created and is responsible for creating all of the commands in a given plug-in. The base class implementation Constructs an instance of every publicly exported command class in your plug-in's assembly.
inherited fromPlugIn

CreatePreview

#
protected virtual void CreatePreview(CreatePreviewEventArgs args)
Creates the preview bitmap that will appear in the content editor's thumbnail display when previewing materials and environments. If this function is not overridden or the PreviewImage is not set on the arguments, then the internal OpenGL renderer will generate a simulation of the content. This function is called with four different preview quality settings. The first quality level of RealtimeQuick is called on the main thread and needs to be drawn as fast as possible. This function is called with the other three quality settings on a separate thread and are meant for generating progressively refined preview.
args (CreatePreviewEventArgs)Event argument with several preview option state properties.

CreateTexture2dPreview

#
protected virtual void CreateTexture2dPreview(CreateTexture2dPreviewEventArgs args)
Creates the preview bitmap that will appear in the content editor's thumbnail display when previewing textures in 2d (UV) mode. If this function is not overridden or the PreviewImage is not set on the arguments, then the internal OpenGL renderer will generate a simulation.
args (CreateTexture2dPreviewEventArgs)Event argument with several preview option state properties.

CurrentRendererSupportsFeature

#Since v6.1
public static bool CurrentRendererSupportsFeature(RenderFeature feature)
feature (RenderPlugIn.RenderFeature)

CustomChannelName

#
protected virtual string CustomChannelName(Guid id)
Return the localized name of your custom channel.
id (Guid)

DisplayHelp

public virtual bool DisplayHelp(nint windowHandle)
Called by Rhino if AddToHelpMenu is true and menu item associated with this plug-in is selected.
inherited fromPlugIn
windowHandle (nint)Native Window handle of the active Rhino interface.
true = Help displayed successfully, false = Error displaying help

DocumentPropertiesDialogPages

protected virtual void DocumentPropertiesDialogPages(RhinoDoc doc, List<OptionsDialogPage> pages)
Override this function if you want to extend the document properties sections of the options dialog. This function is called whenever the user brings up the Options dialog.
inherited fromPlugIn
doc (RhinoDoc)document that the pages are set up for
pages (List<OptionsDialogPage>)list of pages to add your custom options dialog page(s) to.

EnableAssignMaterialButton

#Since v5.12
public virtual bool EnableAssignMaterialButton()
Called to enable/disable the "Material" button located on the "Material" tab in the Properties and Layer dialog boxes. The default return value is false which will disable the button. If the button is disabled then the OnAssignMaterial function is never called.

EnableCreateMaterialButton

#Since v5.12
public virtual bool EnableCreateMaterialButton()
Called to enable/disable the "New" button located on the "Material" in the Properties and Layer dialog boxes. The default return value is false which will disable the button. If the button is disabled then the OnEditMaterial function is never called.

EnableEditMaterialButton

#Since v5.12
public virtual bool EnableEditMaterialButton(RhinoDoc doc, Material material)
Called to enable/disable the "Edit" button located on the "Material" in the Properties and Layer dialog boxes. The default return value is false which will disable the button. If the button is disabled then the OnEditMaterial function is never called.
doc (RhinoDoc)
material (Material)

GetCommands

public Command[] GetCommands()
All of the commands associated with this plug-in.
inherited fromPlugIn

GetLicense

protected bool GetLicense(LicenseBuildType productBuildType, ValidateProductKeyDelegate validateProductKeyDelegate, OnLeaseChangedDelegate leaseChangedDelegate)
Verifies that there is a valid product license for your plug-in, using the Rhino licensing system. If the plug-in is installed as a standalone node, the locally installed license will be validated. If the plug-in is installed as a network node, a loaner license will be requested by the system's assigned Zoo server. If the Zoo server finds and returns a license, then this license will be validated. If no license is found, then the user will be prompted to provide a license key, which will be validated.
inherited fromPlugIn
productBuildType (LicenseBuildType)The product build contentType required by your plug-in.
validateProductKeyDelegate (ValidateProductKeyDelegate)Since the Rhino licensing system knows nothing about your product license, you will need to validate the product license provided by the Rhino licensing system. This is done by supplying a callback function, or delegate, that can be called to perform the validation.
leaseChangedDelegate (OnLeaseChangedDelegate)Called by the ZooClient when the cloud zoo lease is changed.
true if a valid license was found. false otherwise.

GetLicense

protected bool GetLicense(LicenseCapabilities licenseCapabilities, string textMask, ValidateProductKeyDelegate validateProductKeyDelegate, OnLeaseChangedDelegate leaseChangedDelegate)
Verifies that there is a valid product license for your plug-in, using the Rhino licensing system. If the plug-in is installed as a standalone node, the locally installed license will be validated. If the plug-in is installed as a network node, a loaner license will be requested by the system's assigned Zoo server. If the Zoo server finds and returns a license, then this license will be validated. If no license is found, then the user will be prompted to provide a license key, which will be validated.
inherited fromPlugIn
licenseCapabilities (LicenseCapabilities)In the event that a license was not found, or if the user wants to change the way your plug-in is licenses, then provide what capabilities your license has by using this enumeration flag.
textMask (string)In the event that the user needs to be asked for a license, then you can provide a text mask, which helps the user to distinguish between proper and improper user input of your license code. Note, if you do not want to use a text mask, then pass in a null value for this parameter. For more information on text masks, search MSDN for the System.Windows.Forms.MaskedTextBox class.
validateProductKeyDelegate (ValidateProductKeyDelegate)Since the Rhino licensing system knows nothing about your product license, you will need to validate the product license provided by the Rhino licensing system. This is done by supplying a callback function, or delegate, that can be called to perform the validation.
leaseChangedDelegate (OnLeaseChangedDelegate)Called by the ZooClient when the cloud zoo lease is changed.
true if a valid license was found. false otherwise.

GetLicenseOwner

protected bool GetLicenseOwner(out string registeredOwner, out string registeredOrganization)
Get the customer name and organization used when entering the product license.
inherited fromPlugIn
registeredOwner (out string)
registeredOrganization (out string)

GetPlugInObject

public virtual object GetPlugInObject()
inherited fromPlugIn

GetRenderSettingsSections

#Since v6.17
public List<Guid> GetRenderSettingsSections()
This function returns a list of Guids for the render settings pages that should be displayed.
Return a Id list of the Render settings sections that will be displayed

Icon

public Bitmap Icon(Size size)
Returns the plug-in's icon in bitmap form.
inherited fromPlugIn
size (Size)The desired size in pixels.
The icon if successful, null otherwise.

InitializeDecalProperties

#
protected virtual void InitializeDecalProperties(ref List<NamedValue> properties)
Initialize your custom decal properties here. The input list will be empty - add your default named property values and return.
properties (ref List<NamedValue>)A list of named values that will be stored on the object the input values are the current ones, you should modify the values after the dialog closes.

IsTextureSupported

public virtual bool IsTextureSupported(RenderTexture texture)
Returns true if this renderer can render the texture natively without needing it to be baked into a bitmap, false otherwise. By default, returns false for all textures.
inherited fromPlugIn
texture (RenderTexture)

ObjectPropertiesPages

protected virtual void ObjectPropertiesPages(List<ObjectPropertiesPage> pages)
obsoleteUse ObjectPropertiesPages(ObjectPropertiesPageCollection collection) instead
Override this function is you want to extend the object properties dialog
inherited fromPlugIn
pages (List<ObjectPropertiesPage>)

ObjectPropertiesPages

protected virtual void ObjectPropertiesPages(ObjectPropertiesPageCollection collection)
Override this function is you want to extend the object properties dialog. This method will be called each time a new document is created for each instance of a object properties panel. On Windows there will be a single panel per document but on Mac there may be many properties panel per document.
inherited fromPlugIn
collection (ObjectPropertiesPageCollection)Add custom pages by calling collection.Add

OnAssignMaterial

#Since v5.12
public virtual bool OnAssignMaterial(nint parent, RhinoDoc doc, ref Material material)
This function is called by the Object Properties and Layer Control dialogs when the "Material" button is pressed in the "Render" tab. This is only called if EnableAssignMaterialButton returns true.
parent (nint)
doc (RhinoDoc)
material (ref Material)

OnCreateMaterial

#Since v5.12
public virtual bool OnCreateMaterial(nint parent, RhinoDoc doc, ref Material material)
This function is called by the Object Properties and Layer Control dialogs when the "New" button is pressed in the "Material" tab. This is only called if EnableCreateMaterialButton returns true.
parent (nint)
doc (RhinoDoc)
material (ref Material)

OnEditMaterial

#Since v5.12
public virtual bool OnEditMaterial(nint parent, RhinoDoc doc, ref Material material)
This function is called by the Object Properties and Layer Control dialogs when the "Edit" button is pressed in the "Material" tab. This is only called if EnableEditMaterialButton returns true. A return value of true means the material has been updated.
parent (nint)
doc (RhinoDoc)
material (ref Material)

OnLoad

protected virtual LoadReturnCode OnLoad(ref string errorMessage)
Is called when the plug-in is being loaded.
inherited fromPlugIn
errorMessage (ref string)If a load error is returned and this string is set. This string is the error message that will be reported back to the user.
An appropriate load return code.

The default implementation returns LoadReturnCode.Success.

OnSetCurrent

#
protected virtual void OnSetCurrent(bool current)
This plug-in (has become)/(is no longer) the current render plug-in
current (bool)If true then this plug-in is now the current render plug-in otherwise it is no longer the current render plug-in.

OnShutdown

protected virtual void OnShutdown()
inherited fromPlugIn

OptionsDialogPages

protected virtual void OptionsDialogPages(List<OptionsDialogPage> pages)
Override this function if you want to extend the options dialog. This function is called whenever the user brings up the Options dialog.
inherited fromPlugIn
pages (List<OptionsDialogPage>)list of pages to add your custom options dialog page(s) to.

PreviewRenderType

#
protected virtual RenderPlugIn.PreviewRenderTypes PreviewRenderType()
Tell what kind of preview rendering your renderer supports.
One of PreviewRenderTypes

ReadDocument

protected virtual void ReadDocument(RhinoDoc doc, BinaryArchiveReader archive, FileReadOptions options)
Called whenever a Rhino document is being loaded and plug-in user data was encountered written by a plug-in with this plug-in's GUID.
inherited fromPlugIn
doc (RhinoDoc)A Rhino document that is being loaded.
archive (BinaryArchiveReader)OpenNURBS file archive object Rhino is using to read this file. Use BinaryArchiveReader.Read*() functions to read plug-in data. If any BinaryArchive.Read*() functions throws an exception then archive.ReadErrorOccurve will be true and you should immediately return.
options (FileReadOptions)Describes what is being written.

RegisterCommand

protected bool RegisterCommand(Command command)
inherited fromPlugIn
command (Command)

RegisterCustomRenderSaveFileTypes

#
protected virtual void RegisterCustomRenderSaveFileTypes(CustomRenderSaveFileTypes saveFileTypes)
Override this method to add custom file types to the render window save file dialog.
saveFileTypes (CustomRenderSaveFileTypes)

RegisterRenderPanels

#
protected virtual void RegisterRenderPanels(RenderPanels panels)
Override this method and call RenderPanels.RegisterPanel(PlugIn, RenderPanelType, Type, string, bool, bool) to add custom render UI to the render output window.
panels (RenderPanels)

RegisterRenderTabs

#
protected virtual void RegisterRenderTabs(RenderTabs tabs)
Override this method and call RenderTabs.RegisterTab(PlugIn, Type, Guid, string, Icon) to add custom tabs to the render output window
tabs (RenderTabs)

Render

#
protected abstract Result Render(RhinoDoc doc, RunMode mode, bool fastPreview)
Called by Render and RenderPreview commands if this plug-in is set as the default render engine.
doc (RhinoDoc)A document.
mode (RunMode)A command running mode.
fastPreview (bool)If true, lower quality faster render expected.
If true, then the renderer is required to construct a rapid preview and not the high-quality final result.

RenderContentSerializers

#
protected virtual IEnumerable<RenderContentSerializer> RenderContentSerializers()
Called by Rhino when it is time to register RenderContentSerializer derived classes. Override this method and return an array of an instance of each serialize custom content object you wish to add.
List of RenderContentSerializer objects to register with the Rhino render content browsers.

RenderOptionsDialogPage

#
protected virtual OptionsDialogPage RenderOptionsDialogPage(RhinoDoc doc)
Override this method to replace the render properties page in the Rhino document properties dialog. The default implementation returns null which means just use the default Rhino page.
doc (RhinoDoc)The document properties to edit.
Return null to use the default Rhino page or return a page derived from OptionsDialogPage to replace the default page.

RenderSettingsCustomSections

#Since v6.0
public virtual void RenderSettingsCustomSections(List<ICollapsibleSection> sections)
Override this function to provide custom sections for the render settings panel that are displayed when your plug-in is the current render plug-in.
sections (List<ICollapsibleSection>)Create your sections and return a list of them

RenderSettingsSections

#
protected virtual List<Guid> RenderSettingsSections()
Override this method to provide the UUIDs of all sections that should be displayed in the Render Settings tab when this is the current renderer.The default implementation adds all the RDK's built-in Render Settings sections. These UUIDs start with the prefix uuidRenderSettingsSection'. They can be found in RhRdkUuids.h
Remarks: You should add \e all sections you would want to appear in any context.
Return a Id list of content types to display in content browsers

RenderWindow

#
protected virtual Result RenderWindow(RhinoDoc doc, RunMode modes, bool fastPreview, RhinoView view, Rectangle rect, bool inWindow, bool blowup)
doc (RhinoDoc)
modes (RunMode)
fastPreview (bool)
view (RhinoView)
rect (Rectangle)
inWindow (bool)
blowup (bool)

RenderWindow

#
protected virtual Result RenderWindow(RhinoDoc doc, RunMode modes, bool fastPreview, RhinoView view, Rectangle rect, bool inWindow)
This function is obsolete and only exists for legacy purposes. Do not override this function - prefer overriding the version with the blowup parameter.
doc (RhinoDoc)
modes (RunMode)
fastPreview (bool)
view (RhinoView)
rect (Rectangle)
inWindow (bool)

ResetMessageBoxes

protected virtual void ResetMessageBoxes()
inherited fromPlugIn

ReturnLicense

protected bool ReturnLicense()
Returns, or releases, a product license that was obtained from the Rhino licensing system. Note, most plug-ins do not need to call this as the Rhino licensing system will return all licenses when Rhino shuts down.
inherited fromPlugIn

SaveSettings

public void SaveSettings()
Write settings to disk which will raise a PlugIn.SettingsSaved event.
inherited fromPlugIn

SetLicenseCapabilities

protected void SetLicenseCapabilities(string textMask, LicenseCapabilities capabilities, Guid licenseId)
inherited fromPlugIn
textMask (string)
capabilities (LicenseCapabilities)
licenseId (Guid)

ShouldCallWriteDocument

protected virtual bool ShouldCallWriteDocument(FileWriteOptions options)
Called whenever a Rhino is about to save a .3dm file. If you want to save plug-in document data when a model is saved in a version 5 .3dm file, then you must override this function to return true and you must override WriteDocument().
inherited fromPlugIn
options (FileWriteOptions)The file write options, such as "include preview image" and "include render meshes".
true if the plug-in wants to save document user data in the version 5 .3dm file. The default returns false.

ShowDecalProperties

#
protected virtual bool ShowDecalProperties(ref List<NamedValue> properties)
Override this function to handle showing a modal dialog with your plug-in's custom decal properties. You will be passed the current properties for the object being edited. The defaults will be set in InitializeDecalProperties.
properties (ref List<NamedValue>)A list of named values that will be stored on the object the input values are the current ones, you should modify the values after the dialog closes.
true if the user pressed "OK", otherwise false.

SunCustomSections

#Since v6.0
public virtual void SunCustomSections(List<ICollapsibleSection> sections)
Override this function to provide custom sections for the sun panel that are displayed when your plug-in is the current render plug-in.
sections (List<ICollapsibleSection>)Create your sections and return a list of them

SupportedOutputTypes

#
protected virtual List<FileType> SupportedOutputTypes()
Returns a list of output types which your renderer can write.

The default implementation returns BMP, JPG, PNG, TIF, TGA, HDR, EXR and RIMAGE.

A list of file types.

SupportsFeature

#
protected virtual bool SupportsFeature(RenderFeature feature)
Determines if your renderer supports a specific feature.
feature (RenderPlugIn.RenderFeature)A feature to be controlled.
true if the renderer indeed supports the feature.

UiContentTypes

#
protected virtual List<Guid> UiContentTypes()
Override this method to provide the UUIDs of all content types that should be presented to the user in the types combo box or the[+] button types menu.The default implementation adds only RDK's built-in types. Rhino automatically adds types in the most efficient way to minimize the list length. If you override this method, you may call the base class first to add the built-in types, a separator will be inserted at the end of the standard list followed by your own types. You may omit the base class call and only chosen types yourself, followed by a separator and your own types. A 'More Types...' item is automatically added when needed by Rhino. Specify a separator by adding uuidUiContentType_Separator.
Remarks: You should add \e all types you would want to appear in any context, regardless of their content kind. Rhino ensures that only types that make sense will actually be presented to the user in a given context.
Return a Id list of content types to display in content browsers

WriteDocument

protected virtual void WriteDocument(RhinoDoc doc, BinaryArchiveWriter archive, FileWriteOptions options)
Called when Rhino is saving a .3dm file to allow the plug-in to save document user data.
inherited fromPlugIn
doc (RhinoDoc)The Rhino document instance that is being saved.
archive (BinaryArchiveWriter)OpenNURBS file archive object Rhino is using to write the file. Use BinaryArchiveWriter.Write*() functions to write plug-in data. OR use the ArchivableDictionary If any BinaryArchiveWriter.Write*() functions throw an exception, then archive.WriteErrorOccured will be true and you should immediately return. Setting archive.WriteErrorOccured to true will cause Rhino to stop saving the file.
options (FileWriteOptions)The file write options, such as "include preview image" and "include render meshes".

Events

SettingsSaved

This event is raised when an instance of Rhino has modified the external settings file associated with this plug-in's PlugIn.Settings property.
inherited fromPlugIn