# Reversed-Z Rendering in OpenGL

By default the OpenGL 3D normalized device coordinates (NDC) are between -1 and +1. x is from left to right and y is from bottom to top of the screen while the z-axis is pointing into the screen.

Usually the 3D camera coordinates of the object are mapped such that near coordinates are mapped to -1 and far values are mapped to +1. The near and far plane define the nearest and farthest point visualized by the rendering pipeline.

The absolute accuracy of floating point values is highest when the values are near zero. This leads to the depth accuracy to be highest somewhere between the near and far plane which is suboptimal.

A better solution is to map near coordinates to 1 and far coordinates to 0. In this case the higher precision near zero is used to compensate for the large range of distances covered towards the far plane.

Let x, y, z, 1 be the homogeneous coordinate of the 3D point and x’, y’, z’, w’ the homogeneous NDC. Normally the 3D point uses a right-handed coordinate system where the z-axis points out of the screen.

This means that x and y are projected using negative z, i.e. w’ = -z.

The camera projection equations are x’/w’ = fw x/-z and y’/w’ = fh y/-z.

Substituting w’ = -z we get x’ = fw x and y’ = fh y.

Setting z’ = a + b z we get the following matrix equation:

When z = -near, we want z’/w’ = 1.

When z = -far, we want z’/w’ = 0.

For z = -near we get: z’ = w’ => a + b z = -z => a - b near = near.

For z = -far we get: z’ = 0 => a + b z = 0 => a - b far = 0 <=> b = a / far.

Substituting b we get: a - a near / far = near <=> a = near far / (far - near)

This means b = a / far = near / (far - near).

I.e. we get:

and

Finally we set fw = 1 / tan(fov / 2) where fov is the horizontal field of view angle (e.g. 60 degrees in radians).

fh then needs to be chosen such that fh / fw = w / h, where w and h are the width and height of the screen.

# Installing Debian 11 (bullseye) on a physical machine

This is a summary on how to install Debian on a physical machine (as opposed to a VM).

I installed Debian 11 with KDE desktop on my HP 255 G3 notebook.

Because my computer has an AMD GPU it is recommended to download the unofficial Debian image with firmware. The unofficial image also helps with Wireless adapters which frequently require proprietary firmware. I downloaded the image which is 4 GByte in size and wrote it to a USB stick:

Replace `/dev/sdb` with your correct USB location! You can see the location in the log (run `sudo dmesg`) after plugging it in. Under Windows you can use a tool such as Rufus to create a bootable USB stick.

I usually create a list of packages of my current system so that I can later install the same packages on the new system.

I rebooted the computer. My laptop uses UEFI secure boot so you need to press Escape and then F9 to get a list of bootable devices. The Debian installer image on the USB stick should show up in the list. Select it and press return. I proceeded to use the graphical installer.

The Debian installer can shrink Windows partitions if you want to set up dual boot. Note that you need to disable Windows fast startup, otherwise your Windows file system will be in a hibernated state.

On my machine I created a swap partition about the same size as the computer memory. I already have a 16 GByte root (`/`) ext4 partition (should be a bit bigger ideally) and a large home (`/home`) ext4 partition. I just format the root partition and simply mount the home partition without formatting. After setting up the users I can already continue using the system.

I noticed that even the unofficial image is missing some firmware. So I cloned the Linux firmware repository and copied the firmware files:

I then proceeded with the instructions on how to set up Plymouth boot splash.

Furthermore I added deb-multimedia.org to the package sources and updated the multimedia software.

Finally a few more tweaks:

• I installed plasma-browser-integration and the corresponding browser addon (available for Firefox and Chrome/Chromium)
• I installed ffmpegthumbs and kdegraphics-thumbnailers and then enabled the thumbnail generators in the Dolphin settings
• I installed bleachbit and run it to clean up unused disk space
• You can reduce the system swappiness to 10
• In the BIOS I was able to change the order of the UEFI boot files so that Debian/Grub is started by default

I hope this installation summary is useful to you! Enjoy!

# Tessellation OpenGL example using Clojure and LWJGL

