Lightweight, high-performance 2D graphics engine and embedded GUI framework designed for yss OS on resource-constrained microcontrollers.
TurtleShip is the core graphics and user interface library of yss OS. It is architected specifically for embedded systems with limited RAM, featuring device-independent 2D vector primitives, dynamic off-screen frame buffers, anti-aliased typography, and a retained-mode hierarchical widget toolkit.
- Device-Independent 2D Drawing Engine (
Brush):- Implements standard 2D graphics primitives: dots, lines (Bresenham's algorithm), rectangles, quadrangles, triangles, circles (outline and filled).
- Fast clipping calculations via
BitmapDrawingCalculatorto ensure drawing commands stay strictly within valid canvas boundaries. - Multi-alignment text rendering (
ALIGN_CENTER_MID,ALIGN_LEFT_TOP,ALIGN_RIGHT_BOT, etc.).
- Anti-Aliased Typography (
Font,CodeFont):- High-quality UTF-8 proportional and monospaced font rendering.
- 4-bit per-pixel sub-pixel alpha blending (
blendDot()) for smooth glyph anti-aliasing against any background color.
- Flexible FrameBuffer Architecture (
FrameBuffer):- Off-screen drawing surfaces supporting dynamic memory allocation (
malloc(capacity)). - Native support for multiple color formats and endianness configurations:
FrameBufferRgb565LE: Little-Endian 16-bit RGB565 (standard for ARM Cortex-M).FrameBufferRgb565BE: Big-Endian 16-bit RGB565.FrameBufferArgb1555LE/FrameBufferArgb1555: 16-bit ARGB with 1-bit alpha channel.
- Partial redraw and blitting (
drawBitmap()) to transfer only modified areas to the display, drastically reducing SPI/parallel bus bottlenecks.
- Off-screen drawing surfaces supporting dynamic memory allocation (
- Comprehensive Color Abstraction (
Color):- Unified color manipulation with native support for
ColorRgb565LE,ColorRgb565BE,ColorRgb888,ColorBgr565LE, andColorBgr565BE. - Bitwise conversion utilities and alpha blending calculations.
- Unified color manipulation with native support for
- Hierarchical Widget Toolkit (
Object,Container,Frame,Button,Label):- Retained-mode UI component system managing geometry (
Position,Size,Area), visibility, and dirty region invalidation. - Interactive touch and pointer event routing (
push,drag,up).
- Retained-mode UI component system managing geometry (
- Target Microcontrollers & Development Boards:
- Any 32-bit MCU supported by the yss OS platform (ARM Cortex-M0+/M3/M4/M7/M23/M33, etc.).
- Supported Display Interfaces:
- TFT LCDs via SPI, 8080/6800 parallel interfaces, or RGB interfaces (e.g., ST7789V, ILI9341, ST7735).
- Required Software & Toolchains:
- Toolchain: CrossWorks for ARM (v5.x or higher).
- Operating System: yss OS (embedded RTOS & HAL).
- Language: C++11 or higher.
To add TurtleShip as a submodule to your project:
git submodule add https://github.com/mymy49/TurtleShip.git module/TurtleShipTo clone an existing project with submodules:
git clone --recursive <repository-url>- Add the TurtleShip source directory (
TurtleShip/src) and include directory (TurtleShip/inc) to your project's include and build paths. - Ensure yss OS is properly initialized and configured.
- Build the application using CrossWorks for ARM.
- Download the firmware binary to your target hardware using your preferred debug probe (J-Link, CMSIS-DAP, etc.).
Below is a typical real-world workflow using FrameBufferRgb565LE as an off-screen brush to compose UI elements and blit them to a TFT LCD display under yss OS:
#include <bsp.h>
#include <TurtleShip.h>
// Global off-screen drawing buffer instance
FrameBufferRgb565LE brush;
void initializeGraphics(void)
{
// Allocate memory for up to 5,000 pixels (10,000 bytes for RGB565)
brush.malloc(5000);
}#include <bsp.h>
#include <font/Ubuntu_20_B.h>
void drawCustomCard(Area area, const char *title)
{
// Acquire mutex lock on display driver
lcd.lock();
// 1. Resize off-screen canvas to widget dimensions and clear background
brush.setSize(area);
brush.setBackgroundColor(0x20, 0x20, 0x20); // Dark grey
brush.clear();
// 2. Draw border and inner panel
brush.setBrushColor(0x40, 0x40, 0x40);
brush.fillRectangular({2, 2, area.width - 4, area.height - 4});
// 3. Draw geometric shapes
brush.setBrushColor(0x00, 0xFF, 0x80); // Accent color
brush.fillCircle({12, 12}, 6);
// 4. Render anti-aliased text
brush.setFont(Font_Ubuntu_20_B);
brush.setBrushColor(0xFF, 0xFF, 0xFF); // White text
brush.drawString(Brush::ALIGN_CENTER_MID, title);
// 5. Transfer rendered off-screen buffer to the target LCD area
lcd.drawBitmap(area.getPosition(), brush.getBitmap());
// Release mutex lock
lcd.unlock();
}Display drivers (such as Touch_LCD_Shield_for_Arduino_2_8_inch or BrushTftLcdRgb565LE) inherit from Brush, enabling direct vector rendering onto the screen:
lcd.lock();
// Direct line drawing on LCD surface
lcd.setBrushColor({0xFF, 0x00, 0x00});
lcd.drawLine({10, 10}, {200, 10});
// Direct rectangle drawing
lcd.setBrushColor({0x00, 0x00, 0xFF});
lcd.drawRectangular({20, 30, 100, 50});
lcd.unlock();- Doxygen API Reference: https://mymy49.github.io/TurtleShip/
- Doxygen Main Page: This
README.mdfile serves as the main page of the generated Doxygen documentation (USE_MDFILE_AS_MAINPAGE = README.md). - Related Modules:
- Author: Yoon-Ki Hong
- License: MIT License. See LICENSE for full terms and conditions.