Render Engine (core.engine)¶

class CoherenceRenderEngine(*args: Any, **kwargs: Any)¶

Bases: bpy.types.

Blender bpy.types.RenderEngine responsible for syncing a viewport camera state with Coherence and displaying the resulting realtime render coming from Unity.

__del__()¶: Notify the bridge that this viewport is going away

__init__()¶

Called when a new render engine instance is created by Blender.

Note that multiple instances can exist at once, e.g. a viewport and final render

bindcode¶

GLSL texture bind code

Type: int

bl_idname = 'COHERENCE'¶

bl_label = 'Coherence'¶

bl_use_preview = False¶

draw_disconnected_view()¶

draw_unity_view()¶

exclude_panels = {'RENDER_PT_freestyle', 'RENDER_PT_simplify', 'VIEWLAYER_PT_filter', 'VIEWLAYER_PT_layer_passes'}¶

on_changed_visible_ids(visible_ids)¶

Notify the bridge that the visibility list has changed

Parameters: visible_ids (list[int]) –

on_update()¶: Sync the current camera position with Coherence

rebuild_texture(frame, width, height, pixels)¶

render(depsgraph)¶

Handle final render (F12) and material preview window renders

Parameters: depsgraph (bpy.types.Depsgraph) –

update_render_texture()¶

update_viewport_camera(context)¶

Update the current InteropCamera instance from the render thread context

Parameters: context (bpy.context) – Render thread context

view_draw(context, depsgraph)¶

Called when Blender redraws the 3D viewport

Parameters

context (bpy.context) – SceneView3D area context
depsgraph (bpy.types.Depsgraph) –

view_update(context, depsgraph)¶

Called when a scene or 3D viewport changes

Parameters

context (bpy.context) – SceneView3D area context
depsgraph (bpy.types.Depsgraph) –

viewport_id¶

Unique viewport entity ID tracked by the Runtime.

Type: c_ulonglong

Runtime (core.runtime)¶

class Runtime¶

Bases: object

Runtime bridge between Python and LibCoherence

This contains the main event handlers, pumping messages to and from LibCoherence, plugin and viewport management, etc

add_viewport(render_engine)¶

Add a RenderEngine instance as a tracked viewport

Parameters: render_engine (CoherenceRenderEngine) –

connection_name = None¶

get_plugin(plugin)¶

Parameters: plugin (Type[Plugin]) –
Returns: Union[Plugin, None]

is_connected() → bool¶

Is the tool currently connected to an engine

Returns: bool

is_running() → bool¶

Is the tool actively trying to / is connected to an engine

Returns: bool

on_connected()¶: Notify plugins and viewports that we’ve connected

on_depsgraph_update(scene, depsgraph)¶

Notify plugins on a depsgraph update

Parameters

scene (bpy.types.Scene) –
depsgraph (bpy.types.Depsgraph) –

on_disconnected()¶: Notify plugins and viewports that we’ve disconnected

on_load_pre(*args, **kwargs)¶

Stop Coherence when our Blender file changes.

This is to prevent Coherence from entering an invalid state where synced objects/viewports no longer exist in the Blender sync.

on_message(message)¶

Forward inbound messages to plugins

Parameters: message (InteropMessage) –

on_tick()¶

Timer registered through bpy.app.timers to handle connecting/reconnecting to the engine and processing messages

Returns: Next time to run the timer or None to destroy it
Return type: Union[float, None]

plugins = {}¶

Registered Coherence plugins that listen to events

Type: Plugin

register_plugin(plugin)¶

Parameters: plugin (Type[Plugin]) –

remove_viewport(id)¶

Remove a RenderEngine instance as a tracked viewport

Parameters: id (ctypes.c_ulonglong) – Entity ID for the viewport RenderEngine

running: bool = False¶

True if Coherence is currently running

Type: bool

start()¶: Start trying to connect to the host

stop()¶: Disconnect from the host and notify plugins

tag_redraw_viewports()¶: Tag all active RenderEngines for a redraw

