Plugin API

You can upload plugins here so that they can be installed through the “Browse online” window. The .zip file containing binaries that you upload must contain the following file: /plugins/PluginName/plugin.dll where PluginName can be anything (though it really should be equal to the ID of your plugin). The .zip file’s content will be extracted directly into the SHADERed’s installation directory which means that you can provide additional .dll libraries, example projects, data files, etc…

To update your plugin, go to your profile page and click on “My plugins”, find the plugin that you want to update and click on the “UPDATE” button. You can change the description, title & upload new .zip files.

Once uploaded/updated, the plugin will be waiting for a review. We do this to ensure quality content.

Every plugin in the database must have unique ID.

Building a plugin

Copy files found in /src/SHADERed/Objects/Plugins to your plugin’s project. PluginData.h file contains some object definitions and enums that SHADERed will use to communicate with the plugin. Plugin.h file contains definitions for IPlugin1, IPlugin2, etc..

Start by creating a class that inherits one of the IPlugin interfaces. This class will be the main part of your plugin. In that class you’ll have to implement all of the functions. Even if you don’t use some Plugin API’s feature you will have to leave the function’s body empty.

You will also have to implement these five functions:

CreatePlugin()
Returns:a pointer to a instance of your class which inherits IPlugin
Return type:IPlugin*
DestroyPlugin(ptr)
Parameters:ptr (IPlugin*) – a pointer to a object that CreatePlugin() returned
GetPluginAPIVersion()
Returns:version of PluginAPI that this plugin uses; this function must return 3
Return type:int
GetPluginVersion()
Returns:version of your plugin; the return value will be used to compare the version of this plugin with the version available in the databse (the one you provide while uploading/updating the plugin) to check if there has been any updates
Return type:int
GetPluginName()
Returns:name of your plugin that will be used everywhere
Return type:const char*

IPlugin1

Features

In this section we will describe all the methods that you can override.

General

Init(isWeb, sedVersion)

This function is called immediately after the plugin has been loaded from the .dll

Parameters:
  • isWeb (bool) – whether or not this plugin is running on the web
  • sedVersion (int) – encoded version of SHADERed (1003006 for v1.3.6, 1004000 for v1.4, etc…)
Returns:

true if initialization completed successfully, false otherwise
Return type:

bool
InitUI(ctx)

Implement this function only when your plugin uses UI. You must use imgui library and also it must match the version that SHADERed uses.

Parameters:ctx (void*) – a pointer to ImGuiContext* object
Update(delta)

This function is called every frame between event handling code and rendering code. This is where you should call ImGui functions if you use it.

Parameters:delta (float) – time elapsed between previous and this frame
Destroy()

Called when plugin is unloaded.

IsRequired()

This function will be called when saving a project file & if this plagin output some data in that project file (.sprj).

Returns:true if this project can’t be opened without this plugin, false otherwise
Return type:bool
IsVersionCompatible(version)

This function is called when loading a project that requires this plugin. It is used to check if the older/newer version of this plugin’s project data is compatible with user’s version of plugin.

Parameters:version (int) – version of the plugin used in the project file
Returns:true if plugins are compatible and project can be loaded, otherwise false
Return type:bool
BeginRender()

This method is called right before the rendering starts.

EndRender()

This method is called right after the rendering ends.

Project

Functions related to project loading/saving.

Project_BeginLoad()

This method is called before project loading starts. It’s only called for plugins that were used in this project.

Project_EndLoad()

This method is called right after project loading ends. It’s only called for plugins that were used in this project.

Project_BeginSave()

This method is called before project saving starts. It’s only called for plugins that were used in this project.

Project_EndSave()

This method is called right after project saving ends. It’s only called for plugins that were used in this project.

Project_HasAdditionalData()

Called when saving to a project file. Used to check if plugin wants to export some addional data to the project file.

Returns:true if this plugin would like to export some extra data to .sprj file, otherwise false
Return type:bool
Project_ExportAdditionalData()

Called if Project_HasAdditionalData() returned true

Returns:a string containing XML data
Return type:const char*
Project_ImportAdditionalData(xml)

Called when loading a project if there is any extra data tied to this plugin in the .sprj file.

Parameters:xml (const_char*) – version of the plugin used in the project file
Project_CopyFilesOnSave(dir)

