Warning

This is a reference for internal components and not typically useful for third party plugins.

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 ID tracked by the Runtime.

Type: int

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) –

blender_version = None¶

connection_name = None¶

get_plugin(plugin)¶

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

is_connected() → bool¶

Is the bridge currently connected to a host

Returns: bool

is_running() → bool¶

Is the driver actively trying to / is connected

Returns: bool

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

on_connected_to_shared_memory()¶

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 host 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(uid)¶

Remove a RenderEngine instance as a tracked viewport

Parameters: uid (int) – Unique identifier 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)¶

Bases: object

Base class for a Coherence Component.

Warning

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

__init__(obj_name)¶

Parameters: obj_name (str) –

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

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.

property enabled¶

classmethod get_property_group_name() → str¶

Str: Name of the PropertyGroup registered to this component type

property has_mesh¶

property interop¶

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

property material_id: str¶

Unique identifier for the material attached to the object

If there is no bpy_obj or no active material, this returns None.

Type: Union[str, None]

property mesh_id: str¶

Unique identifier for the mesh attached to the object

If the object has modifiers applied - this will be unique for that object. Otherwise - this may be a common mesh name that is instanced between multiple objects in the scene.

Type: Union[str, None]

property mesh_uid¶

Unique identifier for the mesh associated with this object.

If a mesh is instanced between different objects and should only be evaluated once, then return the same UID between objects.

If this returns a non-None value, then on_update_mesh() must be implemented to handle the request for handling mesh data updates when the depsgraph is modified.

Returns: Union[str, None]

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

property object_name: str¶

Name of the associated bpy.types.Object

Type: str

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_mesh(depsgraph)¶

Handle mesh update events from the underlying bpy.types.Object

If the mesh is instanced across multiple objects, only one one of objects will receive this event.

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

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_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

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

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

classmethod unregister_property_group()¶

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(self, context)¶

on_property_change_wrapper(func)¶

Scene (core.scene)¶

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 InteropComponent¶

Bases: _ctypes.Structure

enabled¶: Structure/Union member

material¶: Structure/Union member

mesh¶: Structure/Union member

name¶: Structure/Union member

target¶: Structure/Union member

class InteropComponentMessage¶

Bases: _ctypes.Structure

data¶: Structure/Union member

id¶: Structure/Union member

size¶: Structure/Union member

target¶: 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¶

target¶: Structure/Union member

class InteropMessageHeader¶

Bases: _ctypes.Structure

count¶: Structure/Union member

index¶: Structure/Union member

length¶: 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 RenderTextureData¶

Bases: _ctypes.Structure

frame¶: Structure/Union member

height¶: Structure/Union member

pixels¶: Structure/Union member

viewportId¶: Structure/Union member

width¶: Structure/Union member

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

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_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) –

Render Engine (core.engine)¶

Runtime (core.runtime)¶

Utility (core.utils)¶

Component (core.component)¶

Scene (core.scene)¶

Interop Structures (core.interop)¶

Image (core.image)¶