Lightweight Terminal Media Library, or LWTML for short, is a small C++ library that makes it easy to output simple graphics to a supported terminal emulator. It also provides non-blocking keyboard input and timing - both useful in soft-realtime interactive applications and games.

Surely, much more advanced and feature-rich media libraries exist and I can only wholeheartedly suggest the use of something like SDL or SFML for interactive media development. However, LWTML was developed primarily as a personal learning experience, and for fun! I also frequent /r/unixporn and /r/commandline, and find small quirky command-line tools interesting. I'm also interested in game-development, and see a terminal emulator as a platform for presenting very low-fi graphics - only consoles from the 8-bit generation come close in fidelity.

Game development - small games like packman, pong, tetris, rogue-likes. Old-school demos, generate fractals, simulate Game Of Life, or just rice your desktop with it (the good people on /r/unixporn are especially creative in this regard). Here are some examples of how programs using LWTML might look like:

Note that those are just lame demos I quickly threw together. Also, the refresh rate of the gifs are terrible.

Sure, you can do that - no hurt feelings. I do aim to make it easier to get started using my library compared to ncurses. Ncurses is great, but it has gained some "weight" over the years, meaning a lot of boilerplate code is necessary to get started using it.

The state of the library is still pretty much beta: it has only been tested on OS X at the moment, the interface might change, the makefile and install proceedure is crude - so please use it at your own risk. Contributions are welcome - bug reports, feature requests, you name it. Also, if you create something using the library, be sure to shoot me a message as I would be excited to see what you have cooked up.

Compile and install the library:

    make && sudo make install

Do note that the last step requires root access and installs headers to /usr/local/include and the library to /usr/local/lib. If you rather not have that happen, you can make gcc/clang search for the library and headers elsewhere using:

    clang++ ... -L<path_to_lib> -I<path_to_headers> -lLWTML -o ...

If you did make install you just include the LWTML headers and link against LWTML when compiling:

    clang++ <your_program>.cpp -lLWTML -o <your_program>

And here is a sample of a program using LWTML:

    #include <LWTML/LWTML.hpp>
    
    int main(int argc, char** argv){
        Renderer renderer;
        Keyboard keyboard;
        Bitmap bitmap(renderer.width(), renderer.height());
        Timer timer;
        while(true){
            timer.update();
            keyboard.update();
            if(keyboard.is_key_down('q'){
                  break;
            }
            for(int y = 0; y < bitmap.height(); y++){
                  for(int x = 0; x < bitmap.width(); x++){
                        /* do some fancy stuff */
                  }
            }
            renderer.blit(&bitmap);
            timer.lock_at_fps(30);
        }
        return 0;
    }

This is a rather dull example, but should get you started.

At the moment it's only tested on and made to work on OS X, but making it work on GNU/Linux is simply a matter of using the correct compile flags, which I'll get to in the near future. It will probably never support Windows. I don't own any version of Windows, so I can't really develop for it without too much hassle.

Know bugs, a few yes, and there are probably a whole slew of bugs that I don't know of yet.

Known bugs:

• The iTerm2 terminal emulator for OSX seems to be significantly slower at refreshing the display compared to urxvt under X11. You will probably get something near 10-15fps in iTerm2 compared to ~200fps in urxvt. I'm not sure this is something I have control over, and I assume this has to do with the implementation of iTerm2.
• There is currently an interface for rendering normal ascii text. It does not work properly in iTerm2.

• Proper namespacing. Considered candidates: LWTML::, lwtml:: or lw::.
• Convinient classes such as Rect, Point, etc.
• Proper error handling.
• Double buffering for the renderer. As of now, blittet bitmaps are just spilled directly into the terminal.
• Loading of PNGs to internal bitmaps.
• Persistent valuestore, similar to Unity3d's PlayerPrefs.
• ...