Revision:
2010/12/11 First version of the reference
This framework is copyrighted to CaptainYS. But, this framework is open source. When I say open source, I mean it. You can use it for any purposes, commercial, private, internal, open source, or proprietary as long as you take responsibility for the consequence. (If you use it for an illegal purpose, the police will come to you! Whatcha gonna do when they come to you? So, don't use it for an illegal purpose.) You can cut & paste some part of the code and use in your program. If you want to reverse-engineer, sure, go ahead! That's the way you learn programming. Only condition is you are responsible, and I will NOT take any responsibility for the consequence of using this framework. If you do not agree with this condition, please do not use this framework. Of course, I will be happy if you let me know about your interesting projects with this framework.
Web site http://www.ysflight.com
E-Mail PEB01130[A]nifty.com (Please replace [A] with @)
This framework gives you a set of functions that opens an OpenGL enabled window, and take key strokes, mouse input, and sub-second timer. The framework is available for Mac OSX, Windows, and Linux.
Whole point of this framework is to give you full control of your program. This framework doesn't ask you to surrender your main loop. You write main loop. However, not to overheat your CPU, or over-stress your CPU cooling fan, I recommend you to give some sleeping time to your CPU, like 20ms per iteration.
Event-driven programming is good for some applications. But, when you want to write a quick test program, event-driven programming is evil. There is nothing wrong with polling-based programming, which you can do with this framework.
fssimplewindow.h
This header file must be included to use this simple window framework. The include path must be added to the location where this file is stored, or this file needs to be copied to the location where the include path is pointing.
This package also includes the bitmap-font library. To use the bitmap-font library, please see the reference.
The following source files need to be added to the project to use this simple window framework.
If you are familiar with a makefile, makefiles in the samples directory will tell you everything. It is easy and simple. I'm a minimalist. I like to keep things simple. For each sample code, there are three makefiles, makefile.win, makefile.mac, and makefile.glx, which can be used in Windows (in Visual Studio Command Prompt), Mac OS X (from the terminal), or Linux, respectively.
In Windows, you can open "Visual Studio Command Prompt", which you can find in the same folder in the start menu. In Windows 7, you may be able to find by searching by the keywords "Visual Studio Command Prompt". It is so easy in Windows XP to get there. Windows 7's interface is very inefficient. It forces you to search things even when you know exactly where it is. Anyways, if you are lucky enough to find it, open it, and change directory to one of the samples. Then type:
nmake -f makefile.win
If you want to clean it, type:
nmake -f makefile.win cln
In Mac OS X, open a Unix terminal, then change directory to one of the samples. And, type:
make -f makefile.mac
It is tricky to run a program in Mac OS X since it requires the executable to be in a specific bundle directory structure, and this makefile will make one for you. To run the program, type:
make -f makefile.mac run
By the way, you must have XCode installed.
In Linux (I have tested with Ubuntu 8.4), open a Unix terminal, go to the directories of one of the samples, and type:
make -f makefile.glx
to build a program. You can directly type the executable name to run.
Easy enough. Right? But, if you want to compile from Visual Studio or XCode IDE, I also wrote a tutorial for doing it. You can read from the following links:
Compiling FsSimpleWindow framework program in Visual Studio 2010 Express Edition
Compiling FsSimpleWindow framework program in XCode IDE
int FsCheckWindowExposure(void);
This function returns non-zero if the at least part of the window has been exposed since the last inquiry. See also FsPollDevice.
int FsGetKeyState(int fsKeyCode);
This function returns non-zero if the key specified by fsKeyCode is held down, or zero if it is not. See also Key-Code enum and FsPollDevice
int FsGetMouseEvent(int &lb,int &mb,int &rb,int &mx,int &my);
This function gives non-zero (button is pressed) or zero (button is not pressed) in lb (left button), mb (middle button), and rb (right button), and mouse cursor coordinate relative to the window in mx and my.
The return value is the mouse event since the last inquiry. See also Mouse-Event enum and FsPollDevice.
void FsGetMouseState(int &lb,int &mb,int &rb,int &mx,int &my);
This function gives non-zero (button is pressed) or zero (button is not pressed) in lb (left button), mb (middle button), and rb (right button), and mouse cursor coordinate relative to the window in mx and my.
In fact, I realized this function is really unnecessary since FsGetMouseEvent function does the same and gives more information with virtually zero extra cost. So, use FsGetMouseEvent instead.
See also FsPollDevice.
void FsGetWindowSize(int &wid,int &hei);
This function gives window size in pixels in wid and hei. See also FsPollDevice.
int FsInkey(void);
This function returns a key code of the key that has been pressed since the last inquiry. See also Key-Code enum and FsPollDevice.
int FsInkeyChar(void);
This function returns a character code that has been produced by a key stroke since the last inquiry. The framework has an independent buffer for the produced character codes and key strokes, and this function will not take away one key code to be retrieved by FsInkey, nor FsInkey will not clear a character code to be retrieved by FsInkeyChar. See also FsPollDevice.
void FsOpenWindow(int x0,int y0,int wid,int hei,int useDoubleBuffer);
This function opens up a window located from (x0,y0) pixels from the reference point of the window (top left or bottom left depending on the platform), with the size of (wid,hei) pixels. If useDoubleBuffer is non-zero, the window will have a back buffer.
int FsPassedTime(void);
This function returns elapsed time in millisecond since the last inquiry.
void FsPollDevice(void);
This function talks to the operating system and checks for the device events (such as mouse, key stroke, and window). The events are copied to the framework's internal buffer and be ready to be retrieved by the framework's functions. In other words, you need to call this function at least once in the main loop, or you will not be able to get key strokes, mouse status, etc., by the framework functions.
See also FsCheckWindowExposure, FsGetKeyState, FsGetMouseEvent, FsGetMouseState, FsInkey and FsInkeyChar.
void FsSleep(int ms);
This function let the program sleep for the given time period. The parameter ms is the duration of the sleep in milliseconds. It is a good practice to give some time back to other processes by this function in the main loop. This way, if your program is idle, your program will not take 100% of one CPU core just to run the main loop.
void FsSwapBuffers(void);
In double-buffered environment, this function exposes the back buffer contents to the front buffer.
FsGetMouseEvent function will return one of the following values.
enum
{
FSMOUSEEVENT_NONE,
FSMOUSEEVENT_LBUTTONDOWN,
FSMOUSEEVENT_LBUTTONUP,
FSMOUSEEVENT_MBUTTONDOWN,
FSMOUSEEVENT_MBUTTONUP,
FSMOUSEEVENT_RBUTTONDOWN,
FSMOUSEEVENT_RBUTTONUP,
FSMOUSEEVENT_MOVE
};
| FSMOUSEEVENT_NONE | No change in the mouse status. |
| FSMOUSEEVENT_LBUTTONDOWN | Left button has been pressed since the last inquiry. |
| FSMOUSEEVENT_LBUTTONUP | Left button has been released since the last inquiry. |
| FSMOUSEEVENT_MBUTTONDOWN | Middle button has been pressed since the last inquiry. |
| FSMOUSEEVENT_MBUTTONUP | Middle button has been released since the last inquiry. |
| FSMOUSEEVENT_RBUTTONDOWN | Right button has been pressed since the last inquiry. |
| FSMOUSEEVENT_RBUTTONUP | Right button has been released since the last inquiry. |
| FSMOUSEEVENT_MOVE | Mouse cursor has moved since the last inquiry. |
FsInkey function will return one of the following values. These values are also used to check the key state (down or up) with FsGetKeyState function. (I think you can see the meaning by looking at the value. So, I don't write them out.)
Caution: Some special keys are not available in some platforms. Use of those keys makes your program platform-dependent.
enum
{
FSKEY_NULL,
FSKEY_SPACE,
FSKEY_0,
FSKEY_1,
FSKEY_2,
FSKEY_3,
FSKEY_4,
FSKEY_5,
FSKEY_6,
FSKEY_7,
FSKEY_8,
FSKEY_9,
FSKEY_A,
FSKEY_B,
FSKEY_C,
FSKEY_D,
FSKEY_E,
FSKEY_F,
FSKEY_G,
FSKEY_H,
FSKEY_I,
FSKEY_J,
FSKEY_K,
FSKEY_L,
FSKEY_M,
FSKEY_N,
FSKEY_O,
FSKEY_P,
FSKEY_Q,
FSKEY_R,
FSKEY_S,
FSKEY_T,
FSKEY_U,
FSKEY_V,
FSKEY_W,
FSKEY_X,
FSKEY_Y,
FSKEY_Z,
FSKEY_ESC,
FSKEY_F1,
FSKEY_F2,
FSKEY_F3,
FSKEY_F4,
FSKEY_F5,
FSKEY_F6,
FSKEY_F7,
FSKEY_F8,
FSKEY_F9,
FSKEY_F10,
FSKEY_F11,
FSKEY_F12,
FSKEY_PRINTSCRN,
FSKEY_CAPSLOCK,
FSKEY_SCROLLLOCK,
FSKEY_PAUSEBREAK,
FSKEY_BS,
FSKEY_TAB,
FSKEY_ENTER,
FSKEY_SHIFT,
FSKEY_CTRL,
FSKEY_ALT,
FSKEY_INS,
FSKEY_DEL,
FSKEY_HOME,
FSKEY_END,
FSKEY_PAGEUP,
FSKEY_PAGEDOWN,
FSKEY_UP,
FSKEY_DOWN,
FSKEY_LEFT,
FSKEY_RIGHT,
FSKEY_NUMLOCK,
FSKEY_TILDA,
FSKEY_MINUS,
FSKEY_PLUS,
FSKEY_LBRACKET,
FSKEY_RBRACKET,
FSKEY_BACKSLASH,
FSKEY_SEMICOLON,
FSKEY_SINGLEQUOTE,
FSKEY_COMMA,
FSKEY_DOT,
FSKEY_SLASH,
FSKEY_TEN0,
FSKEY_TEN1,
FSKEY_TEN2,
FSKEY_TEN3,
FSKEY_TEN4,
FSKEY_TEN5,
FSKEY_TEN6,
FSKEY_TEN7,
FSKEY_TEN8,
FSKEY_TEN9,
FSKEY_TENDOT,
FSKEY_TENSLASH,
FSKEY_TENSTAR,
FSKEY_TENMINUS,
FSKEY_TENPLUS,
FSKEY_TENENTER,
FSKEY_WHEELUP,
FSKEY_WHEELDOWN,
FSKEY_NUM_KEYCODE };