unregister_all_plugins()¶: Unregister all previously registered plugins

unregister_plugin(plugin)¶

Parameters: plugin (Type[Plugin]) –
Raises: KeyError – If the plugin is not registered

viewports = <WeakValueDictionary>¶

Mapping viewport ID -> Render Engine

Type: WeakValueDictionary[int, CoherenceRenderEngine]

Utility (core.utils)¶

class EventObservers¶

Bases: object

Basic observer list for a set of event callbacks

append(callback)¶

dispatch(*event)¶

remove(callback)¶

class PluginMessageHandler¶

Bases: object

Entity that can send and receive InteropPluginMessage

Example

class MyObj(PluginMessageHandler):
    def __init__(self):
        self.add_handler('Foo', self.on_foo)

    def on_foo(self, id: str, size: int, data: c_void_p):
        ...

add_handler(id: str, callback)¶

Add an event handler for when Unity sends a custom message for this object (e.g. through a associated Unity plugin)

Parameters

id (str) – Unique message ID
callback – Callback to execute when receiving the message

remove_all_handlers()¶: Remove all callbacks for inbound messages

remove_handler(id: str, callback)¶

Remove a callback previously added with add_handler()

Parameters

id (str) – Unique message ID
callback – Callback to execute when receiving the message

Raises

KeyError – If the handler was not registered

send_event(id: str, size: int, data)¶

Send an arbitrary block of data to Unity.

Data sent will be associated with this object on the Unity side.

Parameters

id (str) – Unique message ID
size (int) – Size of the payload to send
data (c_void_p) – Payload to send

Returns

non-zero on failure

Return type

int

debug(msg)¶

error(msg, exception=None)¶

get_string_buffer(value: str)¶: Use a cache to reuse C string buffers wherever possible

log(msg)¶

warning(msg)¶

Component (core.component)¶

class BaseComponent(obj_name: str)¶

Bases: object

Base class for a Coherence Component.

Warning

Third party components should extend off of Coherence.api.Component

__init__(obj_name: str)¶

Parameters: obj_name (str) –

add_vertex_data_stream(id: str, size: int, callback)¶

Add a callback to be executed every time vertex data needs to be synced.

Note

Not yet implemented

The callback has the following definition:

def callback(mesh: bpy.types.Mesh) -> Tuple[ctypes.void_p, int]:
    """
    Args:
        mesh (bpy.types.Mesh):      The evaluated mesh instance in the
                                    current Depsgraph.

    Returns:
        Tuple[ctypes.void_p, int]:  Tuple containing a pointer to the start of the
                                    vertex data array and the number of bytes per
                                    element in that array.
    """
    # ... logic here ...

Data returned by the callback must be aligned to loops for the given mesh. That is, your element count must equal len(mesh.loops)

Warning

Instancing is disabled for meshes with custom vertex data streams. Each instance will be evaluated and sent to Unity as a separate meshes.

Warning

The callback is given a temporary mesh that was created after evaluating all Blender modifiers through the active Depsgraph. The number of elements in your array must match the number of loops after the evaluation.

Parameters

id (str) –
size (int) – Number of bytes in the data stream per loop index
callback (callable) – Callable that returns a pointer to the data stream

property bpy_obj¶

Get the Blender object this component is attached onto

Avoid holding onto a reference to this value long term, as it will invalidate out from under you like other StructRNA references.

Type: bpy.types.Object

destroy()¶: Remove this component from the bpy_obj.

draw(layout)¶

Draw the component panel in Blender’s UI

This can be overridden per-component to create a custom panel

Parameters: layout (bpy.types.UILayout) – Parent layout to draw into

property enabled¶

classmethod get_property_group_name() → str¶

Str: Name of the PropertyGroup registered to this component type

property id¶

classmethod is_autobind() → bool¶

Bool: true if a poll method is defined on this component.

Autobind components cannot be added and removed via the Blender UI

classmethod name() → str¶: str: Get common component name

property object_name: str¶

Name of the associated bpy.types.Object

