diff --git a/visionforge-threejs/src/jsMain/kotlin/space/kscience/visionforge/solid/three/ThreePlugin.kt b/visionforge-threejs/src/jsMain/kotlin/space/kscience/visionforge/solid/three/ThreePlugin.kt index 7051f887..f5ee8876 100644 --- a/visionforge-threejs/src/jsMain/kotlin/space/kscience/visionforge/solid/three/ThreePlugin.kt +++ b/visionforge-threejs/src/jsMain/kotlin/space/kscience/visionforge/solid/three/ThreePlugin.kt @@ -10,12 +10,14 @@ import space.kscience.dataforge.names.* import space.kscience.visionforge.* import space.kscience.visionforge.solid.* import space.kscience.visionforge.solid.specifications.Canvas3DOptions -import space.kscience.visionforge.solid.three.set import three.core.Object3D import kotlin.collections.set import kotlin.reflect.KClass import three.objects.Group as ThreeGroup +/** + * A plugin that handles Three Object3D representation of Visions. + */ public class ThreePlugin : AbstractPlugin(), ElementVisionRenderer { override val tag: PluginTag get() = Companion.tag @@ -48,6 +50,13 @@ public class ThreePlugin : AbstractPlugin(), ElementVisionRenderer { as ThreeFactory? } + /** + * Build an Object3D representation of the given [Solid]. + * + * @param vision 3D vision to build a representation of; + * @param observe whether the constructed Object3D should be changed when its + * parent vision changes. + */ public suspend fun buildObject3D(vision: Solid, observe: Boolean = true): Object3D = when (vision) { is ThreeJsVision -> vision.render(this) is SolidReference -> ThreeReferenceFactory.build(this, vision, observe) @@ -125,6 +134,16 @@ public class ThreePlugin : AbstractPlugin(), ElementVisionRenderer { private val canvasCache = HashMap() + /** + * Return a [ThreeCanvas] object attached to the given [Element]. + * If there is no canvas bound, a new canvas object is created + * and returned. + * + * @param element HTML element to which the canvas is + * (or should be if it is created by this call) attached; + * @param options canvas options that are applied to a newly + * created [ThreeCanvas] in case it does not exist. + */ public fun getOrCreateCanvas( element: Element, options: Canvas3DOptions, @@ -142,6 +161,19 @@ public class ThreePlugin : AbstractPlugin(), ElementVisionRenderer { override fun rateVision(vision: Vision): Int = if (vision is Solid) ElementVisionRenderer.DEFAULT_RATING else ElementVisionRenderer.ZERO_RATING + /** + * Render the given [Solid] Vision in a [ThreeCanvas] attached + * to the [element]. Canvas objects are cached, so subsequent calls + * with the same [element] value do not create new canvas objects, + * but they replace existing content, so multiple Visions cannot be + * displayed in a single [ThreeCanvas]. + * + * @param element HTML element [ThreeCanvas] should be + * attached to; + * @param vision Vision to render; + * @param options options that are applied to a canvas + * in case it is not in the cache and should be created. + */ internal fun renderSolid( element: Element, vision: Solid, @@ -165,6 +197,19 @@ public class ThreePlugin : AbstractPlugin(), ElementVisionRenderer { } } +/** + * Render the given [Solid] Vision in a [ThreeCanvas] attached + * to the [element]. Canvas objects are cached, so subsequent calls + * with the same [element] value do not create new canvas objects, + * but they replace existing content, so multiple Visions cannot be + * displayed in a single [ThreeCanvas]. + * + * @param element HTML element [ThreeCanvas] should be + * attached to; + * @param obj Vision to render; + * @param optionsBuilder option builder that is applied to a canvas + * in case it is not in the cache and should be created. + */ public fun ThreePlugin.render( element: HTMLElement, obj: Solid, @@ -207,4 +252,4 @@ internal fun Object3D.findChild(name: Name): Object3D? { name.length == 1 -> this.children.find { it.name == name.tokens.first().toString() } else -> findChild(name.tokens.first().asName())?.findChild(name.cutFirst()) } -} \ No newline at end of file +}