UP | HOME

MRaster Quick Start
Linux/UNIX/Msys2/Cygwin/OSX

Copyright © 2023 Mitch Richling. All rights reserved.

Table of Contents

1. Quick Start (The Absolute Minimum)

If you are interested playing around with MRaster as quickly as possible, then this section is for you.

The first step is to download MRaster. You can grab the zip file, or you can simply clone the repository with GIT like this: 

git clone 'https://github.com/richmit/mraster.git'

Once you have it downloaded, make note of the "lib" folder within the repository. This folder contains everything you need to develop with MRaster, and you can simply put your code right in that directory. So let's create a file called "hello.cpp" right inside the "lib" directory with the following content: 

#include "ramCanvas.hpp"                                                     // The main MRaster include

int main(void) {
  mjr::ramCanvas3c8b theRamCanvas(1024, 1024);                               // Create a canvas object
  for(int y=0;y<theRamCanvas.getNumPixY();y++)                               // Run over the rows 
    for(int x=0;x<theRamCanvas.getNumPixX();x++)                             //   and columns of the image
      theRamCanvas.drawPoint(x, y, mjr::color3c8b::csCColdeRainbow::c(x+y)); // Pick a "rainbow" color for the point
  theRamCanvas.writeTIFFfile("hello.tiff");                                  // Write out our image to disk
}

Now we can compile it with GCC like this: 

g++ -m64 -std=gnu++20 hello.cpp -o hello2

Now you can run it, and take a look at the file it created ("hello.tiff"):

hello.png

That's it! How easy was that?

1.1. FAQ for people not using cmake

1.1.1. Q1: How do I get advanced TIFF reader support without cmake?

A: If you have libtiff installed in a standard location, then you can probably just add "=-DTIFF_FOUND" to the compile command like this: 

g++ -DTIFF_FOUND -m64 --std=gcc++20 hello.cpp -o hello

Please note that advanced TIFF reader is only required to read TIFF files. MRaster can save TIFF, TGA, and MRAW files without any external library support.

1.1.2. Q2: What's up with "-std=gcc++20" instead of "-std=c++20"?

A: MRaster works just fine with standard C++20 compilers. The "-std=gcc++20" option enables specific features of GCC that make MRaster better. In particular, it enables 128-bit integers on platforms that support it – allowing, for example, a very high performance floating point RGBA image format. If you want to turn off 128-bit integers, and use pure C++20 instead with GCC, then you can use a command line like this: 

g++ -DMJR_LOOK_FOR_128_BIT_TYPES=0 -m64 --std=c++20 hello.cpp -o hello

1.1.3. Q3: I got some weird errors about bit_cast. What's up?

Probably your compiler is too old to support that part of the C++ standard. One of the advantages of using cmake is that it tries to detect this issue. Without cmake, you need to add the following to your compile command (or get a better compiler): 

-DMISSING_P0476R2=1

1.1.4. Q4: I got some weird errors about complex numbers and std::pow? What's up?

Probably your compiler is too old to support that part of the C++ standard. One of the advantages of using cmake is that it tries to detect this issue. Without cmake, you need to add the following to your compile command (or get a better compiler): 

-DMISSING_P1907R1=1

2. Playing With MRaster's Example Programs

The source code for the example programs is located in the "examples" directory. MRaster ships with a cmake build system that should be able to interrogate your environment, and produce make files for your OS. To build the example programs:

  1. Change directory to the root of the git repository (you should see "lib" & "examples" directories.
  2. Create a "build" directory – cmake builds outside of the source trees.
  3. Change directory to the build directory
  4. Use cmake to generate make files for your system
  5. Build the examples
  6. Play with the examples

A typical shell session following the steps outlined above might look like this: 

rm -rf build
mkdir build
cd build
cmake -G 'MSYS Makefiles' ..    # For Windows running MSYS2.  Remove the "-G 'MSYS Makefiles'" bit for other platforms.
make

Note cmake can take several options like the "-G" option mentioned in the example above. For more information on options related to MRaster, take a look at the "configure.sh" script in the root directory of the git repository.

3. Using MRaster's cmake Configuration

For many MRaster users, cmake is an unfamiliar tool. Some of them decide to directly use MRaster's cmake infrastructure, using the "examples" directory as a template for the code they produce. This can be a nice way for people new to cmake to get an idea of how it works; however, I have to warn you: I'm really a cmake novice! You might just pick up some cmake bad habits looking at my CMakeLists.txt file! :)