Type: str

on_after_depsgraph_updates(depsgraph)¶

Executed after all depsgraph updates have been processed

Parameters: depsgraph (bpy.types.Depsgraph) – Evaluated dependency graph

on_coherence_connected()¶: Perform any additional work after Coherence establishes a connection

on_coherence_disconnected()¶: Perform any cleanup after Coherence disconnects from the host.

on_coherence_start()¶

Called when Coherence has been started

This will be followed by on_coherence_connected() once a connection can be made.

on_coherence_stop()¶

Called when Coherence is stopped or the plugin is unregistered.

This will be preceded by an on_coherence_disconnected() if previously connected.

on_create()¶: Executes after the component has been created and synced with Coherence.

on_destroy()¶: Executes when the bpy.types.Object has been removed from the scene or this component has been removed from the object.

on_disable()¶: Perform any cleanup that needs to be done when disabling this instance

on_enable()¶: Perform any cleanup that needs to be done when enabling this instance

classmethod on_registered()¶: Perform any setup that needs to be done after loading this plugin

classmethod on_unregistered()¶: Perform any cleanup that needs to be done before unloading this plugin

on_update(depsgraph, update)¶

Handle a depsgraph update for the linked bpy.types.Object

Parameters

depsgraph (bpy.types.Depsgraph) – Evaluated dependency graph
update (bpy.types.DepsgraphUpdate) – Update for the linked object

property property_group¶: Returns: PropertyGroup|None

property property_names: list¶

PropertyGroup property names that can be synced

Type: list[str]

classmethod register_property_group()¶

remove_vertex_data_stream(id: str)¶

Remove a previously registered vertex data stream

Note

Not implemented

Parameters: id (str) –

property scene_obj¶

Get the SceneObject associated with this instance.

Type: SceneObject

classmethod unregister_property_group()¶

update_all_properties()¶: Push all associated PropertyGroup properties to Coherence

update_property(name: str, value)¶

Update a property shared between synced components.

This is typically called as an event handler on Blender prop changes but can be called directly with the caveat that the value may be overridden by the Blender UI.

Parameters

name (str) – Unique property name
value (mixed) – Native property value (bool, int, list, etc)

Raises

TypeError – If the value cannot be converted to a supported property type

class BaseComponentPropertyGroup(*args: Any, **kwargs: Any)¶

Bases: bpy.types.

classmethod register()¶: Register with Blender as a PropertyGroup on the bpy.types.Object

classmethod unregister()¶: Unregister from Blender as a PropertyGroup on the bpy.types.Object

on_property_change(name, prev)¶

Parameters

name (str) – bpy property name
prev (Union[Callable, None]) – Previous

Interop Structures (core.interop)¶

class InteropCamera¶

Bases: _ctypes.Structure

forward¶: Structure/Union member

height¶: Structure/Union member

isPerspective¶: Structure/Union member

lens¶: Structure/Union member

position¶: Structure/Union member

up¶: Structure/Union member

viewDistance¶: Structure/Union member

width¶: Structure/Union member

class InteropColor(r=0, g=0, b=0, a=1)¶

Bases: _ctypes.Structure

a¶: Structure/Union member

b¶: Structure/Union member

g¶: Structure/Union member

r¶: Structure/Union member

class InteropMatrix4x4¶

Bases: _ctypes.Structure

m00¶: Structure/Union member

m01¶: Structure/Union member

m02¶: Structure/Union member

m03¶: Structure/Union member

m10¶: Structure/Union member

m11¶: Structure/Union member

m12¶: Structure/Union member

m13¶: Structure/Union member

m20¶: Structure/Union member

m21¶: Structure/Union member

m22¶: Structure/Union member

m23¶: Structure/Union member

m30¶: Structure/Union member

m31¶: Structure/Union member

m32¶: Structure/Union member

m33¶: Structure/Union member

class InteropMessage¶

Bases: _ctypes.Structure

as_component_message()¶

Reinterpret as InteropComponentMessage

Returns: Union[InteropComponentMessage, None]

