readable examples

Makefile

@@ -11,7 +11,7 @@ CFLAGS += -Wshadow
 CFLAGS += -std=gnu11 
 CFLAGS += -Wno-unused-parameter
 CFLAGS += -Iinclude 
-#CFLAGS += -O3
+CFLAGS += -O3
 #CFLAGS += -fsanitize=address
 
 MINGW_FLAGS += -IC:\MinGW\include\ 

examples/basic_triangle.c

@@ -6,43 +6,116 @@
 #include "driver.h"
 #include "sr.h"
 
-float pts[9] = {
-    0.5, 0.5, 0,
-    -0.5, 0.5, 0,
-    0, -0.5, 0,
-};
+/**
+ * basic_triangle.c
+ * --------
+ * this is *almost* the bare minimum setup to
+ * produce some cool graphics with the sr library!
+ * 
+ */
+
+/*********************************************************************
+ *                                                                   *
+ *                      indexed triangle list                        *
+ *                                                                   *
+ *********************************************************************/
 
-int indices[3] = {
-    0, 1, 2
+float pts[18] = {
+    /* x y z */         /* r g b */
+    0.5, -0.5, 0.0,     0.0, 1.0, 0.0,
+    0.0, 0.5, 0.0,      1.0, 0.0, 0.0,
+    -0.5, -0.5, 0.0,    0.0, 0.0, 1.0
 };
 
+int indices[3] = {0, 1, 2};
+
+/*********************************************************************
+ *                                                                   *
+ *                          vertex shader                            *
+ *                                                                   *
+ *********************************************************************/
+
+/******
+ * vs *
+ ******/
+
+/* emits a clip space vertex given an object space vertex */
 static void 
 vs(float* out, float* in, void* uniform)
 {
-    memcpy(out, in, 3 * sizeof(float));
-    out[3] = 1;    /* homogenize */
+    float tmp[4] = { in[0], in[1], in[2], 1 };   /* homogenize */ 
+    memcpy(out, tmp, 4 * sizeof(float));         /* position */
+    memcpy(out + 4, in + 3, 3 * sizeof(float));  /* colors */
 }
 
+/*********************************************************************
+ *                                                                   *
+ *                         fragment shader                           *
+ *                                                                   *
+ *********************************************************************/
+
+/******
+ * fs *
+ ******/
+
+/* emits a pixel color per screen space vertex */
 static void
 fs(uint32_t* out, float* in, void* uniform) 
-{
-    *out = 0xAFF18FFF;
+{   
+    uint8_t a = 255;
+    uint8_t r = in[4] * 255;
+    uint8_t g = in[5] * 255;
+    uint8_t b = in[6] * 255;
+    *out = a << 24 | r << 16 | g << 8 | b << 0; 
 }
 
+/*********************************************************************
+ *                                                                   *
+ *                         prepare context                           *
+ *                                                                   *
+ *********************************************************************/
+
+/*********
+ * start *
+ *********/
+
+/* runs only once in the begining */
 extern void
-start()
+start()  
 {
-    sr_bind_pts(pts, 3, 3);
+    sr_bind_pts(pts, 3, 6);
     sr_bind_framebuffer(SCREEN_WIDTH, SCREEN_HEIGHT, colors, depths);
-    sr_bind_vs(vs, 4);
+    sr_bind_vs(vs, 7);
     sr_bind_fs(fs);
 }
 
+/*********************************************************************
+ *                                                                   *
+ *                           render image                            *
+ *                                                                   *
+ *********************************************************************/
+
+/**********
+ * update *
+ **********/
+
+/* runs every frame */
 extern void
 update(float dt)
 {
     sr_renderl(indices, 3, SR_TRIANGLE_LIST);
 }
 
+/*********************************************************************
+ *                                                                   *
+ *                        free program data                          *
+ *                                                                   *
+ *********************************************************************/
+
+/*******
+ * end *
+ *******/
+
+/* runs once at the end of the program */
 extern void
 end() { /* not implemented */ }

examples/bunny.c

@@ -4,15 +4,42 @@
 #include <stdlib.h>
 #include "sr.h"
 
+/**
+ * bunny.c
+ * --------
+ * this is the minimal code needed to load an .obj
+ * file and render it with a single directional light
+ * 
+ */
+
+/*********************************************************************
+ *                                                                   *
+ *                           vertex data                             *
+ *                                                                   *
+ *********************************************************************/
+
 struct sr_obj* obj;
 
+/*********************************************************************
+ *                                                                   *
+ *                         prepare context                           *
+ *                                                                   *
+ *********************************************************************/
+
+/*********
+ * start *
+ *********/
+
+/* runs only once in the begining */
 extern void
 start()
 {
-    for (int i = 0; i < SCREEN_WIDTH * SCREEN_HEIGHT; i++) {
-        colors[i] = 1;
-        depths[i] = 1000;
-    }
+
+/*********************************************************************
+ *                                                                   *
+ *                           light data                              *
+ *                                                                   *
+ *********************************************************************/
 
     float light_dir[3] = {0, -1, 0};
     float light_color[4] = {1, 1, 1, 1};
@@ -29,6 +56,12 @@ start()
     float kd = 0.5;
     float ks = 0.5;
 
+/*********************************************************************
+ *                                                                   *
+ *                         light bindings                            *
+ *                                                                   *
+ *********************************************************************/
+
     sr_glight(SR_AMBIENT, &ka);
     sr_glight(SR_DIFFUSE, &kd);
     sr_glight(SR_SPECULAR, &ks);
@@ -41,14 +74,31 @@ start()
     sr_light(SR_LIGHT_1, SR_QUADRATIC_ATTENUATION, &light_attn_quad);
     sr_light_enable(SR_LIGHT_1);
 
+/*********************************************************************
+ *                                                                   *
+ *                         material bindings                         *
+ *                                                                   *
+ *********************************************************************/
+
     sr_material(SR_AMBIENT, material_ambient);
     sr_material(SR_DIFFUSE, material_diffuse);
     sr_material(SR_SPECULAR, material_specular);
     sr_material(SR_SHININESS, &material_shininess);
-    sr_material_enable();
+
+/*********************************************************************
+ *                                                                   *
+ *                      load obj file into RAM                       *
+ *                                                                   *
+ *********************************************************************/
 
     obj = sr_load_obj("./assets/bunny.obj");
 
+/*********************************************************************
+ *                                                                   *
+ *                        prepare sr context                         *
+ *                                                                   *
+ *********************************************************************/
+
     sr_bind_pts(obj->pts, obj->n_pts, obj->n_attr);
     sr_bind_framebuffer(SCREEN_WIDTH, SCREEN_HEIGHT, colors, depths);
     sr_bind_std_vs();
@@ -61,12 +111,35 @@ start()
     sr_rotate_y(0.6);
 }
 
+/*********************************************************************
+ *                                                                   *
+ *                           render image                            *
+ *                                                                   *
+ *********************************************************************/
+
+/**********
+ * update *
+ **********/
+
+/* runs every frame */
 extern void
 update(float dt)
 {
     sr_renderl(obj->indices, obj->n_indices, SR_TRIANGLE_LIST);
+    sr_rotate_y(dt);
 }
 
+/*********************************************************************
+ *                                                                   *
+ *                        free program data                          *
+ *                                                                   *
+ *********************************************************************/
+
+/*******
+ * end *
+ *******/
+
+/* runs once at the end of the program */
 extern void
 end()
 {

examples/driver.c

@@ -5,6 +5,12 @@
 
 #include "driver.h"
 
+/*********************************************************************
+ *                                                                   *
+ *                          initialize data                          *
+ *                                                                   *
+ *********************************************************************/
+
 int SCREEN_WIDTH = 1024;
 int SCREEN_HEIGHT = 768;
 
@@ -13,7 +19,7 @@ float* depths;
 
 /*********************************************************************
  *                                                                   *
- *                             placeholder                           *
+ *                            render loop                            *
  *                                                                   *
  *********************************************************************/
 
@@ -25,10 +31,14 @@ float* depths;
 int 
 main(int argc, char* args[])
 {
+    /* allocate frame buffers */
+
     colors = malloc(SCREEN_WIDTH * SCREEN_HEIGHT * sizeof(uint32_t));
     depths = malloc(SCREEN_WIDTH * SCREEN_HEIGHT * sizeof(float));
 
-    start();
+    start();     /* call example's start code */
+
+    /* SDL setup magic */
 
     SDL_Init(SDL_INIT_VIDEO);
 
@@ -45,14 +55,19 @@ main(int argc, char* args[])
                            SDL_PIXELFORMAT_ARGB8888, 
                            SDL_TEXTUREACCESS_STREAMING, 
                            SCREEN_WIDTH, SCREEN_HEIGHT);
+
+    /* the loop */
     
     int quit = 0;
     int cur_time = 0;
+    int prev_sec = 0;
     int prev_time = 0;
     int frame = 0;
 
     while (!quit) {
 
+        cur_time = SDL_GetTicks();
+        
         /* check if quit */
 
         SDL_Event event;
@@ -69,7 +84,10 @@ main(int argc, char* args[])
             colors[i] = 0;
             depths[i] = 1000;
         }
-        update(0.4);
+        float dt = (cur_time - prev_time) / (float) 1000;
+
+     
+        update(dt);   /* call example's update code */
 
         SDL_UpdateTexture(texture, NULL, colors, SCREEN_WIDTH * 4);
         SDL_RenderCopy(renderer, texture, NULL, NULL);
@@ -77,17 +95,19 @@ main(int argc, char* args[])
 
         /* display fps */
 
-        cur_time = SDL_GetTicks();
-        if (cur_time > prev_time + 1000) {
+        if (cur_time > prev_sec + 1000) {
             printf("FPS: %d\n", frame);
             frame = 0;
-            prev_time = cur_time;
+            prev_sec = cur_time;
         }
+
+        prev_time = cur_time;
         frame++;
     }
 
-    /* free example memory */
-    end();
+    /* free program memory */
+
+    end();  /* call example's end code */
     free(colors);
     free(depths);
     

examples/driver.h

@@ -1,14 +1,35 @@
-#ifndef EXAMPLE_H
-#define EXAMPLE_H
+#ifndef DRIVER_H
+#define DRIVER_H
 
 #include <stdint.h>
 
+/**
+ * driver.h
+ * --------
+ * acts as a backend for all example code--
+ * boots up SDL and creates a nice API (start, update, end) 
+ * to abstract all the nasty SDL specifics away
+ * 
+ */
+
+/*********************************************************************
+ *                                                                   *
+ *                    screen dimensions & buffers                    *
+ *                                                                   *
+ *********************************************************************/
+
 extern int SCREEN_WIDTH;
 extern int SCREEN_HEIGHT;
 
 extern uint32_t* colors;
 extern float* depths;
 
+/*********************************************************************
+ *                                                                   *
+ *                           examples' API                           *
+ *                                                                   *
+ *********************************************************************/
+
 extern void
 start();
 
@@ -18,4 +39,4 @@ update(float dt);
 extern void
 end();
 
-#endif /* EXAMPLE_H */
+#endif /* DRIVER_H */