Skip to content

Began documenting SIMD vectorization #226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dawoodoz merged 3 commits into from
Feb 14, 2026
Merged

Began documenting SIMD vectorization #226

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5bedc3d
Began writing a dictionary and a page about design principles for lon…
Dawoodoz Feb 13, 2026
fe6bea6
Documented the basics of using the simd.h header, but not all topics …
Dawoodoz Feb 13, 2026
71964f5
Noted that the new abs function in noSimd.h needs to be tested in Sim…
Dawoodoz Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions Doc/DesignPrinciples.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
<!DOCTYPE html> <HTML lang=en> <HEAD> <STYLE>
body { background-color: #EEFFEE; font-size: 1.0rem; font-family: Arial; max-width: 60rem;
color: #000000; margin: 0px;
padding-left: 0px; padding-right: 0px; padding-top: 0px; padding-bottom: 0px; }
H1 { padding-left: 10px; padding-right: 0px; padding-top: 10px; padding-bottom: 10px; font-size: 1.4rem; }
H2 { padding-left: 10px; padding-right: 0px; padding-top: 10px; padding-bottom: 0px; font-size: 1.2rem; }
blockquote {
tab-size: 3rem;
color: #88FF88; background: #000000;
font-size: 0.95rem; font-family: monospace;
padding-left: 5px; padding-right: 5px;
padding-top: 5px; padding-bottom: 5px;
}
P { padding-left: 20px; padding-right: 0px; padding-top: 0px; padding-bottom: 0px; }
IMG { padding-left: 0px; padding-right: 0px; padding-top: 2px; padding-bottom: 0px;
max-width: 100%; }
A { display: inline; border-radius: 4px;
font-size: 1.0rem; font-family: Arial; color: #000044; text-decoration: none;
padding-left: 4px; padding-right: 4px; padding-top: 4px; padding-bottom: 4px; }
A:hover { color: #FFFF00; background: #000044; }
A:active { color: #FFFFFF; background: #444444; }
</STYLE> </HEAD> <BODY>
<IMG SRC="Images/Title.png" ALT="Images/Title.png">
<P>
<A href="Manual.html">Back to main page</A>
</P><P>
</P><H1> Design principles</H1><P>
</P><P>
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Choice of C++ instead of C</H2><P>
</P><P>
The original version of DFPSR was written in the C language, in an attempt to keep it simple and have a stable ABI for dynamic linking with almost any language.
Being a graphics API instead of a graphics engine however, the pre-existing image filters would have made very boring graphics.
So dynamic linking was not an option and then it did not matter if the ABI was stable or not when compiling all source code in the same version of the same language.
Any mistake in handling of resources when writing all applications in C would lead to memory corruption, so development was painfully slow when trying to throw together a quick prototype.
The library needed a language that allowed writing both realtime image filters with pointers, and the high level abstractions needed to apply bound checks on those pointers in debug mode.

</P><P>
While not perfect, C++ 2014 filled most of the requirements, by having access to both low level optimization and high level abstractions.
With dsr::SafePointer, there were no more random memory crashes of unknown origin, because bound checked pointers caught data corruption directly where it happened in debug mode.
With RAII, memory leaks no longer happened from having allocations with no pointers to them, only from applications deciding to keep adding things to collections without ever removing them.
The SIMD abstraction used operator overloading instead of named functions for everything, which made complex math expressions a lot more readable.

</P><P>
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Relying on a language standard instead of a single compiler implementation</H2><P>
</P><P>
What if the library had used a language with a single compiler implementation to fully specify the behavior?
If the interpretation of your code requires reading the source code of a specific compiler to understand what it is supposed to do, that code will die with the compiler.
Once the source code stands on its own without a compiler that still runs on modern systems, avoiding undefined behavior must be done in the code itself.

</P><P>
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Bundling transpilers with projects</H2><P>
</P><P>
Relying on a transpiler that is bundled with the project is however fine, because you can generate code that avoids undefined behavior and save the output in case that the transpiler can no longer execute.
This documentation was generated using a transpiler, so that it does not rely on the ability to parse HTML.

</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P>
</BODY> </HTML>
119 changes: 119 additions & 0 deletions Doc/Dictionary.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
<!DOCTYPE html> <HTML lang=en> <HEAD> <STYLE>
body { background-color: #EEFFEE; font-size: 1.0rem; font-family: Arial; max-width: 60rem;
color: #000000; margin: 0px;
padding-left: 0px; padding-right: 0px; padding-top: 0px; padding-bottom: 0px; }
H1 { padding-left: 10px; padding-right: 0px; padding-top: 10px; padding-bottom: 10px; font-size: 1.4rem; }
H2 { padding-left: 10px; padding-right: 0px; padding-top: 10px; padding-bottom: 0px; font-size: 1.2rem; }
blockquote {
tab-size: 3rem;
color: #88FF88; background: #000000;
font-size: 0.95rem; font-family: monospace;
padding-left: 5px; padding-right: 5px;
padding-top: 5px; padding-bottom: 5px;
}
P { padding-left: 20px; padding-right: 0px; padding-top: 0px; padding-bottom: 0px; }
IMG { padding-left: 0px; padding-right: 0px; padding-top: 2px; padding-bottom: 0px;
max-width: 100%; }
A { display: inline; border-radius: 4px;
font-size: 1.0rem; font-family: Arial; color: #000044; text-decoration: none;
padding-left: 4px; padding-right: 4px; padding-top: 4px; padding-bottom: 4px; }
A:hover { color: #FFFF00; background: #000044; }
A:active { color: #FFFFFF; background: #444444; }
</STYLE> </HEAD> <BODY>
<IMG SRC="Images/Title.png" ALT="Images/Title.png">
<P>
<A href="Manual.html">Back to main page</A>
</P><P>
</P><H1> Dictionary</H1><P>
</P><P>
To avoid confusion when reading the code comments and documentation, some contemporary programming words will have to be explained in this dictionary.

</P><P>
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Acronyms</H2><P>
</P><P>
While one should mostly avoid using abbreviations in source code, writing davidForsgrenPiuvasSoftwareRenderer:: instead of dsr:: in headers would take too much space and not help to explain the purpose of the code.

</P><P>
ABI | Application Binary Interface.
How a library is linked and called after the source code has been compiled, which is a binary representation.

</P><P>
API | Application Programming Interface.
How a library is called in the source code, which can be checked by the programming language's type system.
A wrapper to call code written in a different language is an API, because the ABI has been wrapped in pre-declarations explaining the meaning of the bits in the calling language's type system.

</P><P>
AD | Anno Domini (In the lord's years), used for years after the birth of prophet Jesus Christ in the Gregorian calendar, which is the calendar used to name versions of the C++ programming language.

</P><P>
C | A programming language created by Dennis Ritche in the 1970s AD.
Not to be confused with the C# language.

</P><P>
C++ | A programming language created by Bjarne Stroustrup in the 1980s AD. Inherited most of the core design from C for easy porting while adding new features.

</P><P>
DSR | David's (Forsgren Piuva's) software renderer, the shorter acronym for this library and the surrounding framework.

</P><P>
DFPSR | David Forsgren Piuva's software renderer, the longer acronym for this library and the surrounding framework.

</P><P>
HTML | Hyper Text Markup Language. A text format adapted for reading on computers instead of printing, by containing links and not dictating any page layout. Most known as the default format for websites.

</P><P>
LOD | Level Of Detail. Often referring to a 3D model's polygon count, but can also apply to other types of assets.

</P><P>
MIP | Multum in parvo. A term used for texture pyramids because there are multiple image resolutions stored in the same texture. Used to avoid noisy undersampling of textures that are seen from far away.

</P><P>
RAII | Resource Allocation Is Initialization, an important design principle in C++ that prevents memory leaks by letting types handle heap memory allocation automatically in constructors and destructors.

</P><P>
SIMD | Single Instruction Multiple Data.
A power efficient hardware design for packing arrays of elements into the same register and processing them at the same time using multiple lanes.
Makes the machine instructions faster, by both increasing the number of elements processed per instruction, and reducing the pipeline latency needed to run a single instruction by using smaller types.

</P><P>
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Abbreviations</H2><P>
</P><P>
Doc | Documentation

</P><P>
Gen | Generator, a function or program used to create something automatically.

</P><P>
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Expressions</H2><P>
</P><P>
Array | A coherent and indexed block of memory with alignment for each element to allow random access.
dsr::Array creates a heap allocation based on a size given at runtime during construction.
dsr::FixedArray does not make any heap allocation, but can not change its size at runtime.

</P><P>
Et cetera | Latin expression that is often used to indicate that a list of examples is not exhaustive, roughly meaning "and all the rest".

</P><P>
List | A collection that can be populated with elements at runtime, where indices to the elements are treated as something temporary.
dsr::List is an array based list, and simply called List to save some typing when there is no linked list among the framework's generic collections.

</P><P>
Vector | An array of numbers, used for multi-dimensional math or SIMD vectorization.

</P><P>
Vectorize | To use vectors in order to solve a math problem.
Instead of treating one million pixels as independent objects with a heap allocation for each pixel, we vectorize images into memory aligned arrays and loop over them using chunks of shorter SIMD vectors.

</P><P>
Scalar | A single number, as opposed to a collection of multiple numbers.
</P>
</BODY> </HTML>
11 changes: 10 additions & 1 deletion Doc/Manual.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,9 @@
<A href="ChoosingStorage.html">Choosing storage</A>
</P><P>
<IMG SRC="Images/SmallDot.png">
<A href="Vectorization.html">SIMD vectorization</A>
</P><P>
<IMG SRC="Images/SmallDot.png">
<A href="ImageProcessing.html">Image processing</A>
</P><P>
</P><IMG SRC="Images/Border.png"><P>
Expand Down Expand Up @@ -108,11 +111,17 @@
</P><H2> Future maintenance</H2><P>
</P><P>
<IMG SRC="Images/SmallDot.png">
<A href="Preserving.html">Preserving software for future maintainers</A>
<A href="Dictionary.html">Dictionary for commonly used terms</A>
</P><P>
<IMG SRC="Images/SmallDot.png">
<A href="DesignPrinciples.html">Design principles</A>
</P><P>
<IMG SRC="Images/SmallDot.png">
<A href="Porting.html">Porting to new processors and operating systems</A>
</P><P>
<IMG SRC="Images/SmallDot.png">
<A href="Preserving.html">Preserving software for future maintainers</A>
</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P>
</BODY> </HTML>
35 changes: 35 additions & 0 deletions Doc/Text/DesignPrinciples.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<- Manual.html | Back to main page

Title: Design principles

---

Title2: Choice of C++ instead of C

The original version of DFPSR was written in the C language, in an attempt to keep it simple and have a stable ABI for dynamic linking with almost any language.
Being a graphics API instead of a graphics engine however, the pre-existing image filters would have made very boring graphics.
So dynamic linking was not an option and then it did not matter if the ABI was stable or not when compiling all source code in the same version of the same language.
Any mistake in handling of resources when writing all applications in C would lead to memory corruption, so development was painfully slow when trying to throw together a quick prototype.
The library needed a language that allowed writing both realtime image filters with pointers, and the high level abstractions needed to apply bound checks on those pointers in debug mode.

While not perfect, C++ 2014 filled most of the requirements, by having access to both low level optimization and high level abstractions.
With dsr::SafePointer, there were no more random memory crashes of unknown origin, because bound checked pointers caught data corruption directly where it happened in debug mode.
With RAII, memory leaks no longer happened from having allocations with no pointers to them, only from applications deciding to keep adding things to collections without ever removing them.
The SIMD abstraction used operator overloading instead of named functions for everything, which made complex math expressions a lot more readable.

---

Title2: Relying on a language standard instead of a single compiler implementation

What if the library had used a language with a single compiler implementation to fully specify the behavior?
If the interpretation of your code requires reading the source code of a specific compiler to understand what it is supposed to do, that code will die with the compiler.
Once the source code stands on its own without a compiler that still runs on modern systems, avoiding undefined behavior must be done in the code itself.

---

Title2: Bundling transpilers with projects

Relying on a transpiler that is bundled with the project is however fine, because you can generate code that avoids undefined behavior and save the output in case that the transpiler can no longer execute.
This documentation was generated using a transpiler, so that it does not rely on the ability to parse HTML.

---
69 changes: 69 additions & 0 deletions Doc/Text/Dictionary.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
<- Manual.html | Back to main page

Title: Dictionary

To avoid confusion when reading the code comments and documentation, some contemporary programming words will have to be explained in this dictionary.

---

Title2: Acronyms

While one should mostly avoid using abbreviations in source code, writing davidForsgrenPiuvasSoftwareRenderer:: instead of dsr:: in headers would take too much space and not help to explain the purpose of the code.

ABI | Application Binary Interface.
How a library is linked and called after the source code has been compiled, which is a binary representation.

API | Application Programming Interface.
How a library is called in the source code, which can be checked by the programming language's type system.
A wrapper to call code written in a different language is an API, because the ABI has been wrapped in pre-declarations explaining the meaning of the bits in the calling language's type system.

AD | Anno Domini (In the lord's years), used for years after the birth of prophet Jesus Christ in the Gregorian calendar, which is the calendar used to name versions of the C++ programming language.

C | A programming language created by Dennis Ritche in the 1970s AD.
Not to be confused with the C# language.

C++ | A programming language created by Bjarne Stroustrup in the 1980s AD. Inherited most of the core design from C for easy porting while adding new features.

DSR | David's (Forsgren Piuva's) software renderer, the shorter acronym for this library and the surrounding framework.

DFPSR | David Forsgren Piuva's software renderer, the longer acronym for this library and the surrounding framework.

HTML | Hyper Text Markup Language. A text format adapted for reading on computers instead of printing, by containing links and not dictating any page layout. Most known as the default format for websites.

LOD | Level Of Detail. Often referring to a 3D model's polygon count, but can also apply to other types of assets.

MIP | Multum in parvo. A term used for texture pyramids because there are multiple image resolutions stored in the same texture. Used to avoid noisy undersampling of textures that are seen from far away.

RAII | Resource Allocation Is Initialization, an important design principle in C++ that prevents memory leaks by letting types handle heap memory allocation automatically in constructors and destructors.

SIMD | Single Instruction Multiple Data.
A power efficient hardware design for packing arrays of elements into the same register and processing them at the same time using multiple lanes.
Makes the machine instructions faster, by both increasing the number of elements processed per instruction, and reducing the pipeline latency needed to run a single instruction by using smaller types.

---

Title2: Abbreviations

Doc | Documentation

Gen | Generator, a function or program used to create something automatically.

---

Title2: Expressions

Array | A coherent and indexed block of memory with alignment for each element to allow random access.
dsr::Array creates a heap allocation based on a size given at runtime during construction.
dsr::FixedArray does not make any heap allocation, but can not change its size at runtime.

Et cetera | Latin expression that is often used to indicate that a list of examples is not exhaustive, roughly meaning "and all the rest".

List | A collection that can be populated with elements at runtime, where indices to the elements are treated as something temporary.
dsr::List is an array based list, and simply called List to save some typing when there is no linked list among the framework's generic collections.

Vector | An array of numbers, used for multi-dimensional math or SIMD vectorization.

Vectorize | To use vectors in order to solve a math problem.
Instead of treating one million pixels as independent objects with a heap allocation for each pixel, we vectorize images into memory aligned arrays and loop over them using chunks of shorter SIMD vectors.

Scalar | A single number, as opposed to a collection of multiple numbers.
11 changes: 10 additions & 1 deletion Doc/Text/Manual.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,9 @@ Title2: Techniques
*
<- ChoosingStorage.html | Choosing storage

*
<- Vectorization.html | SIMD vectorization

*
<- ImageProcessing.html | Image processing

Expand All @@ -74,9 +77,15 @@ Title2: Technical details
Title2: Future maintenance

*
<- Preserving.html | Preserving software for future maintainers
<- Dictionary.html | Dictionary for commonly used terms

*
<- DesignPrinciples.html | Design principles

*
<- Porting.html | Porting to new processors and operating systems

*
<- Preserving.html | Preserving software for future maintainers

---
Loading