data¶: Structure/Union member

header¶: Structure/Union member

property invalid¶

class InteropMessageHeader¶

Bases: _ctypes.Structure

count¶: Structure/Union member

index¶: Structure/Union member

length¶: Structure/Union member

target¶: Structure/Union member

type¶: Structure/Union member

class InteropQuaternion(x, y, z, w)¶

Bases: _ctypes.Structure

w¶: Structure/Union member

x¶: Structure/Union member

y¶: Structure/Union member

z¶: Structure/Union member

class InteropString64¶

Bases: _ctypes.Structure

buffer¶: Structure/Union member

property empty¶

property value: str¶

class InteropTransform¶

Bases: _ctypes.Structure

parent¶: Structure/Union member

position¶: Structure/Union member

rotation¶: Structure/Union member

scale¶: Structure/Union member

class InteropVector2¶

Bases: _ctypes.Structure

x¶: Structure/Union member

y¶: Structure/Union member

class InteropVector3(x, y, z)¶

Bases: _ctypes.Structure

x¶: Structure/Union member

y¶: Structure/Union member

z¶: Structure/Union member

class InteropVector4(x, y, z, w)¶

Bases: _ctypes.Structure

w¶: Structure/Union member

x¶: Structure/Union member

y¶: Structure/Union member

z¶: Structure/Union member

class RenderTextureData¶

Bases: _ctypes.Structure

frame¶: Structure/Union member

height¶: Structure/Union member

id¶: Structure/Union member

pixels¶: Structure/Union member

width¶: Structure/Union member

class ToolState¶

Bases: _ctypes.Structure

name¶: Structure/Union member

version¶: Structure/Union member

blender_state()¶

Get ToolState information for Blender

Returns: ToolState

identity()¶

Get the identity matrix

Returns: InteropMatrix4x4

load_library(path: str)¶

Load LibCoherence and typehint methods

Parameters: path (str) – Location of LibCoherence.dll
Returns: ctypes.CDLL

set_property_by_value_type(component, name: str, value)¶

Calls the appropriate typed setter based on the Python value

Parameters

component (BaseComponent) –
name (str) – Unique property name
value (mixed) – Native property value

Raises

TypeError – If the value cannot be converted to a supported property type

to_interop_int_array(arr)¶

Convert the array of ints to an interop type for C# int[]

Parameters: arr (int[]) –
Returns: ctypes.POINTER(c_int)

to_interop_matrix4x4(mat)¶

Convert the input matrix to an InteropMatrix4x4

Parameters: mat (float[]) – float multi-dimensional array of 4 * 4 items in [-inf, inf]. E.g. ((1.0, 0.0, 0.0, 0.0), (0.0, 1.0, 0.0, 0.0), (0.0, 0.0, 1.0, 0.0), (0.0, 0.0, 0.0, 1.0))
Returns: InteropMatrix4x4

to_interop_property_name(name: str) → str¶

Convert the input name to an interop property name.

Property names are lowercase alphanumeric only.

Parameters: name (str) –
Returns: str

to_interop_quaternion(rot)¶

Convert a Blender Quaternion to an interop type for C#

This automatically converts rotation space to match Unity

Parameters: rot (mathutils.Quaternion) –
Returns: InteropQuaternion

to_interop_transform(obj)¶

Extract transformation (parent, position, euler angles, scale) from an object.

This will also automatically perform conversion from Blender’s RHS Z-up space to Unity’s LHS Y-up.

Parameters: obj (bpy.types.Object) – The object to extract transform from
Returns: InteropTransform

to_interop_vector2(vec)¶

Convert a Blender Vector to an interop type for C#

Parameters: vec (mathutils.Vector) –
Returns: InteropVector2

to_interop_vector3(vec)¶

Convert a Blender Vector to an interop type for C#

Parameters: vec (mathutils.Vector) –
Returns: InteropVector3

update_transform(obj)¶

Send a transform of the given object to Coherence

Parameters: obj (bpy.types.Object) –