# NodGL - Graphics API Reference

## Overview

**NodGL** is a modern graphics API for ModuOS, providing a clean device/context architecture for 2D and 3D graphics rendering. 

**Name Origin**: New Technologies OpenD Graphics Library

## Architecture

NodGL follows a layered architecture with clear separation of concerns:

```
┌─────────────────────────────────────┐
│     Application Layer               │
│  (nodgl_demo.c, games, etc.)        │
└─────────────────────────────────────┘
             ↓
┌─────────────────────────────────────┐
│     NodGL API                       │
│  (lib_nodgl.c, nodgl.h)             │
└─────────────────────────────────────┘
             ↓
┌─────────────────────────────────────┐
│     GFX2D Backend                   │
│  (lib_gfx2d.c, videoctl2)           │
└─────────────────────────────────────┘
             ↓
┌─────────────────────────────────────┐
│     Kernel Graphics Layer           │
│  (SQRM GPU modules, framebuffer)    │
└─────────────────────────────────────┘
```

## Key Features

### Modern API Design
- **Device/Context separation**: Resources vs rendering commands
- **Resource management**: Typed handles for textures, buffers, and surfaces
- **Feature levels**: Progressive enhancement based on hardware capabilities
- **Present model**: Double-buffering with vsync support

### 2D Graphics
- Hardware-accelerated rectangle fills
- Texture blitting with alpha blending
- Line drawing primitives
- Sprite rendering with transforms

### 3D Graphics (Future)
- Vertex/index buffer management
- Primitive topology (points, lines, triangles)
- Shader pipeline (planned)
- Depth/stencil buffers (planned)

## API Reference

### Device Management

#### `NodGL_CreateDevice`
```c
int NodGL_CreateDevice(
    NodGL_FeatureLevel min_feature_level,
    NodGL_Device *out_device,
    NodGL_Context *out_context,
    NodGL_FeatureLevel *out_actual_level
);
```

Creates a NodGL device and immediate rendering context.

**Parameters:**
- `min_feature_level`: Minimum required feature level
- `out_device`: Receives the device handle
- `out_context`: Receives the immediate context handle
- `out_actual_level`: Receives the actual feature level (optional)

**Returns:** `NodGL_OK` on success, error code otherwise

**Feature Levels:**
- `NodGL_FEATURE_LEVEL_1_0`: Software rendering, basic 2D
- `NodGL_FEATURE_LEVEL_2_0`: Hardware-accelerated 2D
- `NodGL_FEATURE_LEVEL_3_0`: 3D pipeline (future)

#### `NodGL_ReleaseDevice`
```c
void NodGL_ReleaseDevice(NodGL_Device device);
```

Releases the device and all associated resources.

#### `NodGL_GetDeviceCaps`
```c
int NodGL_GetDeviceCaps(NodGL_Device device, NodGL_DeviceCaps *out_caps);
```

Queries device capabilities.

**Capabilities Flags:**
- `NodGL_CAP_HARDWARE_ACCEL`: Hardware acceleration available
- `NodGL_CAP_ALPHA_BLEND`: Alpha blending supported
- `NodGL_CAP_3D_PIPELINE`: 3D rendering pipeline
- `NodGL_CAP_SHADER_SUPPORT`: Programmable shaders
- `NodGL_CAP_VSYNC`: Vertical sync support

### Resource Management

#### `NodGL_CreateTexture`
```c
int NodGL_CreateTexture(
    NodGL_Device device,
    const NodGL_TextureDesc *desc,
    NodGL_Texture *out_texture
);
```

Creates a texture resource.

**Texture Formats:**
- `NodGL_FORMAT_R8G8B8A8_UNORM`: 32-bit RGBA (0xAABBGGRR)
- `NodGL_FORMAT_B8G8R8A8_UNORM`: 32-bit BGRA (0xAARRGGBB)
- `NodGL_FORMAT_R5G6B5_UNORM`: 16-bit RGB
- `NodGL_FORMAT_R8_UNORM`: 8-bit grayscale

#### `NodGL_CreateBuffer`
```c
int NodGL_CreateBuffer(
    NodGL_Device device,
    const NodGL_BufferDesc *desc,
    NodGL_Buffer *out_buffer
);
```

Creates a generic buffer resource (vertex buffer, etc.).

#### `NodGL_MapResource` / `NodGL_UnmapResource`
```c
int NodGL_MapResource(
    NodGL_Context ctx,
    NodGL_Resource resource,
    void **out_data,
    uint32_t *out_pitch
);

void NodGL_UnmapResource(NodGL_Context ctx, NodGL_Resource resource);
```

Maps a resource for CPU access and unmaps it when done.

### Rendering Commands

#### `NodGL_Clear`
```c
int NodGL_Clear(
    NodGL_Context ctx,
    uint32_t flags,
    uint32_t color,
    float depth,
    uint8_t stencil
);
```

Clears the render target.

**Clear Flags:**
- `NodGL_CLEAR_COLOR`: Clear color buffer
- `NodGL_CLEAR_DEPTH`: Clear depth buffer
- `NodGL_CLEAR_STENCIL`: Clear stencil buffer

#### `NodGL_FillRect`
```c
int NodGL_FillRect(
    NodGL_Context ctx,
    int32_t x, int32_t y,
    uint32_t width, uint32_t height,
    uint32_t color
);
```

