b/minifb-zig-port
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated readme.md

Browse Source
This commit is contained in:
Carlos Aragones 2020-09-21 11:59:42 +02:00
parent 9e3704b96c
commit cfb114007e
1 changed files with 370 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
README.md
View File

@ -1,27 +1,44 @@
# MiniFB # MiniFB
MiniFB (Mini FrameBuffer) is a small cross platform library that makes it easy to render (32-bit) pixels in a window. An example is the best way to show how it works: MiniFB (Mini FrameBuffer) is a small cross platform library that makes it easy to render (32-bit) pixels in a window.
An example is the best way to show how it works:
```c ```c
struct mfb_window *window = mfb_open_ex("my display", 800, 600, WF_RESIZABLE); struct mfb_window *window = mfb_open_ex("my display", 800, 600, WF_RESIZABLE);
if (!window) if (!window)
return 0; return 0;
for (;;) buffer = (uint32_t *) malloc(800 * 600 * 4);
{
do {
int state; int state;
// TODO: add some fancy rendering to the buffer of size 800 * 600 // TODO: add some fancy rendering to the buffer of size 800 * 600
state = mfb_update(buffer); state = mfb_update_ex(buffer, 800, 600);
if (state < 0) if (state < 0) {
window = NULL;
break; break;
} }
} while(mfb_wait_sync(window));
``` ```
1. First the application creates a **window** calling **mfb_open** or **mfb_open_ex**.
2. Next it's the application responsibility to allocate a buffer to work with.
3. Next calling **mfb_update** or **mfb_update_ex** the buffer will be copied over to the window and displayed. If this function return a value lower than 0 the window will have been destroyed internally and cannot be used anymore.
4. Last the code waits to synchronize with the monitor calling **mfb_wait_sync**.
Furthermore, you can _add callbacks to the windows_: Note that, by default, if ESC key is pressed **mfb_update** / **mfb_update_ex** will return -1 (and the window will have been destroyed internally).
See https://github.com/emoon/minifb/blob/master/tests/noise.c for a complete example.
MiniFB has been tested on Windows, Mac OS X, Linux and iOS but may of course have trouble depending on your setup. Currently the code will not do any converting of data if not a proper 32-bit display can be created.
## More features:
You can _add callbacks to the windows_:
```c ```c
void active(struct mfb_window *window, bool isActive) { void active(struct mfb_window *window, bool isActive) {
@ -76,17 +93,7 @@ mfb_set_mouse_move_callback(window, mouse_move);
mfb_set_mouse_scroll_callback(window, mouse_scroll); mfb_set_mouse_scroll_callback(window, mouse_scroll);
``` ```
Or you can _get information about the window events directly_:
Additionally you can _set data per window and recover it_:
```c
mfb_set_user_data(window, (void *) myData);
...
myData = (someCast *) mfb_get_user_data(window);
```
Finally, you can _get information about the events in the window directly_:
```c ```c
bool mfb_is_window_active(struct mfb_window *window); bool mfb_is_window_active(struct mfb_window *window);
@ -105,11 +112,13 @@ const uint8_t * mfb_get_mouse_button_buffer(struct mfb_window *window); // O
const uint8_t * mfb_get_key_buffer(struct mfb_window *window); // One byte for every key. Press (1), Release 0. const uint8_t * mfb_get_key_buffer(struct mfb_window *window); // One byte for every key. Press (1), Release 0.
``` ```
Additionally you can _set per window data and recover it_:
First the code creates window with the mfb_open call that is used to display the data, next it's the applications responsibility to allocate a buffer (which has to be at least the size of the window and in 32-bit) Next when calling mfb_update function the buffer will be copied over to the window and displayed. Currently the mfb_update will return -1 if ESC key is pressed but later on it will support to return a key code for a pressed button. See https://github.com/emoon/minifb/blob/master/tests/noise.c for a complete example ```c
mfb_set_user_data(window, (void *) myData);
MiniFB has been tested on Windows, Mac OS X and Linux but may of course have trouble depending on your setup. Currently the code will not do any converting of data if not a proper 32-bit display can be created. ...
myData = (someCast *) mfb_get_user_data(window);
```
**Extra: Timers and target FPS** **Extra: Timers and target FPS**
@ -141,40 +150,24 @@ To use this you need to call the function:
bool mfb_wait_sync(struct mfb_window *window); bool mfb_wait_sync(struct mfb_window *window);
``` ```
_Example_:
```c
do {
int i;
mfb_update_state state;
// TODO: add some awesome rendering to the buffer
state = mfb_update(window, g_buffer);
if (state != STATE_OK) {
window = 0x0;
break;
}
} while(mfb_wait_sync(window));
```
Note that if you have several windows running on the same thread it makes no sense to wait them all... Note that if you have several windows running on the same thread it makes no sense to wait them all...
## Build instructions ## Build instructions
MiniFB uses tundra https://github.com/deplinenoise/tundra as build system and is required to build the code as is but not many changes should be needed if you want to use it directly in your own code. The current build system is **CMake**.
You can also use CMake as build system. Initially MiniFB used tundra [https://github.com/deplinenoise/tundra](https://github.com/deplinenoise/tundra) as build system and it was required to build the code (but now is not maintained).
In any case, not many changes should be needed if you want to use MiniFB directly in your own code.
### Mac ### Mac
Cocoa and clang is assumed to be installed on the system (downloading latest XCode + installing the command line tools should do the trick) then to build run: tundra2 macosx-clang-debug and you should be able to run the noise example (t2-output/macosx-clang-debug-default/noise) Cocoa and clang is assumed to be installed on the system (downloading latest XCode + installing the command line tools should do the trick).
MacOS X Mojave does not support Cocoa framework as expected. For that reason now you can switch to Metal API. Note that MacOS X Mojave+ does not support Cocoa framework as expected. For that reason you can switch to Metal API.
To enable it just compile defining the preprocessor macro USE_METAL_API. To enable it just compile defining the preprocessor macro USE_METAL_API.
If you use CMake just enable the flag: If you use **CMake** just enable the flag:
``` ```
mkdir build mkdir build
@ -190,6 +183,13 @@ cd build
cmake .. -DUSE_METAL_API=OFF cmake .. -DUSE_METAL_API=OFF
``` ```
if you use **tundra**:
```
tundra2 macosx-clang-debug
```
and you should be able to run the noise example (t2-output/macosx-clang-debug-default/noise).
### iOS (beta) ### iOS (beta)
@ -208,6 +208,7 @@ If you want to create the UIWindow through an Story Board, remember to set the U
Some of the MiniFB functions don't make sense on mobile. Some of the MiniFB functions don't make sense on mobile.
The available functions for iOS are: The available functions for iOS are:
```c ```c
struct mfb_window * mfb_open(const char *title, unsigned width, unsigned height); struct mfb_window * mfb_open(const char *title, unsigned width, unsigned height);
struct mfb_window * mfb_open_ex(const char *title, unsigned width, unsigned height, unsigned flags); // flags ignored struct mfb_window * mfb_open_ex(const char *title, unsigned width, unsigned height, unsigned flags); // flags ignored
@ -232,6 +233,7 @@ int mfb_get_mouse_y(struct mfb_window *window); // L
``` ```
Timers are also available. Timers are also available.
```c ```c
struct mfb_timer * mfb_timer_create(void); struct mfb_timer * mfb_timer_create(void);
void mfb_timer_destroy(struct mfb_timer *tmr); void mfb_timer_destroy(struct mfb_timer *tmr);
@ -286,25 +288,46 @@ For now, no multitouch is available.
``` ```
**CMake** **CMake**
``` ```
mkdir build mkdir build
cd build cd build
cmake -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 .. cmake -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 ..
``` ```
### Windows ### Windows
Visual Studio (ver 2012 express has been tested) tools needed (using the vcvars32.bat (for 32-bit) will set up the enviroment) to build run: tundra2 win32-msvc-debug and you should be able to run noise in t2-output/win32-msvc-debug-default/noise.exe If you use **CMake** the Visual Studio project will be generated (2015, 2017 and 2019 have been tested).
If you use CMake the Visual Studio project will be generated (2015, 2017 and 2019 have been tested). Furthermore you can also use **MinGW** instead of Visual Studio.
if you use **tundra**:
Visual Studio (ver 2012 express has been tested) tools needed (using the vcvars32.bat (for 32-bit) will set up the enviroment) to build run:
```
tundra2 win32-msvc-debug
```
and you should be able to run noise in t2-output/win32-msvc-debug-default/noise.exe
#### **NEW**: OpenGL API backend
Now, by default, OpenGL backend is used, instead of Windows GDI, because it is faster. To maintain compatibility with old computers an OpenGL 1.5 context is created (no shaders needed).
To enable or disable OpenGL just use a CMake flag:
```
cmake .. -DUSE_OPENGL_API=ON
or
cmake .. -DUSE_OPENGL_API=OFF
```
### x11 (FreeBSD, Linux, *nix) ### x11 (FreeBSD, Linux, *nix)
gcc and x11-dev libs needs to be installed. To build the code run tundra2 x11-gcc-debug and you should be able to run t2-output/x11-gcc-debug-default/noise gcc and x11-dev libs needs to be installed.
If you use CMake just disable the flag: If you use **CMake** just disable the flag:
``` ```
mkdir build mkdir build
@ -312,12 +335,33 @@ cd build
cmake .. -DUSE_WAYLAND_API=OFF cmake .. -DUSE_WAYLAND_API=OFF
``` ```
If you use **tundra**:
To build the code run:
```
tundra2 x11-gcc-debug
```
and you should be able to run t2-output/x11-gcc-debug-default/noise
#### **NEW**: OpenGL API backend
Now, by default, OpenGL backend is used instead of X11 XImages because it is faster. To maintain compatibility with old computers an OpenGL 1.5 context is created (no shaders needed).
To enable or disable OpenGL just use a CMake flag:
```
cmake .. -DUSE_OPENGL_API=ON -DUSE_WAYLAND_API=OFF
or
cmake .. -DUSE_OPENGL_API=OFF -DUSE_WAYLAND_API=OFF
```
### Wayland (Linux) ### Wayland (Linux)
Depends on gcc and wayland-client and wayland-cursor. Built using the wayland-gcc variants. Depends on gcc and wayland-client and wayland-cursor. Built using the wayland-gcc variants.
If you use CMake just enable the flag: If you use **CMake** just enable the flag:
``` ```
mkdir build mkdir build