# dogo/oslib architecture

> Architecture diagram of the GitHub repository dogo/oslib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dogo/oslib
- Repository: https://github.com/dogo/oslib

## Overview

##### Project Type and Purpose
- OSLib is a **static C/C++ library** for classic/retro game development, targeting PSP and other platforms.
- It exposes graphics, input, audio, file I/O, networking, font rendering, math, and utility functions.
- It ships as `libosl.a` plus headers; includes sample apps and conversion tools.

##### File Structure
- **Top Level**
– Build files: `CMakeLists.txt`, `Makefile`, `install.{sh,bat}`, `release.{sh,bat}`
– Output: `libosl.a` (static archive)
– Docs: `Doc/` + `README.md`, `Doxyfile`, `CHANGELOG.md`
– CI: `.github/workflows/Build.yml`
- **Source Modules (`src/`)**
– Core: `oslib.c/h`, `oslmath.h`, `stub.S`
– Graphics: `drawing.c/h`, `palette.c`, image loaders (`src/Special/`), PNG/GIF libs
– Audio: `src/audio/`, `bgm.c`, `mod.c`, `media.c`
– Input/UI: `dialog.c`, `messagebox.c`, `osk.c`
– File/Virtual FS: `vfile/`, `VirtualFile.h`, save/load
– Network: `net.c`, `adhoc/pspadhoc.c`
– Math: `libpspmath/`, `vfpu*.c/h`
– Font: `intraFont/`, `sfont.c`
– Utility: `keys.c`, `text.c`, `map.c`, `vram_mgr.c`, `mem/`
- **Samples (`samples/`)**
– Demonstrations of each subsystem linking against `libosl.a`.
- **Tools (`tools/`)**
– Converters: `font2osl.exe`, `wav2bgm.exe` + their sources.

##### Extract Additional Insights from the README
- Features: Graphics, Input, Sound, Utilities, Cross-Platform support.
- Installation: copy `libosl.a` + headers into PSP-SDK paths.
- Contributing: tests, coding guidelines, CI.

a. **Components**
– **Application / Sample Projects** (e.g. `samples/*`)
– **OSLib Static Library (`libosl.a`)**
– **OSLib Sub-Modules** (Graphics, Audio, Input/UI, Virtual FS, Network, Math, Font, Utility)
– **External Third-Party Libraries** (zlib, GIF, PNG)
– **Platform Abstraction Layer** (`Platform/PSP.cmake`, any PSP-specific code)
– **Build System** (CMake, Makefiles, install/release scripts)
– **Development Tools** (`font2osl`, `wav2bgm`)
b. **Relationships & Data Flows**
– Samples & user apps link → **`libosl.a`**
– `libosl.a` comprises modules that call → External libs (PNG, GIF, zlib)
– Modules communicate through core utilities (VirtualFile, memory, VFPU)
– Build system orchestrates compilation of `src/` into `libosl.a`, compiles tools, runs tests
– Platform layer adapts calls for PSP vs. generic OS
c. **Architectural Patterns & Principles**
– **Modularization:** each domain (audio, graphics, etc.) lives in its own directory
– **Abstraction Layer:** Virtual filesystem, platform-specific glue isolated
– **Adapter Pattern:** image-format loaders under `src/Special` act as adapters for GIF/PNG/JPG
– **Static Linkage:** everything consolidated into one archive for simplicity on embedded targets
d. **Key Technologies & Frameworks**
– Languages: C, C++ (for tools)
– Build: CMake, Make, PSP-SDK CMake wrapper, batch/shell scripts
– Documentation: Doxygen
– CI: GitHub Actions

