# Graphics and Game Development in ModuOS

ModuOS provides powerful graphics capabilities through two complementary systems:

## 🎨 NodGL - Graphics API

**NodGL** is ModuOS's low-level graphics API for drawing and rendering.

### What is NodGL?
- Direct GPU access and hardware acceleration
- Device/Context architecture (similar to modern graphics APIs)
- Full control over rendering pipeline
- Suitable for graphics applications, visualizations, and advanced rendering

### When to Use NodGL?
- Building custom graphics applications
- Advanced rendering techniques
- Maximum control over graphics hardware
- Non-game graphics programs (paint apps, visualizers, etc.)

### Documentation
📖 **[NodGL Documentation →](NodGL/NodGL-Index.md)**

**Topics Covered:**
- [Getting Started](NodGL/Getting-Started.md) - Your first NodGL program
- [Drawing Shapes](NodGL/Drawing-Shapes.md) - Rectangles, circles, lines
- [Using Textures](NodGL/Using-Textures.md) - Images and sprites
- [Handling Input](NodGL/Handling-Input.md) - Mouse and keyboard
- [Simple Examples](NodGL/Simple-Examples.md) - Complete programs
- [API Reference](NodGL-API.md) - Complete function list

---

## 🎮 StarEngine - Game Framework

**StarEngine** is a high-level 2D game framework built on top of NodGL.

### What is StarEngine?
- Complete game development framework
- Entity/sprite management system
- Built-in collision detection
- Easy input handling
- Perfect for beginners and rapid prototyping

### When to Use StarEngine?
- Making 2D games (arcade, platformer, puzzle, shooter, etc.)
- Learning game development
- Rapid prototyping
- Focus on gameplay, not graphics APIs

### Documentation
📖 **[StarEngine Documentation →](StarEngine/README.md)**

**Topics Covered:**
- [Introduction](StarEngine/Introduction.md) - What is StarEngine?
- [Getting Started](StarEngine/Getting-Started.md) - Your first game
- [Core Concepts](StarEngine/Core-Concepts.md) - Game loop, entities, sprites
- [Tutorial: Catch the Stars](StarEngine/Tutorial-Catch-Stars.md) - Step-by-step game
- [Example Games](StarEngine/Example-Games.md) - Complete game examples
- [API Reference](StarEngine/API-Reference.md) - All functions

---

## 🤔 Which Should I Use?

### Use **NodGL** if you want to:
- Build non-game graphics applications
- Have full control over rendering
- Learn low-level graphics programming
- Create custom rendering engines

### Use **StarEngine** if you want to:
- Make 2D games quickly
- Learn game development
- Focus on gameplay mechanics
- Avoid boilerplate code

---

## Quick Comparison

| Feature | NodGL | StarEngine |
|---------|-------|------------|
| **Level** | Low-level | High-level |
| **Purpose** | Graphics API | Game Framework |
| **Learning Curve** | Moderate | Easy |
| **Setup Code** | More | Minimal |
| **Best For** | Graphics apps | 2D games |
| **Input Handling** | Manual | Built-in |
| **Collision** | DIY | Built-in |
| **Entities** | Manual | Built-in |

---

## Code Comparison

### Simple Rectangle with NodGL

```c
#include "NodGL.h"
#include "libc.h"

int md_main(long argc, char **argv) {
    NodGL_Device device;
    NodGL_Context ctx;
    
    NodGL_CreateDevice(NodGL_FEATURE_LEVEL_1_0, &device, &ctx, NULL);
    
    NodGL_ClearContext(ctx, NodGL_CLEAR_COLOR, 0xFF000000, 1.0f, 0);
    NodGL_FillRectContext(ctx, 100, 100, 200, 150, 0xFFFF0000);
    NodGL_PresentContext(ctx, 1);
    
    for (volatile int i = 0; i < 5000000; i++);
    
    NodGL_ReleaseDevice(device);
    return 0;
}
```

### Simple Game with StarEngine

```c
#include "StarEngine.h"
#include "libc.h"

int md_main(long argc, char **argv) {
    StarEngine engine;
    star_engine_init(&engine);
    
    Sprite *player = star_sprite_create_circle(&engine, 16, 0xFF00FF00);
    int x = 100, y = 100;
    
    while (star_engine_is_running(&engine)) {
        star_engine_update_input(&engine);
        
        if (star_key_down(&engine, KEY_W)) y -= 3;
        if (star_key_down(&engine, KEY_S)) y += 3;
        if (star_key_down(&engine, KEY_A)) x -= 3;
        if (star_key_down(&engine, KEY_D)) x += 3;
        
        star_engine_begin_frame(&engine, 0xFF000000);
        star_sprite_draw(&engine, player, x, y);
        star_engine_end_frame(&engine);
    }
    
    star_sprite_free(&engine, player);
    star_engine_shutdown(&engine);
    return 0;
}
```

