3D Rendering
============

This tutorial illustrates how to use the [3D rendering](md:/Library_Reference/UI_Library/3D_Rendering)
capabilities of the UI library. This tutorial assumes that you are at least a bit familiar
with hardware-accelerated 3D rendering.

The code for this tutorial is available in the `root/tutorials/s3d/` directory in the Storm release.
As such, you can run them using the command `storm -f tutorials.s3d.<sample>` where `<sample>` is
the name of the example. The source code is heavily commented, and it is therefore possible to
follow along just by reading the source code in the order outlined below.


Common Utilities
----------------

Before starting, it is worth knowing that the file `common.bs` contains a few utilities to make the
rest of the examples shorter and more to the point.

Most importantly, this file contains the class [stormname:tutorials.s3d.SampleWindow]. It simply
inherits from [stormname:ui.Frame], initializes a window and sets the provided
[stormname:ui.Painter3D] to the window. This way we don't have to create a new [stormname:ui.Frame]
for every example. There is also a function
[stormname:tutorials.s3d.runSample(core.Str,ui.Painter3D)] that accepts a title for the frame and a
[stormname:ui.Painter3D]. It then creates a window and waits for it to close.


In addition to window management, `common.bs` provides the class
[stormname:tutorials.s3d.SamplePainter3D]. It inherits from [stormname:ui.Painter3D] and provides
the following additional member:

```stormdoc
@tutorials.s3d.SamplePainter3D
- .animationTime(*)
```


Finally, it implements [stormname:tutorials.s3d.resUrl(core.Str)] that looks up the full path to a
file name in the relevant resources directory. This is used to make it convenient to locate sample
models and textures. There is also a vertex type [stormname:tutorials.s3d.Output], that is used as
the output vertex type in many examples.


Tutorials
---------

The following tutorials are available. The tutorials depend on each other, so it is recommended to
follow them (at least roughly) from start to end.


1. [Simple Rendering](md:Simple_Rendering)
2. [Textures](md:Textures)
3. [Models](md:Models)
4. [Lighting](md:Lighting)
5. [Cel-Shading](md:Cel-Shading)
6. [Simple Shadows](md:Simple_Shadows)