##### Diagramming Recommendations
– Use **rectangles** for components (Modules, Library, Apps, Tools).
– Use **parallelograms** for data stores or resources (maps, fonts, audio assets).
- Library Core (blue)
- Sub-modules (green)
- External dependencies (orange)
- Samples/Apps (purple)
- Tools & Build (gray)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Samples / Applications
    Samples["Applications & Sample Projects"]:::samples
    click Samples "https://github.com/dogo/oslib/tree/master/samples/"

    %% Static Library
    Lib["OSLib Static Library\nlibosl.a"]:::core
    click Lib "https://github.com/dogo/oslib/blob/master/libosl.a"

    %% Build System
    subgraph "Build System"
        Build["Build System\n(CMakeLists.txt, Makefile, install/release scripts)"]:::build
        CI["CI Workflow\n(.github/workflows/Build.yml)"]:::build
        Scripts["Shell/Batch Scripts\n(install.sh/.bat, release.sh/.bat)"]:::build
    end
    click Build "https://github.com/dogo/oslib/blob/master/CMakeLists.txt"
    click CI "https://github.com/dogo/oslib/blob/master/.github/workflows/Build.yml"
    click Scripts "https://github.com/dogo/oslib/tree/master/Makefile"

    %% Tools
    subgraph "Development Tools"
        Tools["Asset Conversion Tools"]:::tools
    end
    click Tools "https://github.com/dogo/oslib/blob/master/tools/font2osl.exe"

    %% OSLib Library and Modules
    subgraph "OSLib Library"
        Platform["Platform Abstraction Layer\n(Platform/PSP.cmake, stub.S)"]:::module
        Core["Core Module\n(src/oslib.c, src/oslib.h, src/oslmath.h)"]:::core
        Graphics["Graphics Module\n(src/drawing.c, src/palette.c, src/Special/, src/image/, png/gif libs)"]:::module
        Audio["Audio Module\n(src/audio/*.c, src/audio.h, src/bgm.h)"]:::module
        InputUI["Input/UI Module\n(src/dialog.c, messagebox, osk, text, keys)"]:::module
        VFS["Virtual FS Module\n(src/vfile/, src/VirtualFile.h)"]:::module
        Network["Network Module\n(src/net.c, src/adhoc/)"]:::module
        MathVFPU["Math & VFPU Module\n(src/libpspmath/, vfpu.c/h)"]:::module
        Font["Font Rendering Module\n(src/intraFont/, src/sfont.c)"]:::module
        Utility["Utility Module\n(src/map.c, vram_mgr, mem/, usb, saveload, shape)"]:::module
    end
    click Platform "https://github.com/dogo/oslib/blob/master/Platform/PSP.cmake"
    click Core "https://github.com/dogo/oslib/blob/master/src/oslib.c"
    click Graphics "https://github.com/dogo/oslib/blob/master/src/drawing.c"
    click Audio "https://github.com/dogo/oslib/blob/master/src/audio/audio.c"
    click InputUI "https://github.com/dogo/oslib/blob/master/src/dialog.c"
    click VFS "https://github.com/dogo/oslib/blob/master/src/vfile/VirtualFile.c"
    click Network "https://github.com/dogo/oslib/blob/master/src/net.c"
    click MathVFPU "https://github.com/dogo/oslib/tree/master/src/libpspmath/"
    click Font "https://github.com/dogo/oslib/blob/master/src/intraFont/intraFont.c"
    click Utility "https://github.com/dogo/oslib/blob/master/src/map.c"

    %% External Dependencies
    Zlib["zlib"]:::ext
    click Zlib "https://github.com/dogo/oslib/blob/master/src/zlib.h"
    PNG["PNG"]:::ext
    click PNG "https://github.com/dogo/oslib/blob/master/src/png.h"
    GIF["GIF"]:::ext
    click GIF "https://github.com/dogo/oslib/blob/master/src/gif/egif_lib.c"

    %% Relationships
    Samples -->|"link →"| Lib
    Lib -->|includes →| Core
    Lib -->|includes →| Graphics
    Lib -->|includes →| Audio
    Lib -->|includes →| InputUI
    Lib -->|includes →| VFS
    Lib -->|includes →| Network
    Lib -->|includes →| MathVFPU
    Lib -->|includes →| Font
    Lib -->|includes →| Utility
    Lib -->|guided by →| Build
    Build -->|builds →| Lib
    Build -->|builds →| Tools
    Build -->|builds →| Samples
    Tools -->|asset → font →| Font
    Tools -->|asset → audio →| Audio
    Graphics -->|calls →| PNG
    Graphics -->|calls →| GIF
    Graphics -->|calls →| Zlib
    Core -->|uses →| Platform
    Graphics -->|uses →| Platform
    Audio -->|uses →| Platform
    InputUI -->|uses →| Platform
    VFS -->|uses →| Platform
    Network -->|uses →| Platform
    MathVFPU -->|uses →| Platform
    Font -->|uses →| Platform
    Utility -->|uses →| Platform

    %% Styles
    classDef core fill:#b3cde3,stroke:#000,color:#000
    classDef module fill:#ccebc5,stroke:#000,color:#000
    classDef ext fill:#fdae61,stroke:#000,color:#000
    classDef samples fill:#decbe4,stroke:#000,color:#000
    classDef tools fill:#e5e5e5,stroke:#000,color:#000
    classDef build fill:#cccccc,stroke:#000,color:#000
```
