image.h

Go to the documentation of this file.

#pragma once
 
#include "../color.h"
 
#include "../gapi.h"
#include "../position.h"
#include "./position.h"
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
// --- Image Structure ---
 
/**
 * @brief Structure representing the 2D projected output of a 3D scene.
 *
 * This struct acts as a buffer containing the 2D screen-space coordinates,
 * colors, and indices of triangles generated by the 3D projection pipeline.
 * It also manages internal scratch buffers for optimization.
 */
typedef struct {
  // Public Data: Result of projection
  gmPos *vertices;   /**< Array of 2D screen-space vertex positions. */
  gmColor *colors;   /**< Array of colors, one per triangle. */
  size_t *triangles; /**< Array of vertex indices, 3 per triangle. */
  double *depths;    /**< Array of average Z-depths, one per triangle, used for sorting. */
 
  // Active counts for the current frame
  size_t n_vertices;  /**< Current number of vertices stored. */
  size_t n_colors;    /**< Current number of colors stored (should match n_triangles). */
  size_t n_triangles; /**< Current number of triangles stored. */
 
  // Actual allocated memory size (Capacity)
  size_t cap_vertices;  /**< Allocated capacity for vertices array. */
  size_t cap_colors;    /**< Allocated capacity for colors array. */
  size_t cap_triangles; /**< Allocated capacity for triangles (indices) array. */
  size_t cap_depths;    /**< Allocated capacity for depths array. */
 
  // --- Optimization: Per-Image Scratch Buffers ---
  // These allow us to reuse memory across frames for THIS specific image
  // without using global variables that break when multiple images exist.
  struct {
    gm3Pos *world_verts; /**< Temp storage for 3D world coordinates before projection. */
    size_t cap_world;    /**< Allocated capacity for world_verts. */
 
    void *sort_buf; /**< Temp storage for sorting triangles by depth. */
    size_t cap_sort; /**< Allocated capacity for sort_buf. */
 
    double *tri;     /**< Temp storage for sorted triangle vertex data (x1,y1,x2,y2,x3,y3). */
    gmColor *cols;   /**< Temp storage for sorted triangle colors. */
    size_t cap_tri;  /**< Allocated capacity for tri and cols. */
 
  } _internal; /**< Internal scratch buffers for rendering optimizations. */
 
} gm3Image;
 
/**
 * @brief Initializes a new `gm3Image` struct.
 *
 * This function creates a `gm3Image` instance and ensures all its internal
 * pointers are NULL and counts are zero, preventing undefined behavior.
 *
 * @return A new, zero-initialized `gm3Image` instance.
 */
static inline gm3Image gm3_image() {
  return (gm3Image){0}; // Zero-init guarantees NULL pointers
}
 
/**
 * Call this at the start of a new frame.
 * It resets the counters so you can overwrite data,
 * but keeps the heavy memory allocations alive for speed.
 */
static inline void gm3_image_reset(gm3Image *i) {
  i->n_vertices = 0;
  i->n_triangles = 0;
  i->n_colors = 0;
  // We do NOT free the arrays here. That's the optimization.
}
 
/**
 * Call this when you are completely done with the image object
 * and want to release memory to the OS.
 */
void gm3_image_free(gm3Image *i) {
  if (i->vertices)
    free(i->vertices);
  if (i->colors)
    free(i->colors);
  if (i->triangles)
    free(i->triangles);
  if (i->depths)
    free(i->depths);
 
  // Free the scratch buffers too
  if (i->_internal.world_verts)
    free(i->_internal.world_verts);
  if (i->_internal.sort_buf)
    free(i->_internal.sort_buf);
  if (i->_internal.tri)
    free(i->_internal.tri);
  if (i->_internal.cols)
    free(i->_internal.cols);
 
  memset(i, 0, sizeof(gm3Image));
}
 
/**
 * @internal
 * @brief Ensures the allocated capacity for `gm3Image` buffers is sufficient.
 *
 * This helper function reallocates internal buffers (vertices, triangles, colors, depths)
 * if the `new_v` (new vertex count) or `new_t` (new triangle count) exceeds
 * the current capacity. It uses a doubling strategy for efficiency.
 *
 * @param img Pointer to the `gm3Image` to check/resize.
 * @param new_v The minimum required vertex capacity.
 * @param new_t The minimum required triangle capacity.
 * @return 1 on success, 0 on memory allocation failure.
 */
