HelixToolkit.Nex.Maths 1.2.0

# HelixToolkit.Nex.Maths

The `HelixToolkit.Nex.Maths` package provides a comprehensive set of mathematical utilities and structures designed to support 3D graphics operations within the HelixToolkit-Nex engine. This package includes implementations for vectors, matrices, colors, bounding volumes, and collision detection, among other mathematical constructs essential for 3D rendering and physics calculations.

## Overview

The `HelixToolkit.Nex.Maths` package is integral to the HelixToolkit-Nex engine, providing the mathematical backbone required for rendering and physics simulations. It includes:
- Support for various color formats and operations.
- Vector and matrix operations optimized for 3D graphics.
- Bounding volumes like boxes, spheres, and frustums for collision detection and spatial queries.
- Utility functions for geometric calculations and transformations.

## Key Types

| Type                  | Description                                                                 |
|-----------------------|-----------------------------------------------------------------------------|
| `Color`               | Represents a 32-bit color in RGBA format.                                   |
| `Color3`              | Represents a color in RGB format.                                           |
| `Color4`              | Represents a color in RGBA format with floating-point precision.            |
| `BoundingBox`         | Represents an axis-aligned bounding box in 3D space.                        |
| `BoundingSphere`      | Represents a bounding sphere in 3D space.                                   |
| `BoundingFrustum`     | Defines a frustum for frustum culling and intersection tests.               |
| `Vector3`             | Represents a vector with three components.                                  |
| `Vector4`             | Represents a vector with four components.                                   |
| `Matrix`              | Represents a 4x4 matrix used for transformations.                           |
| `Ray`                 | Represents a ray in 3D space for intersection tests.                        |
| `Plane`               | Represents a plane in 3D space.                                             |
| `Collision`           | Provides static methods for collision detection and geometric queries.      |
| `Bool4`               | Represents a four-dimensional vector of boolean values.                     |
| `Bool32Bit`           | Represents a boolean value with a size of 32 bits.                          |
| `AngleSingle`         | Represents a unit-independent angle using a single-precision floating-point.|
| `Alignment`           | Provides utility methods for memory alignment calculations.                 |
| `Size`                | Represents a two-dimensional size with width and height.                    |
| `BoundingBoxHelper`   | Provides static methods for operations on bounding boxes.                   |

## Recent Additions

### New Colors

- `Charcoal`: A new color added to the `Color` struct, represented in BGRA format as `0xFF333333`.

### New Matrix Methods

- `ToMatrix(IList<float> array)`: Creates a 4x4 matrix from a list of 16 single-precision floating-point values in row-major order.
- `ToMatrixTransposed(IList<float> array)`: Creates a 4x4 matrix from a list of 16 single-precision floating-point values in column-major order, transposing the order to row-major.

### New Methods

- `Color.PackToRGBA()`: Packs the color into a 32-bit unsigned integer in RGBA format.
- `Color4Helper.EncodeToUInt(Color4 color)`: Encodes a `Color4` into a 32-bit unsigned integer in RGBA format.

## Usage Examples

### Creating and Using Colors

```csharp
using HelixToolkit.Nex.Maths;

// Create a color using RGBA values
Color color = new Color(255, 0, 0, 255); // Red color

// Convert to Color4 for floating-point operations
Color4 color4 = color.ToColor4();

// Adjust color brightness
Color4 brighterColor = Color4Helper.ChangeIntensity(color4, 1.2f);

// Use the new Charcoal color
Color charcoalColor = Color.Charcoal;

// Pack color to RGBA
uint packedColor = color.PackToRGBA();

Working with Matrices

using HelixToolkit.Nex.Maths;

// Create a matrix from a list of 16 floats in row-major order
IList<float> matrixValues = new List<float>
{
    1, 0, 0, 0,
    0, 1, 0, 0,
    0, 0, 1, 0,
    0, 0, 0, 1
};
Matrix matrix = matrixValues.ToMatrix();

// Create a matrix from a list of 16 floats in column-major order, transposed
Matrix transposedMatrix = matrixValues.ToMatrixTransposed();

Working with Bounding Volumes

using HelixToolkit.Nex.Maths;

// Create a bounding box
BoundingBox box = new BoundingBox(new Vector3(0, 0, 0), new Vector3(1, 1, 1));

// Check if a point is inside the bounding box
Vector3 point = new Vector3(0.5f, 0.5f, 0.5f);
bool isInside = box.Contains(point) == ContainmentType.Contains;

// Create a bounding sphere
BoundingSphere sphere = new BoundingSphere(new Vector3(0, 0, 0), 1.0f);

// Check for intersection between box and sphere
bool intersects = box.Intersects(ref sphere);

Transforming a Bounding Box

using HelixToolkit.Nex.Maths;

// Define a transformation matrix
Matrix transform = Matrix.CreateTranslation(new Vector3(1, 1, 1));

// Transform the bounding box
BoundingBox transformedBox = BoundingBoxHelper.Transform(box, ref transform);

Collision Detection

using HelixToolkit.Nex.Maths;

// Define a ray
Ray ray = new Ray(new Vector3(0, 0, -5), Vector3.UnitZ);

// Define a plane
Plane plane = new Plane(Vector3.UnitY, 0);

// Check for intersection
if (Collision.RayIntersectsPlane(ref ray, ref plane, out float distance))
{
    Vector3 intersectionPoint = ray.Position + ray.Direction * distance;
    Console.WriteLine($"Intersection at: {intersectionPoint}");
}

Using Bool4 and Bool32Bit

using HelixToolkit.Nex.Maths;

// Create a Bool4 vector
Bool4 boolVector = new Bool4(true, false, true, false);

// Access components
bool xValue = boolVector.X;

// Create a Bool32Bit
Bool32Bit bool32 = new Bool32Bit(true);

// Convert to and from bool
bool normalBool = bool32;
Bool32Bit convertedBack = normalBool;

Working with Angles

using HelixToolkit.Nex.Maths;

// Create an angle in degrees
AngleSingle angle = new AngleSingle(90, AngleType.Degree);

// Convert to radians
float radians = angle.Radians;

// Wrap the angle
angle.Wrap();

Memory Alignment Calculations

using HelixToolkit.Nex.Maths;

// Align a size value
uint size = 13;
uint alignment = 16;
uint alignedSize = size.GetAlignedSize(alignment);

// Align a memory address
ulong address = 1024;
ulong alignedAddress = address.GetAlignedAddress(alignment);

Working with Size

using HelixToolkit.Nex.Maths;

// Create a Size instance
Size size = new Size(1920, 1080);

// Check if the size is empty
bool isEmpty = size.IsEmpty;

// Convert Size to Vector2
Vector2 vector = size;

Architecture Notes

• Design Patterns: The package extensively uses value types (structs) for performance-critical operations, minimizing heap allocations.
• Dependencies: This package is a foundational component of the HelixToolkit-Nex engine and is used by other packages for rendering and physics calculations.
• Matrix and Vector Operations: Optimized for 3D graphics, supporting both row-major and column-major formats as needed.
• Bounding Volumes: Essential for spatial queries and collision detection, supporting efficient intersection tests and containment checks.