Rendering internals

This page explains how Live rendering is implemented, and what a developer has to provide so that a new component, shape or handle type can be drawn and kept up to date. The user-facing functions are described in the Basics section.

Live rendering dispatch

The diagram shows which live_render! method draws a thing and which handle it returns. BMO provides render!(ax, obj) and render!(ax, shape) as defaults, which a component or shape replaces with an own method to be drawn differently:

Updating a handle

The diagram shows what update_render! does for each handle type:

Render handle protocol

Every handle returned by live_render! is a BeamletOptics.AbstractRenderHandle. Packages built on BeamletOptics, e.g. BeamletOpticsGUI, use the handles through a protocol instead of the concrete handle types of the Makie extension. There are three abstract handle types: BeamletOptics.AbstractObjectRenderHandle for a component, BeamletOptics.AbstractSystemRenderHandle for a system and BeamletOptics.AbstractBeamRenderHandle for a ray, beam or beam group. They share the accessors below.

BeamletOptics.rendered Function

rendered(h::AbstractRenderHandle)

The object, system or beam that the render handle h shows, see AbstractRenderHandle.

source

BeamletOptics.render_plots Function

render_plots(h::AbstractRenderHandle) -> AbstractVector

The plots of the render handle h; of a system handle, the plots of all its object handles. The plots of an object handle may be replaced by update_render!, hence do not keep them.

source

A system handle groups the handles of its objects. It can be searched and changed at runtime:

AbstractTrees.children Method

AbstractTrees.children(h::AbstractSystemRenderHandle) -> AbstractVector{<:AbstractObjectRenderHandle}

The object handles of the system handle h, one per rendered object (the objects of groups, not the groups). Change them via push! and delete! of h, not via the returned vector.

source

BeamletOptics.render_parent Function

render_parent(h::AbstractSystemRenderHandle, obj)

The object group of the system of h that holds obj (an object or a group), or nothing if obj is at the top level or not in h. The handle returned by live_render!(ax, system) looks the group up when it is called, hence it follows push! and delete! of an ObjectGroup.

source

Base.push! Method

push!(h::AbstractSystemRenderHandle, oh::AbstractObjectRenderHandle) -> h

Adds the object handle oh at the top level of the system handle h, e.g. of an object added to the scene after live_render!, such that update_render! and pick_object of h include it.

source

Base.delete! Method

delete!(h::AbstractSystemRenderHandle, oh::AbstractObjectRenderHandle) -> h

Removes the object handle oh from the system handle h. Its plots stay in the axis, delete them via remove_render!(oh).

source

update_render!, remove_render! and pick_object work on any system handle through these accessors, so a handle type of your own only needs to implement them.

The diagram shows which accessors and hooks the methods of a system handle call, and where they pass on to the object handles:

pick_object uses pickable_plots; the colors of the material classes of the active look are available via look_colors:

BeamletOptics.pickable_plots Function

pickable_plots(x, plots) -> AbstractVector

The plots among the plots of x that select x in pick_object, by default all. Add a method for the type of x to exclude plots, e.g. the outline of a marker, whose clicks should reach what lies behind it.

source

BeamletOptics.look_colors Function

look_colors() -> Dict{Symbol, RGBf}

The colors of the material classes (:refractive, :reflective, :coating, :polarizer, :detector, :mechanics, :interface) of the active look, see set_render_look, e.g. to recolor the rendered objects of a class for a dark background.

If no suitable backend is loaded, a MissingBackendError will be thrown.

source