io7m
com.io7m.jcamera 0.5.0
3.1
Conventions

- 3.1.1. Overview
- 3.1.2. Architecture
- 3.1.3. Mathematics

3.1.1
Overview
1
This section attempts to document the mathematical and typographical conventions used in the rest of the documentation.
3.1.2
Architecture
1
The intention here is to first describe a simple purely mathematical rendering-and-input-system-independent camera that can be positioned and oriented, but that does not know anything about integration of its position and rotation over time. A separate system (the integrator) is built upon this camera that provides interpolation of the position and orientation over time to provide configurable smooth animation. Finally, a system (the input) is described that actually attaches the camera system to a keyboard and mouse package. The input package used in the examples is that of JOGL, but the system is specifically described in a manner to allow it to be easily adapted to any other input package. Essentially, the com.io7m.jcamera package tries to provide a cleanly-separated system-independent core, with the addition of a system to allow it to be attached to system-specific keyboard/mouse input packages. This is essential for the correctness of the software and also for the actual ease of understanding of the mathematics and implementation [1].
3.1.2.1. Architecture
3.1.3
Mathematics
1
Rather than rely on untyped and ambiguous mathematical notation, this documentation expresses all mathematics in strict Haskell 2010 with no extensions. All Haskell sources are included along with the documentation and can therefore be executed from the command line GHCi tool in order to interactively check results and experiment with functions.
2
When used within prose, functions are referred to using fully qualified notation, such as (Vector3f.cross n t). This an the application of the cross function defined in the Vector3f module, to the arguments n and t.
3
Formal examples and definitions, however, will typically be defined within their own modules, possibly with import statements used to allow for shorter names. As an example [ Forward.hs]:
3.1.3.1. Forward movement

            module Forward where

    import qualified Vector3f

    move_forward :: Vector3f.T -> Vector3f.T -> Float -> Vector3f.T
    move_forward p forward d = Vector3f.add3 p (Vector3f.scale forward d)

[1]
Most camera systems documented (usually in blogs) online either describe only the mathematics and fail to describe the intricacies of driving the system with input, or violently mash all of the mathematics into an existing assumption-ridden input and rendering system - meaning that the reader has to fully understand an input system or rendering system that they may not ever have even seen before just to understand how the camera works.