Last week I published a minimal OpenGL example in Clojure. The example was implemented using LWJGL version 2 (see LWJGL Wiki for documentation). My motivation is to implement a space flight game, which requires rendering of planetary bodies. I found an impressive free software called the Oreon Engine which is implemented in Java. Watching the videos I realised that I should investigate tessellation shaders. I didn’t find any small single-page code examples for tessellation shaders, so I decided to publish one here. The example is implemented in Clojure but could be easily ported to C if you prefer.

The example uses several shaders required when doing tessellation using OpenGL:

The example not only shows how to set the tessellation level but it also shows how one can pass through texture coordinates. The polygon mode was switched to display lines only so that one can observe how the triangle is split up.

See code below:

Any feedback, comments, and suggestions are welcome.

Enjoy!

# Minimal OpenGL example in Clojure

Two years ago I published a minimal OpenGL example in C. Recently I got renewed interest in the Clojure programming language (if you want to learn Clojure, I can recommend the book Clojure in Action by the way). I hope to do some game development in Clojure. Initially I tried JOGL (Java Bindings for OpenGL), but then I switched to LWJGL version 2 (Lightweight Java Game Library). There is a Debian package for LWJGL version 2 and there is extensive documentation on the LWJGL Wiki. Using this library, I have translated my earlier example to Clojure. See code below:

You can run the code as follows:

Any feedback, comments, and suggestions are welcome.

Enjoy!

# The MealMaster file format

The MealMaster file format (*.MMF or *.MM file) is a popular file format for sharing recipes. MealMaster is the file format introduced by the MealMaster software developed by Episoft Systems.

The website of Episoft Systems, which provided the original MealMaster software for DOS, is not online any more. Fortunately a copy of the website is still available on the Internet Archive.

#### One-column format

Below follows an example of the one-column MealMaster format (the ingredients are listed in a single column).

``````MMMMM----------------Meal-Master recipe exported by AnyMeal-----------------
Title: Fruit-Meringue-Pie
Categories: pastries,cakes
Servings: 1 pie

MMMMM----------------------------sponge mixture-----------------------------
150 g  soft butter
150 g  sugar
3    eggs
150 g  flour
1 ts baking powder
MMMMM-------------------------------meringue--------------------------------
4    egg white
150 g  sugar
50 g  almond leaves
MMMMM-------------------------------filling---------------------------------
370 g  sour cherries;dripped off (
-1 glass)
1 1/2 tb cornflour
1/4 l  cherry juice
250 g  cream
1 tb sugar
1 pk stabiliser

Butter spring form with butter paper. Preheat oven to 200°.

MMMMM----------------------------sponge mixture-----------------------------
Stir butter, sugar and eggs until foamy, mix flour and baking powder and stir
in. Fill dough in in two spring forms and smooth down. Pre-bake for 15
minutes.

MMMMM-------------------------------meringue--------------------------------
Beat egg white until stiff and let sugar trickle in spoon by spoon. Beat
until stiff. Spread meringue base on pre-backed flan bases. Scatter almond
leaves over them. Bake for further 10-15 minutes. Let flan bases cool down on
a grid.

MMMMM-------------------------------filling---------------------------------
For the filling mix cornflour with some cherry juice. Bring remaining juice
to boiling point, stir in cornflour and boil up. Mix in sour cherries, let
cool down a bit and spread over one flan base.

Beat cream with sugar and stabiliser until stiff, spread over filling.
Cut second flan base in 12 pieces and reassemble on top of the filling. Let
cool down well.

MMMMM
``````

The recipe header begins with MMMMM or —–. The header also has to contain the word “Meal-Master”. The recipe content then starts with a title of up to 60 characters. Then a list of categories follows. Each category can have up to 11 characters. Then servings amount and unit are specified.

In this recipe there are three ingredient sections. An ingredient section starts with MMMMM or —–. Ingredient amounts are specified in column 1 to 7. Column 9 and 10 specify the unit token. Starting from column 12 ingredient text of up to 28 characters follows. If the ingredient text is longer than 28 characters, it is broken up using ingredient continuation lines. Ingredient continuation lines begin with a “-“ in column 12.

