editor_assets.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstddef>
 
// Editor assets a plug-in binary declares: the scripted-UI entry file, its
// theme file, the directories its script may load assets from, and the
// embedded copy of the editor that a shipped image carries.
//
// The selection belongs to the plug-in target, not to the Pulp libraries it
// links. `pulp_add_plugin(... UI_SCRIPT ...)` generates one small source for
// each VST3, CLAP, AU, AAX, Standalone and ControlHost target, and
// `pulp_use_kit_ui()` one for every format target that exists when it runs;
// that source's static initializer calls `register_editor_assets()`. Every
// editor path (ViewBridge in each adapter, the standalone window, the control
// host) then reads the same runtime value, whichever translation unit builds
// the editor.
//
// Two kinds of value live in one record:
//
// - The embedded editor: the script's bytes, the theme beside it, and the
//   asset files beside it, compiled into the image by the same helper. Every
//   build carries these, so a shipped plug-in never depends on a file outside
//   its own bundle, and the developer's directory is not a string in the binary.
// - The on-disk paths: absolute build-machine paths a dev build
//   (`PULP_DEV_BUILD`) also records so a hot-reloading editor can watch the
//   file being edited. A release build records none. The paths are absolute
//   build-machine paths, so `UI_SCRIPT` is not applied to AUv3: an iOS app
//   extension cannot resolve them, and an AUv3 editor ships its script inside
//   the extension bundle instead.
//
// Registration runs at static-init time, so the record is POD: no heap, no
// std::string, no logging. The byte arrays it points at are constant-initialized
// in their own translation units, so the order in which those units initialize
// cannot leave a dangling pointer here.
 
namespace pulp::format {

struct EmbeddedEditorFile {
    const char* name;
    const unsigned char* data;
    std::size_t size;
};
 
struct EditorAssets {
    const char* script_path = nullptr;
    const char* theme_path = nullptr;
    const char* asset_roots = nullptr;

    const char* script_name = nullptr;
    const unsigned char* script = nullptr;
    std::size_t script_size = 0;
    const unsigned char* theme = nullptr;
    std::size_t theme_size = 0;
    const EmbeddedEditorFile* files = nullptr;
    std::size_t file_count = 0;
};

bool declares_editor_assets(const EditorAssets& assets) noexcept;

bool embeds_editor_script(const EditorAssets& assets) noexcept;

void register_editor_assets(const EditorAssets& assets) noexcept;

EditorAssets registered_editor_assets() noexcept;

EditorAssets editor_assets_for(const char* plugin_id) noexcept;

void install_scripted_editor_builder() noexcept;

void reset_editor_assets_for_testing() noexcept;
 
} // namespace pulp::format