VLink  2.3.0
A high-performance communication middleware
convert_plugin_interface.h File Reference

Plugin contract for converting VLink payloads to visualisation backend formats. More...

#include <cstdint>
#include <string>
#include "../base/bytes.h"
#include "../base/plugin.h"
#include "../impl/types.h"
Include dependency graph for convert_plugin_interface.h:

Go to the source code of this file.

Classes

class  vlink::ConvertPluginInterface
 Abstract plugin base translating between VLink payloads and visualisation backends. More...
 
struct  vlink::ConvertPluginInterface::SchemaInfo
 Backend channel schema metadata returned by get_schema(). More...
 
struct  vlink::ConvertPluginInterface::FrontendChannel
 Frontend-advertised channel description used by inbound conversion hooks. More...
 
struct  vlink::ConvertPluginInterface::PublishInfo
 VLink publish destination resolved from an inbound frontend channel. More...
 

Namespaces

 

Detailed Description

Plugin contract for converting VLink payloads to visualisation backend formats.

ConvertPluginInterface lets users supply custom encoders that translate raw VLink messages – in any serialisation – into the payload format expected by a particular webviz frontend. The plugin is loaded as a shared library via the VLink Plugin framework and has no third-party dependencies of its own: it consumes Bytes and emits Bytes, so consumers may implement it without linking Protobuf, FlatBuffers, the Rerun SDK or any JSON library.

Conversion pipeline:

*                          can_convert(ser, target)?
*   VLink Bytes  ----->  +-----------------------+
*                        |  ConvertPluginInterface |  --get_schema(ser, target, info)--> channel registration
*                        +-----------------------+
*                                 |
*                                 v convert(ser, raw, target, payload)
*                              backend Bytes  --->  Foxglove / Rerun frontend
* 

Supported source/target combinations and the meaning of each output field:

Target Wire payload SchemaInfo::type_name meaning
kFoxglove FlatBuffer / Protobuf binary bytes Foxglove schema name
kRerun UTF-8 JSON describing components Rerun archetype name
Rerun JSON payload format
Plugins targeting Rerun emit a UTF-8 JSON object whose fields match the Rerun archetype in the linked SDK. Byte arrays accept a JSON array or a {"base64":"..."} object.
// Points3D
{ "positions": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
"colors": [[255, 0, 0, 255], [0, 255, 0, 255]],
"radii": [0.1, 0.2] }
// EncodedImage (binary payload base64-encoded)
{ "media_type": "image/jpeg",
"blob": {"base64": "<base64 image bytes>"} }
// GeoPoints
{ "positions": [[37.7749, -122.4194], [37.7750, -122.4195]] }
// TextLog
{ "text": "Hello world", "level": "INFO" }
// Scalars
{ "scalars": [3.14] }
// Transform3D
{ "translation": [1.0, 2.0, 3.0],
"quaternion": [0.0, 0.0, 0.0, 1.0] }
// Boxes3D
{ "half_sizes": [[1.0, 2.0, 3.0]],
"centers": [[0.0, 0.0, 0.0]],
"quaternions": [[0.0, 0.0, 0.0, 1.0]],
"colors": [[255, 0, 0, 255]],
"labels": ["box1"] }
// Pinhole
{ "image_from_camera": [fx, 0, 0, 0, fy, 0, cx, cy, 1],
"resolution": [1920, 1080] }

Fields and component layouts come from the linked SDK: vectors are arrays, matrices are flat column-major arrays, structs are objects, and tagged unions are single-key objects such as {"F32":[1.0,2.0]}. Enum strings use SDK names. Image components use format and buffer; Tensor uses {"data":{"shape":[2],"buffer":{"F32":[1.0,2.0]}}}. Binary numeric lists use little-endian values of the declared component type. Integer components reject fractions and overflow; floating components retain NaN and infinity when the source representation supports them. Missing components are omitted. Empty component batches clear their values; an empty Blob array is one empty Blob. RecordingInfo is logged statically at the SDK recording-properties path. Field mappings use this same writer.

Plugin lifecycle:

  1. init() runs once after dynamic load, with an opaque configuration string.
  2. can_convert() is queried per discovered VLink serialisation type, per target.
  3. get_schema() registers the channel and refreshes dynamic output schemas.
  4. convert() runs for every incoming payload on accepted types.
  5. Optional reverse hooks (can_publish(), get_publish(), convert_publish()) handle inbound frontend command/control flows.
  6. The destructor runs when the host unloads the plugin.
Example
class MyConvertPlugin : public vlink::ConvertPluginInterface {
VLINK_PLUGIN_REGISTER(ConvertPluginInterface)
public:
bool init(const std::string& config) override {
(void)config;
return true;
}
bool can_convert(const std::string& ser_type, Target target) override {
return ser_type == "my_pkg.MyMessage";
}
bool get_schema(const std::string& ser_type, Target target,
SchemaInfo& schema_info) override {
if (target == Target::kFoxglove) {
schema_info.type_name = "foxglove.LocationFix";
schema_info.encoding = "flatbuffers";
schema_info.schema_encoding = "flatbuffers";
// schema_info.schema_data = compiled BFBS bytes
} else {
schema_info.type_name = "GeoPoints";
schema_info.encoding = "json";
}
return true;
}
bool convert(const std::string& ser_type, const vlink::Bytes& raw,
Target target, vlink::Bytes& payload) override {
if (target == Target::kRerun) {
std::string json = R"({"positions":[[37.77,-122.41]]})";
payload = vlink::Bytes::deep_copy(json.data(), json.size());
}
return true;
}
};
VLINK_PLUGIN_DECLARE(MyConvertPlugin, 4, 0)
Plugin contract for converting VLink payloads to visualisation backend formats.
#define VLINK_PLUGIN_DECLARE(ImplementType, VersionMajor, VersionMinor)
Emits the extern "C" construction and destruction entry points exported by a plugin module.
Definition: plugin.h:406
#define VLINK_PLUGIN_REGISTER(InterfaceType)
Declares a plugin's identity from the demangled name of its abstract interface.
Definition: plugin.h:359