static inline int gm3_image_ensure_cap(gm3Image *img, size_t new_v,
                                       size_t new_t) {
  // 1. Resize Vertex buffer if needed
  if (new_v > img->cap_vertices) {
    size_t new_cap = img->cap_vertices == 0 ? new_v : img->cap_vertices * 2;
    if (new_cap < new_v)
      new_cap = new_v + 128; // Padding
 
    void *tmp = realloc(img->vertices, new_cap * sizeof(gmPos));
    if (!tmp)
      return 0;
    img->vertices = tmp;
    img->cap_vertices = new_cap;
  }
 
  // 2. Resize Triangle buffers (indices, colors, depths) if needed
  if (new_t > img->cap_triangles) {
    size_t new_cap = img->cap_triangles == 0 ? new_t : img->cap_triangles * 2;
    if (new_cap < new_t)
      new_cap = new_t + 128;
 
    void *t_ptr = realloc(img->triangles, new_cap * 3 * sizeof(size_t));
    void *c_ptr = realloc(img->colors, new_cap * sizeof(gmColor));
    void *d_ptr = realloc(img->depths, new_cap * sizeof(double));
 
    if (!t_ptr || !c_ptr || !d_ptr)
      return 0;
 
    img->triangles = t_ptr;
    img->colors = c_ptr;
    img->depths = d_ptr;
    img->cap_triangles = new_cap;
    img->cap_colors = new_cap;
    img->cap_depths = new_cap;
  }
  return 1;
}
 
// --- Drawing Logic ---
 
/**
 * @internal
 * @brief Helper struct for sorting triangles by depth.
 */
typedef struct {
  size_t tri_idx; /**< The index of the triangle in the original arrays. */
  double z;       /**< The Z-depth of the triangle. */
} _gmImageDepthEntry;
 
/**
 * @internal
 * @brief Comparison function for `qsort` to sort `_gmImageDepthEntry` by Z-depth.
 *
 * Sorts triangles from farthest Z to nearest Z (Painter's Algorithm).
 *
 * @param a Pointer to the first `_gmImageDepthEntry`.
 * @param b Pointer to the second `_gmImageDepthEntry`.
 * @return -1 if `a` is farther, 1 if `b` is farther, 0 if equal.
 */
int _gm3_depth_compare(const void *a, const void *b) {
  _gmImageDepthEntry *ra = (_gmImageDepthEntry *)a;
  _gmImageDepthEntry *rb = (_gmImageDepthEntry *)b;
  // Sort Farthest Z to Nearest Z (Painters Algorithm)
  if (rb->z < ra->z)
    return -1;
  else if (rb->z > ra->z)
    return 1;
  else
    return 0;
}
 
#ifndef GM_NO_GAPI
/**
 * @brief Draws the projected 3D scene contained within a `gm3Image` onto the screen.
 *
 * This function sorts the projected triangles by depth (Painter's Algorithm)
 * and then calls the `gapi_draw_triangles` function to render them.
 *
 * @param img Pointer to the `gm3Image` containing the projected scene data.
 * @param x The X-offset for drawing the entire image.
 * @param y The Y-offset for drawing the entire image.
 * @param scale The scaling factor to apply to the projected image.
 * @return 1 on successful drawing, 0 if no triangles to draw, -1 on memory allocation failure.
 */
int gm3_draw_image(gm3Image *img, double x, double y, double scale) {
  if (!img || img->n_triangles == 0)
    return 0;
 
  // 1. Ensure Sort Buffer Capacity (stored in the image struct)
  if (img->n_triangles > img->_internal.cap_sort) {
    size_t new_cap = img->n_triangles + 512;
    void *tmp =
        realloc(img->_internal.sort_buf, new_cap * sizeof(_gmImageDepthEntry));
    if (!tmp)
      return -1;
    img->_internal.sort_buf = tmp;
    img->_internal.cap_sort = new_cap;
  }
 
  _gmImageDepthEntry *sort_arr = (_gmImageDepthEntry *)img->_internal.sort_buf;
 
  // 2. Fill Sort Buffer
  for (size_t i = 0; i < img->n_triangles; i++) {
    sort_arr[i].tri_idx = i;
    sort_arr[i].z = img->depths[i];
  }
 
  // 3. Sort
  qsort(sort_arr, img->n_triangles, sizeof(_gmImageDepthEntry),
        _gm3_depth_compare);
 
  // 4. Draw Loop
  gmPos *verts = img->vertices;
  gmColor *cols = img->colors;
  size_t *indices = img->triangles;
 
  if (img->_internal.cap_tri < img->n_triangles) {
    if (img->_internal.tri) {
      free(img->_internal.tri);
      free(img->_internal.cols);
    }
    img->_internal.tri = malloc(img->n_triangles * 6 * sizeof(double));
    img->_internal.cols = malloc(img->n_triangles * sizeof(gmColor));
    img->_internal.cap_tri = img->n_triangles;
    if (!img->_internal.tri || !img->_internal.cols) {
      if (img->_internal.tri)
        free(img->_internal.tri);
      if (img->_internal.cols)
        free(img->_internal.cols);
      return -1;
    }
  }
 
  for (size_t i = 0; i < img->n_triangles; i++) {
    size_t tidx = sort_arr[i].tri_idx;
    size_t idx_base = tidx * 3;
    img->_internal.cols[i] = img->colors[tidx];
 
    for (size_t j = 0; j < 3; j++) {
      img->_internal.tri[i * 6 + j * 2 + 0] =
          verts[indices[idx_base + j]].x * scale + x;
      img->_internal.tri[i * 6 + j * 2 + 1] =
          verts[indices[idx_base + j]].y * scale + y;
    }
  }
  gapi_draw_triangles(img->n_triangles, img->_internal.tri,
                      img->_internal.cols);
  return 1;
}
#endif