Support multi-dimensional arrays in FPP

[timcanham]

F´ Version	3.5.1
Affected Component	n/a

---

Feature Description

Support an FPP notation for multi-dimensional arrays like:

array twod_array = [10][15] F32

Rationale

If developers want to store something like a matrix as a parameter, they have to do it in two stages like here. It would be convenient to define it in one place.

[matt392code]

fpp-multidim-arrays.md

Multi-dimensional Arrays in FPP

Technical Specification

1. Overview

This specification defines the syntax and semantics for multi-dimensional arrays in FPP (F Prime Prime).

2. Syntax

2.1 Basic Syntax

array <array_name> = [<dim1>][<dim2>]...[<dimN>] <type> [default <default_value>] [format <format_string>]

Where:

• <array_name>: Valid FPP identifier
• <dim1>, <dim2>, ..., <dimN>: Positive integer dimensions
• <type>: Valid FPP type
• <default_value>: Optional default value specification
• <format_string>: Optional format specification

2.2 Default Value Specification

Default values for multi-dimensional arrays can be specified in several ways:

1. Nested array literals:

array matrix = [2][3] F32 default [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]

2. Single value promotion:

array matrix = [2][3] F32 default 0.0  # Promotes to [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]

3. Empty default (zero-initialization):

array matrix = [2][3] F32  # Initializes to [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]

3. Semantics

3.1 Memory Layout

Multi-dimensional arrays are stored in row-major order (C-style). For a 2D array with dimensions [M][N], element (i,j) is stored at offset (i * N + j).

3.2 Type Checking

1. All dimensions must be positive integers known at compile time
2. The base type must be a valid FPP type
3. Default values must match the array dimensions exactly when specified as nested literals
4. Single values used as defaults must be promotable to the base type

3.3 Default Value Rules

1. If no default is specified, the array is zero-initialized
2. Single value defaults are promoted to fill all elements
3. Nested literal defaults must match dimensions exactly
4. All default values must be convertible to the base type

4. Examples

# 2D array of F32 (3x4 matrix)
array matrix = [3][4] F32

# 3D array of U8 with single value promotion
array cube = [2][2][2] U8 default 1

# 2D array with nested literal default
array init_matrix = [2][2] F32 default [[1.0, 2.0], [3.0, 4.0]]

# 2D array with format string
array formatted = [2][3] F32 format "{.03f}"

# Array of arrays (equivalent to 2D array)
array row = [3] F32
array matrix = [2] row  # Creates a 2x3 matrix

5. Implementation Considerations

5.1 Code Generation

The FPP compiler should generate:

1. Appropriate serialization/deserialization code for all dimensions
2. Proper initialization code for default values
3. Correct size calculations for memory allocation
4. Accessor methods that handle multi-dimensional indexing

5.2 Performance

1. Access patterns should be optimized for row-major order
2. Serialization should be implemented efficiently for large arrays
3. Memory layout should be cache-friendly

6. Backwards Compatibility

This feature maintains backwards compatibility with existing single-dimension array syntax. All existing array definitions remain valid.

7. Error Handling

The compiler should generate clear error messages for:

1. Mismatched dimensions in default values
2. Invalid dimension specifications
3. Type mismatches in default values
4. Invalid format strings

8. Limitations

1. Maximum number of dimensions is implementation-defined
2. Total size must fit within platform memory constraints
3. Individual dimension sizes must be positive integers

9. Future Considerations

1. Support for dynamic dimensions
2. Specialized matrix operations
3. Integration with mathematical libraries
4. Support for sparse arrays