Skip to content

NodGL API

Jump to bottom
NtinosTheGamer2324 edited this page Mar 7, 2026 · 1 revision

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

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

void NodGL_ReleaseDevice(NodGL_Device device);

Releases the device and all associated resources.

NodGL_GetDeviceCaps

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

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

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 

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

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

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

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

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

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

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

Sets the rendering viewport.

NodGL_SetScissorRect

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

Sets the scissor rectangle for clipping.

NodGL_SetBlendMode

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

#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

// 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

Clone this wiki locally