Unit VectorMath

Description

A lot of operations on vectors and matrices. This includes operations on geometric objects (2D and 3D) that can be represented as some vectors, matrices and scalar values. Various collision-checking routines for these geometric objects. Also functions to operate on RGB colors (these are vectors too, after all).

Representation of geometric objects in this unit :

• Triangle is a TTriangle<point-type> type. Where <point-type> is such suffix that vector type TVector<point-type> exists. For example, we have TVector3Single type that represents a point in 3D space, so you can use TTriangle3Single to represent triangle in 3D space. There are also 2D triangles like TTriangle2Single and TTriangle2Double.

  Triangle's three points must not be collinear, i.e. routines in this unit generally don't accept "degenerated" triangles that are not really triangles. So 3D triangle must unambiguously define some plane in the 3D space. The only function in this unit that is able to handle "degenerated" triangles is IsValidTriangle, which is exactly used to check whether the triangle is degenerated.

  Since every valid triangle unambiguously determines some plane in the 3D space, it also determines it's normal vector. In this unit, when dealing with normal vectors, I use two names:

  • TriangleNormal means that this is the normalized (i.e. scaled to length 1.0) normal vector.

  • TriangleDir means that this is not necessarily normalized normal vector.

• Plane in 3D space is a vector TVector4*. Such vector [A, B, C, D] defines a surface that consists of all points satisfying equation A * x + B * y + C * z + D = 0. At least one of A, B, C must be different than zero.

  Vector [A, B, C] is called PlaneDir in many places. Or PlaneNormal when it's guaranteed (or required to be) normalized, i.e. scaled to have length 1.

• Line in 3D space is represented by two 3D vectors: Line0 and LineVector. They determine a line consisting of all points that can be calculated as Line0 + R * LineVector where R is any real value.

  LineVector must not be a zero vector.

• Line in 2D space is sometimes represented as 2D vectors Line0 and LineVector (analogously like line in 3D).

  And sometimes it's represented as a 3-items vector, like TVector3Single (for [A, B, C] line consists of all points satisfying A * x + B * y + C = 0). At least one of A, B must be different than zero.

• A tunnel is an object that you get by moving a sphere along the line segment. In other words, this is like a cylinder, but ended with a hemispheres. The tunnel is represented in this unit as two points Tunnel1, Tunnel2 (this defines a line segment) and a TunnelRadius.

• A ray is defined just like a line: two vectors Ray0 and RayVector, RayVector must be nonzero. Ray consists of all points Line0 + R * LineVector for R being any real value >= 0.

• A simple plane in 3D is a plane parallel to one of the three basic planes. This is a plane defined by the equation X = Const or Y = Count or Z = Const. Such plane is represented as PlaneConstCoord integer value equal to 0, 1 or 2 and PlaneConstValue.

  Note that you can always represent the same plane using a more general plane 3D equation, just take

    Plane[0..2 / PlaneConstCoord] = 0,
    Plane[PlaneConstCoord] = -1,
    Plane[3] = PlaneConstValue.
  

  On such "simple plane" we can perform many calculations much faster.