Called when saving a project but also copying all the files related to it (when “Save As” is used).

Parameters:dir (const_char*) – path to a directory in which the project is being saved

Context

UI methods for adding items to the context menus.

HasContextItems(name)

This method will be called to check if plugin wants to add custom options to one of the context menus.

Parameters:name (const_char*) –

name of the context menu, can be one of these values:

  • ”pipeline” → right click in the “Pipeline” window
  • ”shaderpass_add” → right click on a shader pass item → Add
  • ”pluginitem_add” → right click on a plugin item in the pipeline window → Add
  • ”objects” → right click in the “Objects” window
  • ”editcode” → right click on a plugin item → Edit code
Returns:true if this plugin wants to add its own items to the context menu, false otherwise
Return type:bool
ShowContextItems(name[, owner = nullptr][, extraData = nullptr])

Call ImGui::MenuItem() to add items depending on the given parameter

Parameters:
  • name (const_char*) –

    name of the context menu, can be one of these values:

    • ”pipeline” → right click in the “Pipeline” window
    • ”shaderpass_add” → right click on a shader pass item → Add
    • ”pluginitem_add” → right click on a plugin item in the pipeline window → Add
    • ”objects” → right click in the “Objects” window
    • ”editcode” → right click on a plugin item → Edit code
  • owner (void*) –

    the item that we right clicked on

    • ”shaderpass_add” → pointer to a PipelineItem (PipelineItem*) that we right clicked on
    • ”pluginitem_add” → the item type (const char*) of the plugin PipelineItem that we right clicked on
    • ”editcode” → name of the PipelineItem
  • extraData (void*) –

    additional data supplied

    • ”pluginitem_add” → pointer to PluginItemData structure

System variables

Methods for implementing your own system variables.

SystemVariables_GetNameCount(varType)

Get number of system variables for given variable type.

Parameters:varType (VariableType) – the type of the variable
Returns:number of system variables for given variable type
Return type:int
SystemVariables_GetName(varType, index)

Get the name of the system variable.

Parameters:
  • varType (VariableType) – the type of the variable
  • index (int) – number in range [0, SystemVariables_GetNameCount(varType)-1]
Returns:

name of the system variable at the given index
Return type:

const char*
SystemVariables_HasLastFrame(name, varType)

Does this system variable support last frame value?

Parameters:
  • name (char*) – name of the system variable
  • varType (VariableType) – type of the variable
Returns:

true if the “Use values from last frame” flag can be used on this system variable
Return type:

bool
SystemVariables_UpdateValue(data, name, varType, isLastFrame)

Modify variable’s value (stored in the data parameter)

Parameters:
  • data (char*) – variable’s value (input & output)
  • name (char*) – system variable name
  • varType (VariableType) – variable type
  • isLastFrame (bool) – true if the “Last frame” flag is checked, otherwise false

Function variables

Methods for implementing your own variable functions.

VariableFunctions_GetNameCount(vtype)

Get number of functions for given variable type.

Parameters:vtype (VariableType) – the type of the variable
Returns:number of function variables for given variable type
Return type:int
VariableFunctions_GetName(ed::plugin::VariableType varType, int index)

Get the name of the function.

Parameters:
  • varType (VariableType) – the type of the variable
  • index (int) – number in range [0, VariableFunctions_GetNameCount(varType)-1]
Returns:

name of the function variable at the given index
Return type:

const char*
VariableFunctions_ShowArgumentEdit(fname, args, vtype)

Show the UI for editing function’s arguments

Parameters:
  • fname (char*) – name of the function
  • args (char*) – argument values
  • vtype (VariableType) – the type of the variable
Returns:

– not used –
Return type:

bool
VariableFunctions_UpdateValue(data, args, fname, varType)

Update the value of a variable based on the function and arguments.

Parameters:
  • data (char*) – variable’s value (input & output)
  • fname (char*) – name of the function
  • args (char*) – argument values
  • vtype (VariableType) – the type of the variable
VariableFunctions_GetArgsSize(fname, varType)

Get the size required to store the arguments for this function.

Parameters:
  • fname (char*) – function name
  • varType (VariableType) – the type of the variable
Returns:

number of bytes required to store arguments for this function
Return type:

int
VariableFunctions_InitArguments(args, fname, vtype)

Initialize arguments to default values.

Parameters:
  • args (char*) – output
  • fname (char*) – function name
  • vtype (VariableType) – the type of the variable
VariableFunctions_ExportArguments(fname, vtype, args)

Export arguments in the project file.

Parameters:
  • fname (char*) – function name
  • vtype (VariableType) – the type of the variable
  • args (char*) – argument values
Returns:

XML containing information about argument values
Return type:

const char*
VariableFunctions_ImportArguments(fname, vtype, args, argsString)

Import arguments from the project file.

Parameters:
  • fname (char*) – function name
  • vtype (VariableType) – the type of the variable
  • args (char*) – argument values
  • argsString (const_char*) – XML containing information about argument values

Objects

Methods for handling and implementing custom objects.

Object_HasPreview(type)

Check if the custom object has a preview in the context menu (when user right clicks on the object).

Parameters:type (const_char*) – the type name of the object
Returns:true if the object has preview, false otherwise
Return type:bool
Object_ShowPreview(type, data, id)

Show preview in the context menu.

Parameters:
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by this plugin (“user data”) and passed as an argument in AddObject() function
  • id (uint) – object ID, the one passed as an argument when calling the AddObject()
Object_IsBindable(type)

Can this object be bound as a readonly object to shader and compute passes?

Parameters:type (const_char*) – the type name of the object
Returns:true if the object can be bound as a SRV, false otherwise
Return type:bool
Object_IsBindableUAV(type)

Can this object be bound as a UAV in compute passes?

Parameters:type (const_char*) – the type name of the object
Returns:true if the object can be bound as a UAV, false otherwise
Return type:bool
Object_Remove(name, type, data, id)

Method that handles when user deletes an object.

Parameters:
  • name (const_char*) – name of the object
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by the plugin
  • id (uint) – id of the object
Object_HasExtendedPreview(type)

Check if the custom object has a preview that can be opened in a special window.

Parameters:type (const_char*) – the type name of the object
Returns:true if the object has “extended” preview, false otherwise
Return type:bool
Object_ShowExtendedPreview(type, data, id)

Show preview in a special window.

Parameters:
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by this plugin (“user data”) and passed as an argument in AddObject() function
  • id (uint) – object ID, the one passed as an argument when calling the AddObject()
Object_HasProperties(type)

Can our object be opened in the properties window?

Parameters:type (const_char*) – the type name of the object
Returns:true if the object can be opened in properties window, false otherwise
Return type:bool
Object_ShowProperties(type, data, id)

Show properties UI for this object.

Parameters:
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by this plugin (“user data”) and passed as an argument in AddObject() function
  • id (uint) – object ID, the one passed as an argument when calling the AddObject()
Object_Bind(type, data, id)

Bind your object to a shader (eg: call glActiveTexture, glBindTexture, etc…)

Parameters:
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by this plugin (“user data”) and passed as an argument in AddObject() function
  • id (uint) – object ID, the one passed as an argument when calling the AddObject()
Object_Export(type, data, id)

Export information about your object to a project file

Parameters:
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by this plugin (“user data”) and passed as an argument in AddObject() function
  • id (uint) – object ID, the one passed as an argument when calling the AddObject()
Returns:

XML containing information about the object
Return type:

const char*
Object_Import(name, type, objString)

Parse information about an object from a project file. This function should call AddObject so that SHADERed can actually add the object to object manager.

Parameters:
  • name (const_char*) – the name of the object
  • type (const_char*) – the type name of the object
  • objString (const_char*) – XML containing information about the object
Object_HasContext(type)

Check if this plugin object should have more items in its context menu than the “Preview”, “Properties” & “Delete” buttons.

Parameters:type (const_char*) – the type name of the object
Returns:true if there are additional context menu items, false otherwise
Return type:bool
Object_ShowContext(type, data)

Render the UI for the context menu items.

Parameters:
  • type (const_char*) – the type name of the object
  • data (void*) – the data allocated by this plugin (“user data”) and passed as an argument in AddObject() function

Pipeline items

Methods for handling and implementing custom pipeline items.

PipelineItem_HasProperties(type, data)

Can our pipeline item be opened in the properties window?

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

true if the pipeline item can be opened in the properties window, false otherwise
Return type:

bool
PipelineItem_ShowProperties(type, data)

Show properties UI for this pipeline item.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
PipelineItem_IsPickable(type, data)

Check if the pipeline item can be selected through the preview window using left click.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

true if the pipeline item can be picked, false otherwise
Return type:

bool
PipelineItem_HasShaders(type, data)

Check if the pipeline item has its own shaders.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

true if the pipeline item has its own shaders, false otherwise
Return type:

bool
PipelineItem_OpenInEditor(type, data)

Handle a request to open this plugin’s pipeline item’s shaders in the text editor.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
PipelineItem_CanHaveChild(type, data, itemType)

Check if an item of a certain type can be added as a child to this custom pipeline item.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
  • itemType (PipelineItemType) – type of the child item
PipelineItem_GetInputLayoutSize(type, data)

Get number of input layout entries for this pipeline item. This must be supported if this item can have geometry as children.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

number of input layout entries
Return type:

int
PipelineItem_GetInputLayoutItem(type, data, index, out)

Gets information about input layout item at a certain index.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
  • index (int) – index of a input layout item
  • out (InputLayoutItem&) – parameter in which you should store information about this input layout item
PipelineItem_Remove(itemName, type, data)

Method that handles when user deletes a pipeline item owned by this plugin.

Parameters:
  • itemName (const_char*) – name of the pipeline item
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
PipelineItem_Rename(oldName, newName)

Method that handles when user renames a pipeline item owned by this plugin.

Parameters:
  • oldName (const_char*) – old name of the pipeline item
  • newName (const_char*) – new name of the pipeline item
PipelineItem_AddChild(owner, name, type, data)

Method that handles when user adss a child item to a pipeline item owned by this plugin.

Parameters:
  • owner (const_char*) – name of the pipeline item to which this child item has been added
  • name (const_char*) – name of the pipeline item
  • type (PipelineItemType) – type of the pipeline item
  • data (void*) – pointer to pipeline item’s data
PipelineItem_CanHaveChildren(const char* type, void* data)

Check if an item can have child items.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

true if it can have children, false otherwise
Return type:

bool
PipelineItem_CopyData(type, data)

Handle copying data allocated by this plugin to another item. This is used when user duplicates an item for example.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

pointer to a new object
Return type:

void*
void PipelineItem_Execute(Owner, OwnerType, type, data)

Handle executing/rendering the child item.

Parameters:
  • Owner (void*) – pointer to a PipelineItem of the owner of this plugin’s pipeline item that we are executing
  • OwnerType (PipelineItemType) – the type of the owner
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
PipelineItem_Execute(type, data, children, count)

Execute/Render the pipeline item.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
  • children (void*) – list of child items
  • count (int) – number of child items
PipelineItem_GetWorldMatrix(type, data, pMat)

Get pipeline item’s world matrix. This must be handled if item is pickable.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
  • children (float*) – output - a 4x4 matrix
PipelineItem_Intersect(type, data, rayOrigin, rayDir, hitDist)

Check if a ray (generated when user is picking items) intersects the pipeline item

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
  • rayOrigin (float[3]) – the position where the ray starts
  • rayDir (float[3]) – the direction in which ray is going
  • hitDist (float&) – output - store a distance between ray origin and intersection point if there is any intersection
Returns:

true if ray intersects the pipeline item
Return type:

bool
PipelineItem_GetBoundingBox(type, data, minPos, maxPos)

Get the pipeline item’s bounding box.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
  • minPos (float[3]) – output - the minimum coordinates
  • maxPos (float[3]) – output - the maximum coordinates
PipelineItem_HasContext(const char* type, void* data) = 0;

Check if this plugin pipeline item should have additional items in its context menu.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

true if there are additional context menu items
Return type:

bool
PipelineItem_ShowContext(type, data)

Render the UI for the context menu items.

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
PipelineItem_Export(type, data)

Export information about the pipeline item to a project file

Parameters:
  • type (const_char*) – the type name of the pipeline item
  • data (void*) – the data allocated by this plugin and passed to the AddCustomPipelineItem() function
Returns:

XML containing information about the pipeline item
Return type:

const char*

Rest of the documentation is missing. Feel free to help. Here’s source code for this documentation: GitHub link.