What is a descriptor

Descriptors tell react how to render native elements.

What is an element?

An element is an object that is sent to react to be rendered.

For example, for React-DOM, these are all native elements:

• <h1 />
• <div />
• <span />

And these are component elements:

• <MyClass />
• <SignupForm />

Where

class MyClass extends React.Component{
  render() {
    return <div>I'm a component!</div>;
  }
}

How do descriptors work?

They can:

• create instances
• set properties
• mount into containers
• append children

Example

ReactThreeRenderer.render(
  <object3D position = {new Vector3(1,2,3)} />,
  container);

This instructs ReactThreeRenderer to do these:

• find the object3D descriptor
• instruct it to:
  • create an instance of object3D
  • set its position property to new Vector3(1,2,3)
  • mount it into the container object.

(Actually in the background ReactThreeRenderer talks to a "reconciler" but more info about that to be found [here](TODO: find a good link to describe reconcilers))

How does ReactThreeRenderer find descriptors?

Currently, a bit of magic:

• it looks in the src/core/hostDescriptors/descriptors directory, for all *.ts files.
• for each *.ts file, it extracts the filename,
  • e.g. meshBasicMaterial.ts -> meshBasicMaterial.
• this filename is used to help ReactThreeRenderer find that descriptor.
• so when it looks for meshBasicMaterial it will use whatever is exported by meshBasicMaterial.ts.

Implementation for ReactThreeRenderer

Creating instances

Similar to document.createElement(elementType)

Receives initial properties and creates a copy of the requested type. This copy is called the host instance.

For example, an object3D descriptor will create an Object3D object.

Setting properties

Similar to setting DOM attributes

myDiv.id = "newID"

Handles modifications for each property of the element:

<object3D
  name="test-name"
  position={new Vector3()}
/>

The name and position are the properties.

If the name property changes, how should this be reflected in the host instance?

For object3D, it would simply do instance.name = newValue.

Mounting into containers

Similar to appending children for DOM

Places elements into containers that are passed through the render function.

For example:

// preparation:
const container = new Object3D();
 
// this:
ReactThreeRenderer.render(<object3D name="myObject" />, container);
 
// would do:
container.add(myObject);

Parents and children

Handles the nesting of elements.

For example:

// preparation:
const container = new Object3D();
 
// this:
ReactThreeRenderer.render(<object3D name="parentObject" >
  <object3D name="childObject" />
</object3D>, container);
 
// would do:
parentObject.add(childObject);
// parent's child is now "childObject"
// child's parent is now "parentObject"

Special descriptors

Wrappers

A lot of magic. TODO.

Can you name them better?

[help needed]