Finally the instruction text follows. The instruction text also can be split up into multiple sections starting with MMMMM or —–. The recipe ends with MMMMM.

#### Two-column format

Here is an example of the two-column format. The ingredients are listed in two columns.

``````---------- Recipe via Meal-Master (tm) v8.01

Title: Cannoli
Categories: Italian, Desserts
Yield: 16 servings

----------------------------------FILLING----------------------------------
1 1/2 c  Whole-milk ricotta cheese;      1 1/2 c  Milk chocolate;
- well drained                           - coarsely chopped
3 tb Sugar                             1/4 c  Pistachio nuts;
1 1/2 ts Cinnamon                                 - coarsely chopped

-----------------------------------DOUGH-----------------------------------
1 c  All-purpose flour                        - or dry white wine
1 tb Sugar                               2 c  Vegetable oil
1 tb Butter or lard                           Colored sprinkles
4 tb To 5 Tbl sweet Marsala wine

In a bowl, combine all the filling ingredients and mix well. Refreigerate,
covered, until ready to fill the cannoli shells.

To make the dough, place the flour in a bowl or food processor. Add the
butter or lard and sugar and mix with a fork, or pulse, until the mixture
resembles coarse meal. Slowly add the 1/4 cup of wine and shape the mixture
into a ball; add a little more wine if the dough appears too dry. It should
be soft but not sticky. Knead the dough on a floured surface until smooth,
about 10 minutes.  Wrap the dough and refrigerate for 45 minutes.

Place the chilled dough on a floured work surface. Divide the dough in
half.  Work with 1 piece of dough at a time; keep the remaining dough
refrigerated. Roll the dough out to a very thin long rectangle about 14
inches long and 3 inches wide, either by hand or using a pasta machine set
to the finest setting.  Cut the dough into 3-inch squares. Place a cannoli
form diagnoally across 1 square. Roll the dough up around the form so the
points meet in the center.  Seal the points with a little water. Continue
making cylinders until all the dough is used.

In an electric skillet, heat the vegetable oil to 375F. Fry the cannoli 3
or 4 at a time, turning them as they brown and blister, until golden brown
on all sides. Drain them on brown paper. When they are cool enough to
handle, carefully slide the cannoli off the forms.

To serve, use a long iced tea spoon or a pastry bag without a tip to fill
the cannoli with the ricotta cheese mixture. Dip the ends into colored
sprinkles, arrange them on a tray, and sprinkle confectioner's sugar over
the tops.  Serve at once.

NOTE:  If you prefer, you can fry the cannoli in a deep fryer. Be sure to
fill the cannoli just before serving - any sooner will make the shells
soggy.

This recipe from CIAO ITALIA by Mary Ann Esposito

-----
``````

Here “Yield” is used instead of “Servings”. Note that the order of ingredients in each section is column major. In this example the second ingredient section has a second column starting with an ingredient continuation line. I.e. it is continuing the last ingredient of the first column.

This example also shows instruction text being indented by two spaces. Empty lines are used to create paragraphs.

The recipe ends with —–.

Not shown in these examples is to use an instruction line beginning with a “:” to force a line break.

#### Units

The following table shows the meaning of each of the unit tokens:

special tokens
x "per serving" (quantity not to be scaled)
placeholder (no unit)
metric unit of volume
mlmilliliter (0.001 liter)
clcentiliter (0.01 liter)
dldeciliter (0.1 liter)
l liter
metric unit of weight
mgmilligram (0.001 gram)
cgcentigram (0.01 gram)
dgdecigram (0.1 gram)
g gram
kgkilogram (1000 gram)
U.S. unit of volume
flfluid ounce (1/128 gallon or 28.4130625 milliliter)
ptpint (1/8 gallon or 473.176473 milliliter)
qtquart (1/4 gallon or 0.946352946 liter)
gagallon (3.785411784 liter)
U.S. unit of weight
ozounce (1/16 pound or 28.34952312 gram)
lbpound (453.59237 gram)
unprecise unit of volume
drdrop (1/64 teaspoon)
dsdash (1/8 teaspoon)
pnpinch (1/16 teaspoon)
tsteaspoon (1/6 fluid ounce or 4.928921595 milliliter)
tbtablespoon (1/2 fluid ounce or 14.7867647825 milliliter)
c cup (8 fluid ounces or 236.5882365 milliliter)
unprecise description of size
smsmall
mdmedium
lglarge
unprecise description of quantity
cncan
pkpackage
ctcarton
slslice
bnbunch
alternate tokens
ea"each" (deprecated placeholder)
cbcubic centimeter (1 milliliter)
t teaspoon
T tablespoon

