PolyphasePluginAPI.h

Go to the documentation of this file.

#pragma once
 
#include <stdint.h>
 
// Platform-specific export/import macros.
// Legacy scaffolds ship with OCTAVE_PLUGIN_EXPORT defined (the pre-rename alias);
// accept either name here so those projects select dllexport correctly. Without this,
// the plugin entry point is treated as dllimport and its definition hits C2491.
#if defined(OCTAVE_PLUGIN_EXPORT) && !defined(POLYPHASE_PLUGIN_EXPORT)
    #define POLYPHASE_PLUGIN_EXPORT
#endif
 
#ifdef _WIN32
    #ifdef POLYPHASE_PLUGIN_EXPORT
        #define POLYPHASE_PLUGIN_API __declspec(dllexport)
    #else
        #define POLYPHASE_PLUGIN_API __declspec(dllimport)
    #endif
#else
    #define POLYPHASE_PLUGIN_API __attribute__((visibility("default")))
#endif
 
// Plugin API version - increment when breaking changes are made
// v4: added EditorUIHooks::RegisterBuildTarget / UnregisterBuildTarget
//     (ABI-additive; old plugins still load and just don't see the new ptrs)
// v5: added EditorUIHooks::Viewport_RaycastUnderMouse / Viewport_GetMouseState
//     (ABI-additive; old plugins still load and just don't see the new ptrs)
// v6: added PolyphaseEngineAPI::EditorAction_Push / _BeginGroup / _EndGroup
//     (ABI-additive; lets native addons push undo-able actions into the
//     editor's ActionManager. Old plugins still load and just don't see the
//     new ptrs.)
// v7: added EditorUIHooks::ShowOpenFileDialog / ShowSaveFileDialog /
//     ShowSelectFolderDialog (thin wrappers over SYS_*Dialog) and
//     RegisterFileDropHandler / UnregisterFileDropHandler (plugin-side
//     OS file-drop subscription, dispatched alongside the built-in
//     FileDropImportModal). All ABI-additive — appended to the END of
//     the struct. Old plugins still load; new plugins null-check the
//     function pointers before calling for forward/backward compat.
// v8: added EditorUIHooks::Viewport_GetMouseWorldRay (mouse → world
//     origin/dir for plugin transform gizmos, arbitrary plane
//     intersections, etc) and Viewport_WorldToScreen (project a
//     world-space point into the editor viewport's window-space
//     pixels, for overlaying ImGui labels on top of scene objects).
//     Both ABI-additive at the end of EditorUIHooks.
// v9: added EditorUIHooks::EditorImage_Load / EditorImage_GetSize /
//     EditorImage_Invalidate — an engine-owned, path-keyed image → ImGui
//     texture cache. Lets addons show thumbnails without linking class
//     Image / DestroyQueue / GetDestroyQueue / DeviceWaitIdle, none of
//     which are exported from Polyphase.lib. Also annotated
//     GFX_GetVulkanAddonHandles with POLYPHASE_API so addons that drive
//     their own Vulkan passes can actually link it (declaration-only
//     change; no ABI impact). ABI-additive at the end of EditorUIHooks.
#define POLYPHASE_PLUGIN_API_VERSION 9
 
// Forward declarations
struct PolyphaseEngineAPI;
struct EditorUIHooks;
struct lua_State;
 
struct PolyphasePluginDesc
{
    // Plugin metadata
    uint32_t apiVersion;        // Must match POLYPHASE_PLUGIN_API_VERSION
    const char* pluginName;     // Human-readable plugin name
    const char* pluginVersion;  // Plugin version string (e.g., "1.0.0")
 
    // Lifecycle callbacks
    int (*OnLoad)(PolyphaseEngineAPI* api);    // Called when plugin is loaded, return 0 on success
    void (*OnUnload)();                         // Called before plugin is unloaded
 
    // Tick callbacks (set to nullptr if not needed)
    void (*Tick)(float deltaTime);           // Called during gameplay (PIE or built game)
    void (*TickEditor)(float deltaTime);     // Called in editor regardless of play state (editor builds only)
 
    // Registration callbacks (called after OnLoad)
    void (*RegisterTypes)(void* nodeFactory);           // Register custom node types
    void (*RegisterScriptFuncs)(struct lua_State* L);   // Register Lua bindings
 
    // Editor UI extension (editor builds only, set to nullptr for game-only plugins)
    void (*RegisterEditorUI)(EditorUIHooks* hooks, uint64_t hookId);
 
    void (*OnEditorPreInit)();
 
    void (*OnEditorReady)();
};
 
typedef int (*PolyphasePlugin_GetDescFunc)(PolyphasePluginDesc* outDesc);
 
// Macro for declaring the plugin entry point
#define POLYPHASE_PLUGIN_ENTRY() \
    extern "C" POLYPHASE_PLUGIN_API int PolyphasePlugin_GetDesc(PolyphasePluginDesc* outDesc)
 
// Backwards-compatibility aliases (deprecated, will be removed in a future version)
#ifndef POLYPHASE_NO_LEGACY_MACROS
    #define OCTAVE_PLUGIN_API          POLYPHASE_PLUGIN_API
    #ifndef OCTAVE_PLUGIN_EXPORT
        #define OCTAVE_PLUGIN_EXPORT   POLYPHASE_PLUGIN_EXPORT
    #endif
    #define OCTAVE_PLUGIN_API_VERSION  POLYPHASE_PLUGIN_API_VERSION
    #define OCTAVE_PLUGIN_ENTRY        POLYPHASE_PLUGIN_ENTRY
    #define OctavePluginDesc           PolyphasePluginDesc
    #define OctavePlugin_GetDescFunc   PolyphasePlugin_GetDescFunc
    #define OctavePlugin_GetDesc       PolyphasePlugin_GetDesc
    #define OctaveEngineAPI            PolyphaseEngineAPI
#endif