Fills a rectangle with a solid color.

#### `NodGL_DrawTexture`
```c
int NodGL_DrawTexture(
    NodGL_Context ctx,
    NodGL_Texture texture,
    int32_t src_x, int32_t src_y,
    int32_t dst_x, int32_t dst_y,
    uint32_t width, uint32_t height
);
```

Draws a texture region to the screen.

#### `NodGL_DrawLine`
```c
int NodGL_DrawLine(
    NodGL_Context ctx,
    int32_t x0, int32_t y0,
    int32_t x1, int32_t y1,
    uint32_t color,
    uint32_t thickness
);
```

Draws a line between two points.

#### `NodGL_Present`
```c
int NodGL_Present(NodGL_Context ctx, uint32_t sync_interval);
```

Presents the backbuffer to the screen.

**Parameters:**
- `sync_interval`: 0 = no vsync, 1+ = sync every N vblanks

### State Management

#### `NodGL_SetViewport`
```c
int NodGL_SetViewport(NodGL_Context ctx, const NodGL_Viewport *viewport);
```

Sets the rendering viewport.

#### `NodGL_SetScissorRect`
```c
int NodGL_SetScissorRect(NodGL_Context ctx, const NodGL_Rect *rect);
```

Sets the scissor rectangle for clipping.

#### `NodGL_SetBlendMode`
```c
int NodGL_SetBlendMode(NodGL_Context ctx, NodGL_BlendMode mode);
```

Sets the blend mode for rendering.

**Blend Modes:**
- `NodGL_BLEND_NONE`: No blending (opaque)
- `NodGL_BLEND_ALPHA`: Alpha blending
- `NodGL_BLEND_ADDITIVE`: Additive blending
- `NodGL_BLEND_MODULATE`: Modulate blending

## Example Code

### Basic Initialization

```c
#include "NodGL.h"

int main(void) {
    NodGL_Device device;
    NodGL_Context context;
    NodGL_FeatureLevel level;
    
    // Create device with minimum feature level 1.0
    if (NodGL_CreateDevice(NodGL_FEATURE_LEVEL_1_0, &device, &context, &level) != NodGL_OK) {
        printf("Failed to create device\n");
        return 1;
    }
    
    // Get device capabilities
    NodGL_DeviceCaps caps;
    NodGL_GetDeviceCaps(device, &caps);
    printf("Using adapter: %s\n", caps.adapter_name);
    
    // Render loop
    for (int frame = 0; frame < 100; frame++) {
        // Clear to blue
        NodGL_Clear(context, NodGL_CLEAR_COLOR, NodGL_ColorARGB(0xFF, 0, 0, 0xFF), 1.0f, 0);
        
        // Draw a red rectangle
        NodGL_FillRect(context, 100, 100, 200, 150, NodGL_ColorARGB(0xFF, 0xFF, 0, 0));
        
        // Present frame
        NodGL_Present(context, 1);
    }
    
    // Cleanup
    NodGL_ReleaseDevice(device);
    return 0;
}
```

### Texture Rendering

```c
// Create a 64x64 texture
NodGL_TextureDesc tex_desc = {0};
tex_desc.width = 64;
tex_desc.height = 64;
tex_desc.format = NodGL_FORMAT_R8G8B8A8_UNORM;
tex_desc.mip_levels = 1;

uint32_t *pixels = malloc(64 * 64 * 4);
// Fill with gradient...
for (int y = 0; y < 64; y++) {
    for (int x = 0; x < 64; x++) {
        pixels[y * 64 + x] = NodGL_ColorARGB(0xFF, x * 4, y * 4, 128);
    }
}

tex_desc.initial_data = pixels;
tex_desc.initial_data_size = 64 * 64 * 4;

NodGL_Texture texture;
NodGL_CreateTexture(device, &tex_desc, &texture);

// Draw the texture
NodGL_DrawTexture(context, texture, 0, 0, 100, 100, 64, 64);

// Cleanup
NodGL_ReleaseResource(device, texture);
free(pixels);
```

## Design Principles

NodGL was designed with the following principles:

1. **Clean separation** - Device manages resources, context issues commands
2. **Type safety** - Opaque handles prevent misuse
3. **Progressive enhancement** - Feature levels allow graceful degradation
4. **Performance** - Minimize overhead, maximize hardware utilization
5. **Simplicity** - Easy to learn, hard to misuse

## Files

### Headers
- `userland/nodgl.h` - NodGL API interface

### Implementation
- `userland/lib_nodgl.c` - NodGL library implementation

### Demo
- `userland/nodgl_demo.c` - Example application
- `userland/nodgl_build.sh` - Build script

## Future Enhancements

1. **3D Pipeline**
   - Vertex/index buffer support
   - Transformation matrices
   - Lighting models
   
2. **Shader Support**
   - Vertex shaders
   - Pixel/fragment shaders
   - Compute shaders (GPGPU)

3. **Advanced Features**
   - Multi-sampling anti-aliasing (MSAA)
   - Deferred rendering contexts
   - Resource views
   
4. **Performance**
   - Command batching
   - Multi-threaded resource creation
   - GPU timeline synchronization

## See Also

- [Graphics System](Graphics-System.md)
- [Driver API](Driver-API.md)
- [SQRM Modules](SQRELF-Formats.md)