If you want to use the MRaster cmake infrastructure, the easiest path is to put your code in the "examples" directory. Next we need to add your code to the "CMakeLists.txt" file. Look for lines like these: 

set(TARGETS_REQ_NONE   "apollony" "apomorph"  ...
set(TARGETS_REQ_MRRL   "color_lut_indexed" "color_lut_rainbows"  ...
set(TARGETS_REQ_OPENGL "glut_image")
set(TARGETS_REQ_TIFF   "brownianDiffusion" "dlaBrownian"  ...
set(TARGETS_REQ_OPENMP "mandelbrot_bm_cplx_openmp")
set(TARGETS_REQ_BTEST  "utest_foo" "utest_color_types_ia64nGCC"  ...
set(TARGETS_REQ_PNG    )
set(TARGETS_REQ_IM     )

Each of these lines are a list of source files that require various external dependencies. In general you should always add your source file (minus the ".cpp" extension) to the "TARGETS_REQ_MRRL" list. If your program needs the advanced TIFF reader, then also add it to the "TARGETS_REQ_TIFF" list as well. Now we are ready to go:

  1. Create a directory called "build" in the root of the git repository
  2. Change directory the "build" directory
  3. Use cmake to generate make files
  4. Build your program!

These steps might look like this: 

rm -rf build
mkdir build
cd build
cmake -G 'MSYS Makefiles' ..
make your_program

4. Platform Notes

I write these notes on 2022-08-28 as a guide for making the most of MRaster on various platforms given the rather uneven nature of C++20 support in the wild. I expect these notes will be out of date by the time I hit the publish button. ;)

4.1. Windows 11 with MSYS2 GCC 12.1.0

Everything works with the following cmake: 

cmake -G 'MSYS Makefiles' -DCMAKE_CXX_COMPILER=g++ ..

4.2. Windows 11 with MSYS2 clang 14.0.6

Everything works with the following cmake: 

cmake -G 'MSYS Makefiles' -DCMAKE_CXX_COMPILER=clang++ ..

4.3. Windows 11 with MSYS2 cmake and Visual Studio 2022 Community Edition

This method works, but you won't get any external dependencies like GLUT, SDL2, libTIFF, boost, etc… But, you will get enough to run many of the examples.

From the MSYS2 shell, we can run cmake like this: 

cmake -G 'Visual Studio 17 2022' ..

Then open up the directory with explorer, and double click on one of the project files. That will open up VS, and you can work the project.

4.4. Windows 11 with Visual Studio 2022 Community Edition

Everything works, but it's harder to get set up. Simply fire up VS, and open the folder with the CMakeLists.txt file in it. VS will detect a cmake project. Next use vcpkg to install GLUT, SDL2, libTIFF, & boost. Update CMakeLists.txt as described here. Refresh the cmake, and you should be able to build.

4.5. Mac OS X Monterey 12.5.1 with Homebrew GCC 12.1.0

I had trouble getting boost to work, but everything else seems OK. Note the -DGLUT_glut_LIBRARY option – this is required to direct cmake to use the Apple provided GLUT instead of freeglut from homebrew.

Here is what I installed via Homebrew: 

brew install gcc
brew install cmake
brew install sdl2
brew install doxygen
brew install libtiff
brew install boost

And I used the following cmake: 

cmake -DCMAKE_CXX_COMPILER=g++-12 -DGLUT_glut_LIBRARY=/System/Library/Frameworks/GLUT.framework ..

4.6. Mac OS X Monterey 12.5.1 with Apple clang 13.1.6

Right now clang doesn't have support for floating point template parameters, and thus the templates csPLY_tpl & csCubeHelix_tpl are not available. This also means that examples using these features are not built:

  • color_lut_poly.cpp
  • color_lut_docs.cpp
  • color_lut_cubehelix.cpp
  • heart2022.cpp

In addition, the Apple version of clang is missing the C++20 feature bit_cast. Right now MRaster has conditional compilation sections removing those features when using this compiler. Hopefully Apple will have better C++20 support soon.

Lastly, note the -DGLUT_glut_LIBRARY option – this is required to direct cmake to use the Apple provided GLUT instead of freeglut from homebrew. 

cmake -DCMAKE_CXX_COMPILER=clang++ -DGLUT_glut_LIBRARY=/System/Library/Frameworks/GLUT.framework ..

4.7. Debian bullseye 11.4 with GCC 10.2.1

This is the stock compiler that comes with bullseye. It's a bit old, and is missing support for both floating point template arguments and bit_cast.

You can install everything you might want for MRaster like so: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick
sudo apt install cmake/bullseye-backports

Now you can use the following cmake command: 

cmake ..

4.8. Debian bullseye 11.4 with GCC 11.3

With this newer compiler all MRaster features are supported.

This is the compiler currently in the bullseye testing channel for 11.4

Here is my /etc/apt/sources.list file: 

deb http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://security.debian.org/debian-security bullseye-security main
deb http://ftp.debian.org/debian bullseye-backports main

deb http://mirrors.xmission.com/debian/ testing main non-free contrib
deb http://http.us.debian.org/debian testing main contrib non-free
deb http://ftp.us.debian.org/debian testing main non-free contrib

Here is my /etc/apt/preferences file: 

Package: *
Pin: release a=testing
Pin-Priority: 490

You can install everything with the following: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick
sudo apt install cmake/bullseye-backports
sudo apt install -t testing g++-11 gcc-11

Now you can use the following cmake command: 

cmake -DCMAKE_CXX_COMPILER=g++-11 ..

4.9. Debian bullseye 11.6 with GCC 12.2

With this newer compiler all MRaster features are supported.

This is the compiler currently in the bullseye testing channel for 11.6

Here is my /etc/apt/sources.list file: 

[sudo] password for richmit:
deb http://deb.debian.org/debian bullseye main
deb-src http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://security.debian.org/debian-security bullseye-security main


deb http://deb.debian.org/debian testing main
deb-src http://deb.debian.org/debian testing main

Here is my /etc/apt/preferences.d/prefs.pref file: 

Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 400

You can install everything with the following: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick
sudo apt install -t testing --install-suggests gcc-12 gfortran-12 cmake

Now you can use the following cmake command: 

cmake -DCMAKE_CXX_COMPILER=g++-11 ..

5. FAQ

5.1. Q1: What's up with "-std=gcc++20" instead of "-std=c++20"?

A: MRaster works just fine with standard C++20 compilers. The "-std=gcc++20" option enables specific features of GCC that make MRaster better. In particular, it enables 128-bit integers on platforms that support it – allowing, for example, a very high performance floating point RGBA image format. If you want to turn off 128-bit integers, and use pure C++20 instead with GCC, then you can use a command line like this: 

g++ -DMJR_LOOK_FOR_128_BIT_TYPES=0 -m64 --std=c++20 hello.cpp -o hello

5.2. Q2: The examples seem to be missing standard/system include files

A: It is good form to place necessary includes in each file that needs them; however, I have violated this sound practice in the examples shipped with MRaster. In particular, because the ramCanvasTpl.hpp and colorTpl.hpp files include just about everything the examples need I have tended to shorten up the examples and depend on the includes from these headers.