1. What is Scene?

Scene is the Curl® language 3D retained-mode graphics API.

2. How would I create a scene in 3-D?

Creating a scene is as simple as instantiating a Scene object. Of course, the scene will be empty and therefore, not very interesting.
Example:

let my-scene:Scene={Scene}

3. How would I create an object as part of the 3-D scene?

Adding an object to a Scene is accomplished by using the Scene's add-object method (there is also a remove-object method). There are three built-in SceneObjects that can be added to a Scene to model objects: Triangle, Quad, and PolygonSet. You can also create your own customized object by subclassing SceneObject or any of the built in objects. TextSceneObject is another type of SceneObject, and it can be used to display text billboards in 3D. SceneLights are a type of SceneObject tht can be used to illuminate PolygonSets.

Example:

my-scene.add-object red-quad}

4. How do I display my Scene?

The easiest way to display a Scene in a page is to use SceneGraphic. Since SceneGraphic is a Graphic, it participates in page layout like any other Graphic object.

5. How do I move my point of view?

All Scenes have a camera object accessible by the Scene's camera method. Setting various properties of this camera (position, transformation, projection, etc.) will change the way the Scene is rendered. You can also use any of these convenience methods to change the properties of a camera: set-orientation-and-position, pan, dolly, tilt, and roll.

6. How do I use lighting?

There are three types of SceneLights available for Scene lighting: PointLight, DirectionalLight, SpotLight. A PointLight is similar to a light bulb - rays emanating from a single point in space. DirectionalLights model infinitely distant light sources with parallel rays. A SpotLight is similar to flashlight - rays emanating from a point source within a cone.

Like other objects, SceneLights must be added to a Scene to have any effect on a Scene. SceneLights do not paint themselves by default so you will not see the light object but you will see the effect of the lights on other objects. (Currently, only PolygonSet objects can be lit.)

Example:

let color-change:EventHandler =
     {on PointerPressSceneEvent at quad:Quad do
         set quad.fill-pattern = >new-color
     }
   {my-quad.add-event-handler color-change}

7. How do objects respond to "mouse clicks" or "pointer events"?

Since all SceneObjects are EventTargets, in order for SceneObjects to respond to "mouse clicks" or "pointer events" you have to give them EventHandlers. EventHandlers need events to be useful and several 3D events are part of the Scene API (PointerPressSceneEvent, PointerReleaseSceneEvent, etc.) Also, if you use SceneGraphic, the pointer press and release 2D events are translated for you into 3D SceneEvents.

Example:

let color-change:EventHandler =
     {on PointerPressSceneEvent at quad:Quad do
         set quad.fill-pattern = >new-color
     }
   {my-quad.add-event-handler color-change}

8. How would I group things in 3D?

Since SceneGroup is the superclass of Scene, creating and populating a 3D SceneGroup is very similar to creating a Scene. SceneGroups are often created to allow all the SceneGroup's children to be transformed as a single unit; you can use the transformation accessor or any of the convenience methods and accessors (rotate, translate, scale and world-position) for this.

Example:

let spin-group:SceneGroup =
       {SceneGroup
            obj1,
            obj2,
            obj3
        }
    {my-scene.add-object spin-group}
    {spin-group.rotate {Direction3d 0, 0, 1}, 10 degrees}

The following example builds a simple scene consisting of 6 groups of 5 triangles each. Clicking on a triangle changes the triangle's color and spins its group. Also, dragging the mouse changes the camera position and orientation.

{curl 5.0 applet}
{import * from CURL.GRAPHICS.SCENE}
|| A procedure for generating random colors.
{let random:Random = {Random}}

{define-proc {random-color}:Color
    {return
        {Color.from-rgb
            {random.next-float},{random.next-float},{random.next-float}
        }
    }
}

{value
    || The scene that holds all the triangles.
    let scene:Scene =
        {Scene
            camera =
                {Camera
                    position = {Distance3d 0in, -2in, 3in},
                    direction = {Direction3d 1, 1, -1},
                    up-vector = {Direction3d 0, 0, 1},
                    field-of-view = 90degrees,
                    near-clipping-plane = .1in,
                    far-clipping-plane = 50in,
                    projection = Projection.perspective
                }
        }
    || This event handler sets the color of the triangle that is hit
    || to a random color and rotates the triangle's group
    let event-handler:EventHandler =
        {on event:PointerPressSceneEvent at tri:Triangle do
            set tri.fill-pattern = {random-color}
            {tri.parent.rotate {Direction3d 0, 0, 1}, 15degrees}
        }

    || Add the triangles to the scene as a grid.
    {for x:Distance = 0in to 5in step 1in do
        let group:SceneGroup = {SceneGroup}
        let color:Color = {random-color}
        {for y:Distance = -2in to 2in step 1in do
            {group.add-object
                {Triangle
                    {Distance3d 0in, y, 0in},
                    {Distance3d 0.5in, y, 0in},
                    {Distance3d 0in, y + 0.5in, 0in},
                    fill-pattern = color,
                    event-handler
                }
            }
        }
        {group.translate x, 0in, 0in}
        {scene.add-object group}
    }
  || SceneGraphic displays the scene on the page.
    {SceneGraphic
        width = 5in,
        height = 5in,
        background = {FillPattern.get-black},
        scene
    }
}