#### Grammar

Here is an ABNF grammar of the MealMaster file format:

``````Mealmaster   = recipe Mealmaster
/ *( VCHAR / SP ) eol Mealmaster
/
recipe       = header title categories servings ingredients instructions footer
header       = separator *( VCHAR / SP ) "Meal-Master" *( VCHAR / SP ) eol
title        = '     Title: ' 0*60( VCHAR / SP ) eol
categories   = 'Categories: ' categlist eol
categlist    = 1*11( VCHAR / SP ) ["," categlist]
servings     = '  Servings: ' 1*4( DIGIT ) [ SP [ 1*10( VCHAR / SP ) ] ] eol
ingredients  = onecolumn
/ twocolumn
onecolumn    = section onecolumn
/ ingredone eol onecolumn
/ *( SP ) eol onecolumn
/
twocolumn    = section twocolumn
/ ingredtwo SP ingredone eol twocolumn
/ ingredone eol [ *( eol ) section twocolumn ]
/
ingredone    = amount SP unit SP 1*28( VCHAR / SP )
ingredtwo    = amount SP unit SP 28( VCHAR / SP )
amount       = 7( SP / DIGIT / "." / "/" )
unit         = 'x ' / 'sm' / 'md' / 'lg' / 'cn' / 'pk' / 'pn' / 'dr' / 'ds'
/ 'ct' / 'bn' / 'sl' / 'ea' / 't ' / 'ts' / 'T ' / 'tb' / 'fl'
/ 'c ' / 'pt' / 'qt' / 'ga' / 'oz' / 'lb' / 'ml' / 'cb' / 'cl'
/ 'dl' / 'l ' / 'mg' / 'cg' / 'dg' / 'g ' / 'kg' / '  '
instructions = 0*255( VCHAR ) eol instructions
/ section instructions
/
section      = separator *( VCHAR / SP ) eol
footer       = separator eol
separator    = 'MMMMM'
/ '-----'
eol          = [ CR ] LF
``````

The grammar uses several rules from the ABNF standard:

• / is used to specify alternative rules.
• VCHAR stands for any printable character (except whitespace)
• DIGIT is a digit (one of 0,1,2,3,…,9).
• SP is the space character.
• CR means carriage return (0x0D).
• LF is the line-feed character (0x0A).
• *( VCHAR / SP ) means any number of printable and space characters or no characters at all.
• 1*4( DIGIT ) is used to specify one to four digits.
• [ CR ] is an optional carriage return character.
• 5( ‘M’ ) is exactly 5 capital “M”-characters.

#### Conclusion

The MealMaster file format is quite difficult to parse. Also there are a few problems with the file format:

• It is not possible to protect a comma in a category-name from interpretation as a separator.
• To prevent an occurrence of —–, : or MMMMM in the instructions-text from being interpreted as a special token, some recipe applications prepend all instruction lines with two space characters, which need to be ignored during import.
• The original Mealmaster software will refuse to import recipes exceeding a certain size. Also overlong titles, categories, and servings will be cropped.
• There are many recipes with ingredient-text longer than 28 characters. Overlong ingredient lines are making it more difficult to distinguish between the one- and two-column format.
• The ending of the ingredient section is not defined properly.
• Some recipe applications are relying on an empty line separating the ingredients from the instructions. On the other hand the original Mealmaster application allows empty lines within the ingredient-section.
• There are recipe applications exporting MealMaster files containing categories with more than 11 characters.

I hope this description will be useful to you if you are trying to parse MealMaster recipes. Please let me know any feedback in the comment section below.