• A line segment (often referred to as just segment) is represented by two points Pos1 and Pos2. For some routines the order of points Pos1 and Pos2 is significant (but this is always explicitly stated in the interface, so don't worry).

  Sometimes line segment is also represented as Segment0 and SegmentVector, this consists of all points Segment0 + SegmentVector * t for t in [0..1]. SegmentVector must not be a zero vector.

  Conversion between the two representations above is trivial, just take Pos1 = Segment0 and Pos2 = Segment0 + SegmentVector.

• On 2005-03 functions that work with frustum were added. Frustum is represented as TFrustum type, which is just 6 plane equations.

In descriptions of geometric objects above, I often stated some requirements, e.g. the triangle must not be "degenerated" to a line segment, RayVector must not be a zero vector, etc. You should note that these requirements are generally not checked by routines in this unit (for the sake of speed) and passing wrong values to many of the routines may lead to serious bugs — maybe the function will raise some arithmetic exception, maybe it will return some nonsensible result. In other words: when calling these functions, always make sure that values you pass satisfy the requirements.

(However, wrong input values should never lead to some serious bugs like access violations or range check errors — in cases when it would be possible, we safeguard against this. That's because sometimes you simply cannot guarantee for 100% that input values are correct, because of floating-point precision problems – see below.)

As for floating-point precision:

• Well, floating-point inaccuracy is, as always, a problem. This unit always uses FloatsEqual and variables SingleEpsilonEquality, DoubleEpsilonEquality and ExtendedEpsilonEquality when comparison of floating-point values is needed. In some cases you may be able to adjust these variables to somewhat fine-tune the comparisons.

• For collision-detecting routines, the general strategy in case of uncertainty (when we're not sure whether there is a collision or the objects are just very very close to each other) is to say that there is a collision.

  This means that we may detect a collision when in fact the precise mathematical calculation says that there is no collision.

  This approach should be suitable for most use cases.

A design question about this unit: Right now I must declare two variables to define a sphere (like SphereCenter: vector; SphereRadius: scalar;) Why not wrap all the geometric objects (spheres, lines, rays, tunnels etc.) inside some records ? For example, define a sphere as

  TSphere = record Center: vector; Radius: scalar; end;

The answer: this is not so good idea, because it would create a lot of such types into unit, and I would have to implement simple functions that construct and convert between these types. Consider e.g. when I have a tunnel (given as Tunnel1, Tunnel2 points and TunnelRadius vector) and I want to "extract" the properties of the sphere at the 1st end of this tunnel. Right now, it's simple: just consider Tunnel1 as a sphere center, and TunnelRadius is obviously a sphere radius. Computer doesn't have to actually do anything, you just have to think in a different way about Tunnel1 and TunnelRadius. But if I would have tunnel wrapped in a type like TTunnel and a sphere wrapped in a type like TSphere, then I would have to actually implement this trivial conversion. And then doing such trivial conversion at run-time would take some time, because you have to copy 6 floating-point values. This would be a very serious waste of time at run-time. Well, on the other hand, routines could take less parameters (e.g. only 1 parameter TTunnel, instead of three vector parameters), but (overall) we would still loose a lot of time.

In many places where I have to return collision with a line segment, a line or a ray there are alternative versions that return just a scalar "T" instead of a calculated point. The actual collision point can be calculated then like Ray0 + T * RayVector. Of course for rays you can be sure that T is >= 0, for line segments you can be sure that 0 <= T <= 1. The "T" is often useful, because it allows you to easily calculate collision point, and also the distance to the collision (you can e.g. compare T1 and T2 to compare which collision is closer, and when your RayVector is normalized then the T gives you the exact distance). Thanks to this you can often entirely avoid calculating the actual collision point (Ray0 + T * RayVector).

This unit compiles with FPC and Delphi. But it will miss most things when compiled with Delphi. Because it compiles with Delphi, Images unit (that depends on some simplest things from this unit) can be compiled with Delphi too.

This unit, when compiled with FPC, will contain some stuff useful for integration with FPC's Matrix unit. The idea is to integrate in the future this unit with FPC's Matrix unit much more. For now, there are some "glueing" functions here like Vector_Get_Normalized that allow you to comfortably perform operations on Matrix unit object types. Most important is also the overload of ":=" operator that allows you to switch between VectorMath arrays and Matrix objects without any syntax obfuscation. Although note that this overload is a little dangerous, since now code like

  V3 := VectorProduct(V1, V2);

compiles and works both when all three V1, V2 and V3 are TVector3Single arrays or TVector3_Single objects. However, for the case when they are all TVector3_Single objects, this is highly un-optimal, and

  V3 := V1 >< V2;

is much faster, since it avoids the implicit convertions (unnecessary memory copying around).

uses

• SysUtils
• KambiUtils
• Matrix

Overview

Classes, Interfaces, Objects and Records

Functions and Procedures