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.
- ...