Rendering prefer it’s 1996 – Child’s first pixel
There’s completely no likelihood we’ll get to this degree of high quality.
In 1996, I used to be a teen and not using a gaming console. Whereas my buddies loved their Crash Bandicoots, Tekens, and Turoks, I had a beige 486 DX 2 with a turbo button, 16Mb of RAM, a 256Mb onerous disk, and a 2x CD-ROM drive working DOS. After which I obtained a duplicate of Quake. Did it run nice? No. But it surely did run! And to my younger eyes, it was essentially the most lovely factor I’ve ever seen on my laptop display. Okay, essentially the most lovely brown factor.
3D accelerator graphics playing cards had been of their infancy. Most DOS PC video games round that point would render their wonderful pixels by way of the CPU to a devoted space in RAM, e.g. beginning at phase handle 0xa000. The (fairly dumb) graphics card would then learn and show the contents of that reminiscence space in your cumbersome CRT. This is named software rendering or software rasterization.
I did dabble in some graphics programming again then. I even managed to create a Wolfenstein style first person shooter in QBasic with some meeting earlier than the tip of the century.
Really not a ray casting engine, however a polygonal 3D engine with horrible affine texture mapping.
However I by no means actually dove into the depths of up to date graphics expertise. And whereas my subsequent skilled profession featured loads of graphics programming, it was largely the GPU accelerated form, not the “fear about every cycle in your internal loops” software program rasterizer form of kind.
(Non-)Objectives
I wish to discover the ins and outs of software program rasterization, ranging from first rules, i.e. getting a pixel on display. From there, I wish to delve into subjects like easy demo results, primitive rasterization, ray casting, voxel terrain, possibly even Quake-style 3D rendering, and no matter else involves thoughts.
Every weblog submit on a subject will lay out the idea the best way I perceive it in hopefully easy phrases, talk about a naive sensible implementation, and at last examine methods to optimize the implementation till it’s moderately quick.
The tip product(s) ought to work on Home windows, Linux, macOS, and customary browsers. Ideally, just a little software program rasterizer library and demos will fall out on the finish, that may serve each for instance implementation of widespread strategies, or as the idea for different demos or video games with DOS sport aesthetics.
You can observe alongside each right here, and by enjoying with the code on GitHub. For every weblog submit, there will probably be one tagged commit within the principal department you’ll be able to try. Along with the render-y bits, I will additionally reveal how I arrange a cross-platform C mission and present you ways I construction, construct, and debug C code in such a mission. I like seeing and studying from different folks’s workflows. Perhaps that is true for you too.
What I don’t wish to do is dabble in issues like meeting or SIMD optimizations. Whereas that may be enjoyable too, it’s unlikely to be needed on in the present day’s {hardware}, provided that I will goal widespread DOS resolutions like 320×240, or 640×480. I would nevertheless examine and talk about the compiler’s meeting output to establish areas that may be improved efficiency sensible within the larger degree code.
Instruments of the commerce
The weapon of alternative will probably be C99 for aesthetic and sensible causes. I would like all of the code produced all through this sequence to compile anyplace. It must also be simple to re-use the code in different languages by means of an FFI. C99 is an effective alternative for each aims.
By way of ompilers, I will be utilizing Clang with MinGW headers and standard libraries on Home windows, Clang by means of Xcode on macOS, and GCC on Linux. Why Clang on Home windows? As a result of Visible Studio is a multi-gigabyte obtain, and establishing builds for it’s a horrible expertise. Clang additionally generates higher code.
I will use CMake because the meta construct device, not as a result of I adore it, however as a result of my favourite C/C++ IDE CLion has firstclass help for it. Different improvement environments perceive CMake as properly lately, together with Visual Studio if that is your kink. For truly executing the builds, I will use Ninja, which is depraved quick, particularly in comparison with MSBuild and consorts.
The pixels we’ll generate have to be thrown up on the show in some way. On Home windows, Linux, and macOS we’ll use MiniFB. In just a few traces of code, we are able to open a window, course of keyboard and mouse enter, and provides it a bunch of pixels to attract to the window. It will possibly even upscale our low decision output if wanted. Since MiniFB doesn’t have browser help, I’ve written an online backend myself and submitted it as a pull request to the upstream repo. Within the meantime, we’ll use my MiniFB fork, which has net help baked in.
To get the code working within the browser, we’ll use Emscripten to compile the C code to WASM and a small .js file, which hundreds the .wasm file and exposes our C capabilities to JavaScript.
By way of IDE, you might be free to make use of no matter you need. You may almost certainly need one thing that may ingest CMake builds. For this sequence, I select VS Code, not as a result of I adore it, however as a result of it is free. The mission accommodates a bunch of VS Code particular settings that make engaged on the mission tremendous easy for all supported platforms.
Getting the supply code and instruments
That is a whole lot of instruments! I’ve tried to make it as easy so that you can observe alongside as potential. Here is what you could set up:
- Visual Studio Code
- Be sure that
codemay be referred to as on the command line! Open VS Code, pressCTRL+SHIFT+P(orCMD+SHIFT+Pon macOS), kindShell Command: Set up 'code' command in PATHand hit enter. - Home windows:
- Git for Windows. Be sure that its obtainable on the command line by way of the system PATH.
- Linux:
- macOS:
As soon as you have put in the above, clone the repository (on Home windows, use Git Bash, which comes with Git for Home windows):
git clone https://github.com/badlogic/r96
cd r96
Subsequent, checkout the tag for the weblog submit you wish to observe together with, execute the instruments/download-tools.sh script:
git checkout 01-babys-first-pixel
./instruments/download-tools.sh
The download-tools.sh script will obtain all remaining instruments which might be wanted, like CMake, Ninja, Clang for Home windows, Python, a small static file server, Emscripten, and Visible Studio Code extensions wanted for C/C++ improvement. See the README.md for particulars.
Notice: we might add new instruments in future weblog posts. After trying out a tag for a weblog submit, be sure to run instruments/download-tools.sh once more.
The r96 mission
These are the targets for the mission scaffold:
- Make constructing and debugging for the desktop and the net trivial.
- Permit including new demo apps that work with out code modification on each the desktop and within the browser
- Make creating re-usable code simple.
Let’s examine how I attempted to realize the above. Open your clone of the r96 Git repository in VS Code and take a look what’s inside.
Notice: The primary time you open the mission in VS Code, you will be requested to pick a CMake configure preset.
Notice: the primary time you open a supply file in VS Code, you can be requested if you wish to set up clangd. Click on Sure.
File construction
Let’s begin within the root folder.
The .gitignore, LICENSE, and README.md recordsdata are self-explanatory.
The CMakeLists.txt and CMakePresets.json outline our construct. We’ll look into these in a later part.
The .clang-format file shops the formatting settings used to format the code by way of, you guessed it, clang-format. The VS Code C/C++ extension makes use of the settings in that file everytime you format a C/C++ supply file. The file will also be used to format your entire code base from the command line.
The src/ folder accommodates our code. Re-usable code goes into src/r96/. Demo apps go into the basis of the src/ folder. There are two demo apps to date referred to as 00_basic_window.c and 01_drawing_a_pixel.c. Any demo apps we write in subsequent weblog posts will even go into src/ and begin with a sequential quantity, so we instantly see during which order they had been written.
The src/net/ folder could also be bizarre, even scary to seasoned C veterans. However we want it to run our demo apps on the internet. A small worth to pay. It accommodates one .html file per demo app. The aim of that file is to:
- Load the
.jsand.wasmrecordsdata generated by Emscripten for the demo app executable goal - Present the demo app with a HTML5 canvas aspect to attract to
- Kick off the demo apps execution by calling its
principal()operate
For any demo app we write sooner or later, we’ll add a supply file to the src/ folder, and a corresponding .html file to the src/net/ folder.
The src/net/index.html file is only a plain itemizing linking to all of the .html recordsdata of our demo apps. The src/net/r96.css file is a CSS fashion sheet used to make the weather within the demo app .html recordsdata just a little prettier.
The .vscode/ folder accommodates settings and launch configurations so engaged on the mission is a pleasant expertise in VS Code.
Lastly, the instruments/ folder accommodates scripts to obtain the required instruments in addition to configuration recordsdata for just a few of these instruments. When executing the instruments/download-tools.sh script, a number of the instruments truly get put in within the instruments/ folder so they do not clog up your system. The folder additionally accommodates scripts and batch recordsdata utilized by the launch configurations to do their work.
The main points of the .vscode and instruments folder are all gory and duct tape-y. You’ll be able to take a look when you should. For the remained of the sequence, their content material would not matter a lot. Simply know that they’re setup in a approach to make our lives simple.
Constructing
The primary time you open the mission in VS Code, you are requested to pick a configure preset.
A configure preset defines for what platform the code ought to be construct and with what compiler and construct flags that ought to occur. The presets are outlined in CMakePresets.json.
For every platform the r96 mission helps, there’s a corresponding debug and launch configure preset. To start out, we’ll choose Desktop debug. You can too choose the configure preset within the standing bar on the backside of VS Code.
To construct the mission for the chosen platform and construct kind (debug or launch), click on the Construct button within the standing bar.
Alternatively, you’ll be able to open the VS Code command palette (CTRL+SHIFT+P or CMD+SHIFT+P on macOS), kind CMake: Construct, and hit enter.
In each circumstances, the CMake Tools extension, which was put in as a part of instruments/download-tools.sh, will configure the CMake construct if needed, then incrementally construct the libraries and executables outlined in CMakeLists.txt.
The ensuing construct output consisting of executables and belongings may be present in construct/<os>-<build-type>. E.g. for Desktop debug, the construct output will probably be situated in construct/windows-debug, construct/linux-debug, or construct/macos-debug relying on what working system you might be on. For Internet launch the output will probably be in construct/web-output, and so forth.
Notice: To study extra about the best way to use VS Code CMake integration, try the documentation.
You’ll be able to in fact additionally construct the mission on the command line:
# Configure a Home windows debug construct and execute the construct
cmake --preset windows-debug
cmake --build construct/windows-debug
# Configure an online launch construct and execute the construct
cmake --preset web-release
cmake --build construct/web-releaseDebugging
The launch.json file within the .vscode/ folder defines launch configurations for every platform. Click on the launch button within the standing bar to pick the launch configuration and begin a debugging session.
After clicking this standing bar entry, you will be requested to pick a launch configuration:
If you first begin a debugging session, you will be requested to pick a launch goal, aka the executable you wish to launch:
You can too change the launch goal within the standing bar:
After choosing the launch goal, the code is incrementally rebuild, and the debugging session begins.
As a substitute of going by means of the standing bar, you may as well begin a brand new debugging classes by urgent `F5`. This can launch a session for the at the moment chosen launch configuration, configure preset, and launch goal.
Vital: the launch configuration MUST match the preset you chose:
Desktop debug goal: choose theDesktop debugorDesktop launchpreset.Internet debug goal: choose theInternet debugorInternet launchpreset.
Debugging a desktop construct is the usual expertise you might be used to. Set breakpoints and watches, interrupt this system at any time, and so forth.
Debugging the C code compiled to WASM instantly in VS Code just isn’t potential. If you begin an online debugging session, the respective launch configuration begins an area static file server (downloaded by way of instruments/download-tools.sh) and opens the .html file akin to the chosen launch goal in a browser tab.
When you find yourself executed “debugging” an online construct, shut the browser tab, and shut the debugging session in VS Code by clicking the “Cease” button within the debugger controls.
In case you really feel adventurous: it’s potential to debug the C and JavaScript code in Chrome.. We’ll look into that under.
Dissecting the CMakeLists.txt and CMakePresets.json recordsdata
To know how the construct is setup, we have to perceive the CMakeLists.txt and CMakePresets.json recordsdata.
We have already had a short have a look at the CMakePresets.json file above. It defines a configure preset for every working system and construct kind mixture. Let’s take a look at one of many presets, particularly, the one used for Home windows debug builds.
{
"identify": "windows-debug",
"displayName": "Desktop debug",
"description": "",
"generator": "Ninja",
"binaryDir": "${sourceDir}/construct/${presetName}",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug",
"CMAKE_MAKE_PROGRAM": "${sourceDir}/instruments/desktop/ninja/ninja"
},
"toolchainFile": "${sourceDir}/instruments/desktop/toolchain-clang-mingw.cmake",
"situation": {
"kind": "equals",
"lhs": "${hostSystemName}",
"rhs": "Home windows"
}
},The essential bits are:
generator: we inform CMake to generate a Ninja construct.binaryDir: specifies the output listing for the construct. On this case it maps toconstruct/windows-debugby means of variable substitution.CMAKE_BUILD_TYPE: tells CMake we wish the binaries to incorporate debugging data.CMAKE_MAKE_PROGRAM: tells CMake had been to search out the Ninja executable. Theinstruments/download-tools.shscript downloaded the executable toinstruments/desktop/ninja/toolchainFile: the place to search out the compiler and linker. On Home windows, we use Clang with MinGW headers and standard libraries., which theinstruments/download-tools.shscript downloads toinstruments/desktop/clang. The toolchain file references the compiler and linker in that location and units up just a few different CMake cache variables.situation: tells CMake to solely allow this configure preset if we’re working on Home windows.
The opposite configure presets are fairly comparable and solely differ in what working system they need to be obtainable on, in addition to the toolchain getting used. On macOS and Linux, the default toolchain is used (GCC or Xcode’s Clang). For the net, the Emscripten toolchain is used by means of a toolchain file that ships with Emscripten.
We might work with out this presets file, however that may imply we would should specify all these parameters manually each time we configure a CMake construct. With the presets, this turns into cmake --preset <preset-name>. A lot nicer!
The CMakeLists.txt file defines the precise construct itself, i.e. which supply recordsdata make up which libraries and executables, and what compiler flags to make use of. Definitions of libraries and executables are referred to as targets in CMake. Let’s undergo it part by part. We begin out with this:
cmake_minimum_required(VERSION 3.21.1)
mission(r96)
set(CMAKE_C_STANDARD 99)
set(CMAKE_C_STANDARD_REQUIRED TRUE)
set(CMAKE_EXPORT_COMPILE_COMMANDS TRUE)
We outline the minimal CMake model and mission identify, and allow (and require) C99 help. The ultimate line makes CMake generate a compile_commands.json file within the construct folder. That is often known as a compilation database and utilized by many IDEs to know a CMake construct. In our case, the file is utilized by the clangd VS Code extension to supply us with code completion and different niceities.
embody(FetchContent)
FetchContent_Declare(minifb GIT_REPOSITORY https://github.com/badlogic/minifb GIT_TAG dos-pr-master)
set(MINIFB_BUILD_EXAMPLES CACHE INTERNAL FALSE)
FetchContent_MakeAvailable(minifb)
Subsequent we pull in MiniFB by way of CMake’s FetchContent mechanism. CMake veterans might sneer at this and quite use a Git submodule. However I prefer it that manner, thanks very a lot. This magic incantation will clone my MiniFB fork with net help, disable the MiniFB instance targets, and at last make the remaining MiniFB library goal obtainable to the targets outlined in our personal CMakeLists.txt. Good.
add_compile_options(-Wall -Wextra -Wpedantic -Wno-implicit-fallthrough)This part units the “pedantic warnings are errors” compiler flags. We would like the code to be moderately clear and fail if a warning is generated.
add_library(r96 "src/r96/r96.c")
Subsequent we add a library goal referred to as r96. It is compiled from the r96/r96.c supply file. Any re-usable code we write through the course of this weblog submit sequence will go in there. Any of our demo app executable targets can then rely upon the r96 library goal to drag in its code.
add_executable(r96_00_basic_window "src/00_basic_window.c")
add_executable(r96_01_drawing_a_pixel "src/01_drawing_a_pixel.c")We outline two executable targets for the demos of this weblog submit.
add_custom_target(r96_web_assets
COMMAND ${CMAKE_COMMAND} -E copy_directory
${CMAKE_CURRENT_SOURCE_DIR}/src/net
$<TARGET_FILE_DIR:r96_00_basic_window>
)
We outline a customized goal that copies all of the .html recordsdata from src/net/ to the output folder. This goal is required for net builds.
get_property(targets DIRECTORY "${_dir}" PROPERTY BUILDSYSTEM_TARGETS)
record(REMOVE_ITEM targets minifb r96 r96_assets r96_web_assets)
foreach(goal IN LISTS targets)
target_link_libraries(${goal} LINK_PUBLIC minifb r96)
if(EMSCRIPTEN)
add_dependencies(${goal} r96_web_assets)
target_link_options(${goal} PRIVATE
"-sSTRICT=1"
"-sENVIRONMENT=net"
"-sLLD_REPORT_UNDEFINED"
"-sMODULARIZE=1"
"-sALLOW_MEMORY_GROWTH=1"
"-sALLOW_TABLE_GROWTH"
"-sMALLOC=emmalloc"
"-sEXPORT_ALL=1"
"-sEXPORTED_FUNCTIONS=["_malloc","_free","_main"]"
"-sASYNCIFY"
"--no-entry"
"-sEXPORT_NAME=${goal}"
)
endif()
endforeach()
After which stuff will get loopy! The primary two traces compiles an inventory of all demo executable targets. We then iterate by means of these executable targets and hyperlink the r96 library goal to every of them. If we construct for the net, we additionally add the customized r96_web_assets goal to the executable as a dependency, so the .html recordsdata get copied over to the output folder.
Lastly, we add just a few Emscripten particular linker choices. These are settings I arrived at after working with WASM for the final 2 years. They’re all Emscripten particular and do issues like permitting heap reminiscence to develop. You’ll be able to try all of the choices in Emscripten’s settings.js file. There’s rather a lot.
The aim of this evil incantation is to scale back the quantity of CMake spaghetti wanted when including a brand new demo. All we have to do is add a single add_executable_target() line, specifiyng the demo identify and supply recordsdata its composed of. The evil incantation will then hyperlink the brand new demo up with all the required bits robotically. Good!
The primary demo app: 00_basic_window
Earlier than we are able to get our palms soiled with programmatically creating essentially the most lovely pixels on the earth, we have to perceive how MiniFB works and the way a demo app is structured when it comes to code. With no additional ado, here is src/00_basic_window.c:
#embody <MiniFB.h>
#embody <stdlib.h>
int principal(void) {
const int res_x = 320, res_y = 240;
struct mfb_window *window = mfb_open("00_basic_window", res_x, res_y);
uint32_t *pixels = (uint32_t *) malloc(sizeof(uint32_t) * res_x * res_y);
do {
mfb_update_ex(window, pixels, res_x, res_y);
} whereas (mfb_wait_sync(window));
return 0;
}
This can be a minimal MiniFB app that opens a window with a drawing space of 320×240 pixels (line 6). It then allocates a buffer of 320×240 unit32_t parts (line 7). Every uint32_t aspect encodes the colour of a pixel. Subsequent, we hold drawing the contents of the buffer to the window by way of mfb_update_ex() (line 9) till mfb_wait_sync() returns false (line 10), e.g. as a result of the person pressed the ESC key to stop the app. It will possibly’t get any less complicated.
MiniFB has a brilliant minimal API. You’ll be able to study extra about it here.
Notice: The mfb_update_ex() operate additionally returns a standing code which can be utilized to determine if the app ought to be exited. We’re not utilizing this above for brevity’s sake.
Working the demo app on the desktop
To compile and run (or debug) our little demo app on the desktop, choose the Desktop debug configure preset within the VS Code standing bar, choose the r96_00_basic_window goal because the launch goal, and the Desktop debug goal launch configuration. Press F5 and you will get this:
r96_00_basic_window on the desktop.
Most spectacular. You can also make adjustments to the code and simply hit F5 once more to incrementally rebuild and restart the demo app. You can too set breakpoints, examine variables and name stacks, and so forth.
Now how can we run the identical demo app within the browser?
Working the demo app on the internet
Choose the Internet debug configure preset, and the Internet debug goal launch configuraton and press F5. You may see this:
r96_00_basic_window working within the browser.
The launch configuration begins a static file server (instruments/net/static-server) which serves the recordsdata in construct/web-debug/ on port 8123. The static server will even robotically open a browser tab with the URL akin to the demo’s .html file.
If you’re executed being amazed by this, shut the browser tab, and click on the Cease button within the debugger controls in VS Code. If you wish to be amazed once more, simply press F5
How the net model works
It is form of magic. Here is how the 00_basic_window.html file for the 00_basic_window.c demo app seems like:
<html>
<!DOCTYPE html>
<html lang='en'>
<head>
<meta charset="utf-8">
<meta http-equiv='X-UA-Appropriate' content material="IE=edge">
<meta identify="viewport" content material="width=device-width, initial-scale=1">
<hyperlink rel="stylesheet" href="https://marioslab.io/posts/rendering-like-its-1996/babys-first-pixel/r96.css">
<script src="r96_00_basic_window.js"></script>
</head>
<physique class="r96_content">
<h2>Primary window</h2>
<canvas id='00_basic_window'></canvas>
</physique>
<script>
async operate init() {
await r96_00_basic_window()
}
init();
</script>
</html>
Ignoring the boring HTML boilerplate, we see that the r96_00_basic_window.js file is loaded by way of a <script> tag. This file was generated as a part of the construct by Emscripten. It accommodates JavaScript code that hundreds the WebAssembly file that shops our compiled C code and exports capabilities with which we are able to work together with the WebAssembly code.
Subsequent we outline a <canvas> with the id 00_basic_window. Lastly, just a little JavaScript kicks of a name to r96_00_basic_window() (outlined in r96_00_basic_window.js) in an asynchronous operate. This name will load the r96_00_basic_window.wasm file and run its principal() methodology.
How does MiniFB know to render to the canvas? In our C code we have now this line:
struct mfb_window *window = mfb_open("00_basic_window", res_x, res_y);
As a substitute of opening a window with “00_basic_window” because the title, the MiniFB net backend makes use of the primary argument handed to mfb_open() to look a canvas aspect with that string as its id. Any calls to mfb_update_ex() will then draw the contents of the offered buffer to this canvas.
Additionally of notice: We did not have to change our C code in any respect, it simply “works”. In case you’ve ever executed any front-end improvement, which may be very bizarre to you. The app principally has an infinite loop! In case you do this in JavaScript, the browser tab (or the entire browser) will freeze, as a result of the browser engine’s occasion loop won’t ever get an opportunity to run and course of occasions. How does this magic work?
The MiniFB net backend I wrote makes use of an Emscripten function referred to as Asyncify. Within the implementation of mfb_wait_sync(), I name emscripten_sleep(0). This provides again management to the browser engine, so it might probably course of any DOM occasions and never freeze. Our native C code will then resume once more, with out our C code ever understanding that it was truly put to sleep. The Asyncify function rewrites our C code (or quite its WASM illustration) to make use of continuations. That permits pausing and resuming the C code transparently. Tremendous cool!
Can I debug the C code within the browser?
Sure, we are able to in Chrome. After we construct utilizing the Internet debug configure preset, Emscripten will emit DWARF data within the ensuing .wasm file. Chrome can use that data to supply native code debugging proper within the developer instruments. To get that working:
- Set up Chrome
- Set up the C/C++ DevTools Support (DWARF) extension in Chrome
- Open Chrome Developer Instruments, click on the gear (⚙) icon within the high proper nook of dev instruments pane, go to the experiments panel and tick
WebAssembly Debugging: Allow DWARF help
- Restart Chrome
Launch the demo app utilizing the Internet debug goal launch config in VS code, then open the dev instruments within the browser, and click on on the Sources tab. Yow will discover all of the .c recordsdata that make up our little demo app beneath the file:// node, together with the MiniFB sources. Open up 00_basic_window.c and set a breakpoint contained in the loop:
C/C++ debugging in Chrome
And there you may have it: C/C++ debugging in Chrome! For the reason that C code runs the identical on each the desktop and within the browser, we’ll probably by no means want this performance, until we implement net particular options.
Talking of options, let’s add a second demo app and draw our first pixel! However first, some very sensible “idea”.
Of colours, pixels, and rasters
What’s a pixel? Rumor has it that pixel is a stylized abbreviation of “(pic)ture (el)ement”. A exact reply is definitely fairly concerned and should even rely upon the last decade you might be dwelling in.
Right here, we lazily and imprecisely outline a pixel because the smallest “atomic” space inside a raster for which we are able to outline a shade. A raster is an oblong space made up of pixels. Every pixel within the raster is assumed to have the identical measurement. The width of a raster equals the variety of pixels in a row, the peak equals the variety of pixels in a column.
The under raster has a width of 23 pixels and a peak of 20 pixels. To find a pixel contained in the raster, we use an integer coordinate system, with the x-axis pointing to the precise, and the y-axis pointing down. The highest left pixel within the raster is at coordinate (0, 0), the highest proper pixel is at coordinate (22, 0) (or (width - 1, 0)), the underside proper pixel is at coordinate (22, 19) (or (width - 1, peak -1)), and so forth.
A raster could be a show gadget’s output space, a bit of grid paper, and so on. The rasters we’ll work with are two-dimensional arrays in reminiscence. Every array aspect shops the colour of the pixel in some encoding.
Shade encodings
We encode the colour of a pixel utilizing the RGBA color model, the place a shade is represented as an additive mixture of its purple, inexperienced, and blue parts, and an extra alpha part specifying the pixel’s opacity. The opacity comes into play once we mix pixels of 1 raster with pixels from one other raster. That is a subject for an additional weblog submit.
Extra particularly, we use an ARGB8888 encoding that matches in a 32-bit unsigned integer (or uint32_t in C). Every shade part is encoded as an 8-bit integer within the vary 0 (no contribution) to 255 (highest contribution). For the alpha part, 0 means “absolutely clear” and 255 means “absolutely opaque”.
Here is how the parts are saved in a 32-bit unsigned integer. Essentially the most vital byte shops the alpha part, then come the purple, inexperienced, and blue bytes.
Listed below are just a few colours in C:
uint32_t purple = 0xffff0000;
uint32_t inexperienced = 0xff00ff00;
uint32_t blue = 0xff0000ff;
uint32_t pink = 0xffff00ff;
uint32_t fifty_percent_transparent_white = 0x80ffffff;Extra typically, we are able to compose a shade by bit shifting and or’ing its particular person parts:
uint8_t alpha = 255; // absolutely opaque
uint8_t purple = 20; // just a little purple
uint8_t inexperienced = 200; // a whole lot of inexperienced
uint8_t blue = 0; // no blue
uint32_t shade = (alpha << 24) | (purple << 16) | (inexperienced << 8) | blue;
That appears like an amazing candidate for a re-usable macro! Why a macro? As a result of C99 help in Microsoft’s C++ compiler remains to be meh and who is aware of the way it does with inlined capabilities outlined in a header. The macro ensures that the code is inlined on the use website. Let’s put the next in src/r96/r96.h
#embody <stdint.h>
#outline R96_ARGB(alpha, purple, inexperienced, blue) (uint32_t)(((uint8_t) (alpha) << 24) | ((uint8_t) (purple) << 16) | ((uint8_t) (inexperienced) << 8) | (uint8_t) (blue))Defining a shade then turns into:
uint32_t shade = R96_ARGB(255, 20, 200, 0);Adressing a pixel in a raster
We now can outline colours simply. However how can we work with rasters in code and manipulate the colours of its pixels? We already did! Bear in mind this line from our 00_basic_window demo app?
const int res_x = 320, res_y = 240;
...
uint32_t *pixels = (uint32_t *)malloc(res_x * res_y * sizeof(uint32_t))
This allocates reminiscence to retailer a 320×240 raster the place every pixel is saved in a uint32_t. Every row of pixels is saved after the opposite. We will consider it as a one-dimensional array storing a two-dimensional raster.
This raster is handed to mfb_update_ex() to be drawn to the window. The explanation the window content material stays black is that the pixels all have the colour 0x00000000 aka black (no less than when constructing the debug variant or for Emscripten).
We will set the pixel within the high left nook at coordinate (0, 0) to the colour purple like this:
pixels[0] = R96_ARGB(255, 255, 0, 0);OK, that was apparent. However how a few pixel at an arbitrary coordinate? Let’s take a look at a smaller 4×3 pixel raster:
Our raster is a one dimensional block of reminiscence. The pixel rows are saved one behind the opposite. The 4 pixels of the primary pixel row with y=0 are saved in pixels[0] to pixels[3]. The index of a pixel within the first row is solely its x-coordinate. E.g. the pixel at coordinate (2, 0) is saved in pixels[2].
The pixels of the second row with y=1 are saved in pixels[4] to pixels[7]. The pixels of the third row with y=2 are saved in pixels[8] to pixels[11]. Basically, the primary pixel of a row at y-coordinate y is situated at pixels[y * width]. And to deal with any pixel inside a row, we simply add its x-coordinate! The final method to go from a pixel’s (x, y) coordinate to an index within the one dimensional array representing the raster is thus x + y * width!
Notice: that is how C implements two-dimensional arrays beneath the hood as properly. The precept additionally applies to larger dimensional arrays.
If we wish to set the colour of the pixel at (160, 120) to purple in our 320×240 pixel raster, we are able to do it like this:
const int res_x = 320, res_y = 240;
...
pixels[160 + 120 * res_x] = R96_ARGB(255, 255, 0, 0);Alright, time to attract some pixels!
Demo app: drawing a pixel
Drawing a single pixel is a bit boring, so how about we flood the display with a gazillion pixels as a substitute?
#embody <MiniFB.h>
#embody <stdlib.h>
#embody <string.h>
#embody "r96/r96.h"
int principal(void) {
const int res_x = 320, res_y = 240;
struct mfb_window *window = mfb_open("01_drawing_a_pixel", res_x, res_y);
uint32_t *pixels = (uint32_t *) malloc(sizeof(uint32_t) * res_x * res_y);
do {
for (int i = 0; i < 200; i++) {
int32_t x = rand() % res_x;
int32_t y = rand() % res_y;
uint32_t shade = R96_ARGB(255, rand() % 255, rand() % 255, rand() % 255);
pixels[x + y * res_x] = shade;
}
if (mfb_get_mouse_button_buffer(window)[MOUSE_BTN_1]) {
memset(pixels, 0, sizeof(uint32_t) * res_x * res_y);
}
mfb_update_ex(window, pixels, res_x, res_y);
} whereas (mfb_wait_sync(window));
return 0;
}
The fascinating bit occurs in traces 11 to fifteen. Every body, we generate 200 pixels at random coordinates with random colours. We make sure that the coordinates are throughout the raster bounds by % res_x and % res_y. We additionally clamp the colour parts to the vary 0-255 by way of modulo.
We additionally introduce some mild enter dealing with by checking if the left mouse button is pressed. In that case, we set all pixels to the colour black, giving the “person” a approach to restart the fantastic demo.
Lastly, we move the pixels to mfb_update_ex(), which is able to draw them to the window.
And right here it’s stay in your browser, as a result of why would we spend a lot time getting the WASM construct to work so properly. Click on/contact to start out!
I certain really feel all this construct up paid off, do not you?
Mario, WTF
Yeah, I am sorry. I generally simply drift off. However we discovered rather a lot! Subsequent time I probably will not be so wordy. We’ll have a looksy at how to attract rectangles. Thrilling!
Learn the the next article in the series.