Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lvntky/fbgl
Lightweight 2D Framebuffer Library for Linux
https://github.com/lvntky/fbgl
2d 2d-graphics embedded fbdev framebuffer graphics graphics-library graphics-rendering library lightweight unix
Last synced: about 1 month ago
JSON representation
Lightweight 2D Framebuffer Library for Linux
- Host: GitHub
- URL: https://github.com/lvntky/fbgl
- Owner: lvntky
- License: mit
- Created: 2024-11-18T19:45:00.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2024-11-28T21:41:47.000Z (about 2 months ago)
- Last Synced: 2024-11-28T22:26:39.552Z (about 2 months ago)
- Topics: 2d, 2d-graphics, embedded, fbdev, framebuffer, graphics, graphics-library, graphics-rendering, library, lightweight, unix
- Language: C
- Homepage: https://lvntky.github.io/fbgl/
- Size: 14.7 MB
- Stars: 32
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fbgl: Lightweight 2D Framebuffer Library for Linux
[](https://app.codacy.com/gh/lvntky/fbgl/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
`fbgl` (Framebuffer Graphics Library) is a minimalistic, **header-only** 2D framebuffer library written in C. Designed for simplicity and performance, `fbgl` provides an intuitive API for directly manipulating the Linux framebuffer device (`/dev/fb0`). Whether you're experimenting with low-level graphics or building lightweight graphical applications, `fbgl` offers the foundation you need.
---
## Features
- **Header-only design**: Include `fbgl.h` and start coding.
- **Direct framebuffer rendering**: Writes directly to `/dev/fb0` for high performance.
- **Simple API**: Easy-to-use functions for initializing, clearing, and drawing.
- **Lightweight**: Minimal dependencies, using only standard Linux libraries.
- **Custom rendering**: Draw pixels, lines, and shapes directly to the framebuffer.
---
## Getting Started
### Prerequisites
- A Linux-based system with framebuffer support.
- Development tools like GCC.
- Access to `/dev/fb0` (requires elevated permissions or proper user configuration).
### Installation
No installation is required! Simply copy the `fbgl.h` file into your project directory and include it in your source files,
while also defining the `FBGL_IMPLEMENTATION` macro in one of your source files.
```c
#define FBGL_IMPLEMENTATION
#include "fbgl.h"
```
---
## Usage
### Example Program
Here’s a simple program that initializes the framebuffer, clears it to a blue color, and draws a red diagonal line.
```c
#define FBGL_IMPLEMENTATION
#include "fbgl.h"
#include
int main()
{
fbgl_t buffer;
// Initialize the framebuffer
if (fbgl_init("/dev/fb0", &buffer) != 0) {
fprintf(stderr, "Failed to initialize framebuffer\n");
return 1;
}
printf("Framebuffer size: %dx%d\n", fb_get_width(), fb_get_height());
// Clear framebuffer to blue
fbgl_clear(0x0000FFFF); // Blue color
// Draw a red diagonal line
for (int i = 0; i < fb_get_width() && i < fb_get_height(); i++) {
fbgl_put_pixel(i, i, 0xFFFF0000, &buffer); // Red
}
// Wait for user input before exiting
getchar();
// Clean up
fbgl_destroy(&buffer);
return 0;
}
```
Compile the program:
```bash
gcc -o example main.c
```
Run the program with elevated permissions to access `/dev/fb0`:
```bash
sudo ./example
```
---
## API Reference
### Initialization and Cleanup
#### `int fbgl_init(const char *device);`
Initializes the framebuffer.
- **Parameters**:
`device`: Path to the framebuffer device (e.g., `/dev/fb0`).
- **Returns**:
`0` on success, `-1` on failure.
#### `void fbgl_destroy(void);`
Destroys the framebuffer and releases resources.
---
### Drawing Functions
#### `void fbgl_clear(uint32_t color);`
Fills the entire framebuffer with a specified color.
- **Parameters**:
`color`: 32-bit ARGB color (e.g., `0xFFFF0000` for red).
#### `void fbgl_put_pixel(int x, int y, uint32_t color);`
Sets a pixel at the specified position to the given color.
- **Parameters**:
`x, y`: Pixel coordinates.
`color`: 32-bit ARGB color.
---
### Utility Functions
#### `int fbgl_get_width(void);`
Returns the width of the framebuffer in pixels.
#### `int fbgl_get_height(void);`
Returns the height of the framebuffer in pixels.
---
## How It Works
1. **Framebuffer Device**: `fbgl` uses the Linux framebuffer device (`/dev/fb0`) to directly access the screen memory.
2. **Memory Mapping**: The framebuffer is mapped into user-space memory using `mmap`, allowing for direct pixel manipulation.
3. **Direct Rendering**: Pixels are written directly to the framebuffer, bypassing higher-level graphics APIs.
---
## Limitations
- **Platform-specific**: Works only on Linux systems with framebuffer support.
- **Root permissions**: Access to `/dev/fb0` often requires `sudo`.
- **No hardware acceleration**: Rendering is done in software, so performance depends on CPU speed.
---
## Roadmap
Future improvements for `fbgl` may include:
- Support for double buffering.
- More advanced drawing primitives (e.g., circles, filled polygons).
- Cross-platform abstraction for non-Linux systems.
- Text rendering using bitmap fonts.
- Performance optimizations for large resolutions.
---
## Contributing
Contributions are welcome! If you’d like to improve `fbgl`, add features, or fix bugs:
1. Fork the repository.
2. Create a new branch for your changes.
3. Submit a pull request with a clear description of your updates.
---
## License
`fbgl` is licensed under the MIT License. See the `LICENSE` file for details.
---
## Acknowledgments
- Inspired by the simplicity of low-level graphics programming.
- Thanks to the Linux community for making framebuffer programming accessible!
- See the [acknowledgements](./acknowledgements.md) for more details.
---
## Showcase
First Texture Rendering
PSF Text in fbgl
Simple ray casting demo
---
## Contact
If you have questions or suggestions, feel free to reach out via GitHub or email.
Happy coding with `fbgl`! 🚀