---

## Examples in the Repository

### NodGL Examples
Located in `userland/`:
- `NodGL_demo.c` - Feature showcase
- `NodGL_triangle.c` - 3D spinning cube
- `dvdbounce.c` - Bouncing DVD logo
- `gfxtest.c` - Graphics test program
- `snakegfx.c` - Snake game
- `minesgfx.c` - Minesweeper
- `calcgfx.c` - Calculator GUI

### StarEngine Examples
Located in `userland/`:
- `star_example_shooter.c` - Space shooter
- `star_example_pong.c` - Pong game

---

## Getting Started

### For Graphics Programming
1. Read [NodGL Getting Started](NodGL/Getting-Started.md)
2. Try [NodGL Simple Examples](NodGL/Simple-Examples.md)
3. Explore the NodGL example programs

### For Game Development
1. Read [StarEngine Introduction](StarEngine/Introduction.md)
2. Follow [StarEngine Getting Started](StarEngine/Getting-Started.md)
3. Build the [Catch the Stars Tutorial](StarEngine/Tutorial-Catch-Stars.md)
4. Study [StarEngine Example Games](StarEngine/Example-Games.md)

---

## Architecture

```
┌─────────────────────────────────────┐
│         Your Application            │
│    (Games, Graphics Programs)       │
└──────────┬──────────────────────────┘
           │
    ┌──────┴──────┐
    │             │
┌───▼────┐   ┌───▼─────────┐
│NodGL   │   │ StarEngine  │ (Built on NodGL)
│Graphics│   │    Game     │
│  API   │   │  Framework  │
└───┬────┘   └─────┬───────┘
    │              │
    └──────┬───────┘
           │
    ┌──────▼──────┐
    │   NodGL     │
    │  Graphics   │
    │   Backend   │
    └──────┬──────┘
           │
    ┌──────▼──────┐
    │  GPU/HW     │
    │Acceleration │
    └─────────────┘
```

---

## File Locations

### Headers
- `include/moduos/NodGL.h` - NodGL API
- `userland/StarEngine.h` - StarEngine framework

### Implementations
- `userland/lib_NodGL.c` - NodGL implementation
- `userland/StarEngine.c` - StarEngine implementation

### Documentation
- `wiki-repo/NodGL/` - NodGL documentation
- `wiki-repo/StarEngine/` - StarEngine documentation

### Examples
- `userland/NodGL_*.c` - NodGL examples
- `userland/star_example_*.c` - StarEngine examples
- `userland/*gfx.c` - Various graphics programs

---

## Common Tasks

### Drawing a Rectangle
**NodGL:**
```c
NodGL_FillRectContext(ctx, x, y, width, height, color);
```

**StarEngine:**
```c
star_draw_rect(&engine, x, y, width, height, color);
```

### Handling Input
**NodGL:**
```c
int queue_fd = open("/dev/event0", 0);
event_t ev;
while (read(queue_fd, &ev, sizeof(ev)) == sizeof(ev)) {
    if (ev.type == EVENT_KEYBOARD) {
        // Handle key
    }
}
```

**StarEngine:**
```c
star_engine_update_input(&engine);
if (star_key_down(&engine, KEY_W)) {
    // Handle key
}
```

### Collision Detection
**NodGL:**
```c
int collides = (x1 < x2 + w2 && x1 + w1 > x2 &&
                y1 < y2 + h2 && y1 + h1 > y2);
```

**StarEngine:**
```c
int collides = star_entity_collides(entity1, entity2);
```

---

## Resources

- **[NodGL Documentation](NodGL/NodGL-Index.md)** - Complete NodGL guide
- **[StarEngine Documentation](StarEngine/README.md)** - Complete StarEngine guide
- **[System Architecture](System-Architecture.md)** - ModuOS overview
- **[Contributing](Contributing.md)** - Help improve ModuOS

---

## Support

Both NodGL and StarEngine are actively maintained as part of ModuOS.

**Questions?**
- Check the documentation wiki pages
- Examine the example programs
- Read the API references

**Found a bug?**
- Report issues following the [Contributing Guide](Contributing.md)

---

Happy coding! Whether you're making games or graphics applications, ModuOS has you covered! 🎨🎮