Debian Codegraph @

doc/manual2/d2

raw
1 h1. Dealing with two Dimensions: *D2*
2
3 After writing a few classes for two dimensional objects, we realized
4 that there is a lot of boilerplate associated with what is essentially
5 lifting one dimensional concepts into two. Instead of frequently
6 rewriting this code, we instead created the *D2* template class.
7
8 For example, a point in space might be represented by *D2<double>*.
9 This may, in fact, become the actual representation for Point.
10 We have not yet replaced Point with this, as not all of Points
11 operations have been ported (or are applicable), and we are not
12 yet sure if there is 0 performance loss.
13
14 (TODO remove previous stuff if D2<double> becomes point repr)
15
16 h2. Component Access
17
18 One might expect such an object to have @.x@ and @.y@ fields, however,
19 it instead consists of 2 element array. With LibNR, it was found that
20 the availability of @.x@ and @.y@ encouraged people to attempt to
21 inline operations rather than using the operators, perhaps in (vain)
22 pursuit of a performance enhancement. By using an array, we encourage
23 people to think about points as symmetric objects and discourage
24 direct use of the components. However, we still provide direct access
25 for the rare occasion that it is needed. Even in these cases, the array
26 method reduces bugs by encouraging iteration over the array rather than
27 explicit element reference.
28
29 The components of a *D2* are accessed through the indexing operator, [].
30 The input value to the index operator is the @enum@ *Dim2*, which
31 defines *X* = 0 and *Y* = 1. This is to encourage using the
32 @for(int d=0; i<2; i++)@ idiom when normal operations do not suffice.
33
34 h2. Arithmetic Operators
35
36 @D2<T>@ implements the *AddableConcept*, *OffsetableConcept*, and
37 *ScalableConcept* (if @T@ implements them as well) yielding the
38 following operators:
39
40 <pre><code>
41 AddableConcept: x + y, x - y, x += y, x -= y
42 OffsetableConcept: x + p, x - p, x += p, x -= p
43 ScalableConcept: x * p, x / p, x *= p, x /= p, -x
44 x * d, x / d, x *= d, x /= d
45 </code></pre>
46
47 (where @x@ and @y@ are *D2*, d is *Coord*, and @p@ is a *Point* and all
48 return @D2<T>@)
49
50 These operators all just apply the operation on @T@ to the components.
51 So, @a + b@ just returns @D2<T>(a[X] + b[X], a[Y] + b[Y])@, though the
52 actual code uses a loop (which is unrolled) in order to avoid
53 bugs.
54
55 h2. Geometric Operations
56
57 <pre><code>
58 T dot(D2<T> const &, D2<T> const &);
59 T cross(D2<T> const &, D2<T> const &);
60 </code></pre>
61
62 The *dot*:http://en.wikipedia.org/wiki/Dot@product and
63 *cross*:http://en.wikipedia.org/wiki/Cross@product products are defined
64 on D2<T> when T implements *AddableConcept* and *MultiplicableConcept.
65 The cross function returns the length of the resultant 3d vector
66 perpendicular to the 2d plane.
67
68 @ D2<T> operator*(D2<T> const &, Matrix const &)@
69
70 This operation applies an affine transformation to the 2d object.
71
72 h2. Fragment Lifting
73
74 *D2<T>* also implements FragmentConcept if T implements it as well,
75 allowing *D2* to lift one dimensional functions into two-dimensional
76 parametric curves. As a fragment, a *D2* will represent a function
77 from a double to a Point.
78
79 h3. Fragment Operations
80
81 In addition to the normal set of Fragment methods, D2 has the following
82 functions:
83
84 h4. @ D2<T> compose(D2<T> const &a, T const &b); @
85
86 The *compose* function is defined when @T@ is a function representation which
87 supports composition. The only forms in 2geom are *SBasis* and *SBasis2d*.
88 The *D2* *compose* function composes @b@ on both components of @a@. This
89 makes sense, as a D2<SBasis> is double -> D2<double> and the function for
90 composition is double -> double. One way to think of composition is that
91 the output is equivalent to applying @b@ to the input, and then applying a
92 to @b@'s output.
93
94 h4. @ D2<T> compose_each(D2<T> const &a, D2<T> &b); @
95
96 The *compose_each* function is similar to the *compose* function, except that
97 @b@ is also a *D2*, so instead of composing the same function on each component,
98 the two functions in @b@ are used.
99
100
101 h4. @ Point D2<T>::operator()(double x, double y) const @
102
103 *D2* wraps this operator for when @T@ is a function taking a 2 component input.
104 The only case of this currently within 2geom is SBasis2d.
105
106 (TODO: derivative/integral)