add changelog to docs

MAKE.bat

@@ -340,11 +340,13 @@ if "%1"=="docs" (
     set /p GIT_BRANCH=<info.obj
     date /t > info.obj
     set /p LAST_MODIFIED=<info.obj
+    git --no-pager log --pretty="format:%%h: %%s (**%%cN**)" > changelog.txt
 
     rem ...and generate docs
     cl   tools\docs\docs.c engine\v4k.c -Iengine %2
     docs engine\v4k.h --excluded=3rd_glad.h,v4k.h,v4k_compat.h, > v4k.html
     move /y v4k.html engine\
+    del changelog.txt
 
     exit /b
 )
@@ -461,7 +463,6 @@ if "%1"=="web" (
 )
 
 if "%1"=="vps" (
-    call make.bat git
     tools\pscp -4 -batch -agent -P 22 -l app engine\v4k.html 128.140.14.212:/home/app/microblog/app/static/v4k/index.html
     rem tools\pscp -4 -batch -agent -P 22 -l app engine\joint\v4k.h 128.140.14.212:/home/app/microblog/app/static/v4k/v4k.h
     exit /b

demos/99-compute.c

@@ -26,7 +26,7 @@ int main() {
         ssbo_bind(buf, 1);
         ssbo_update(0, sizeof(data), &data);
         
-        dispatch(TEX_WIDTH/10, TEX_WIDTH/10, 1);
+        compute_dispatch(TEX_WIDTH/10, TEX_WIDTH/10, 1);
         image_write_barrier();
         
         fullscreen_quad_rgb(tex, 2.2);

engine/bind/v4k.lua

@@ -2366,7 +2366,7 @@ WRITE,
 READ_WRITE
 };
  unsigned compute(const char *cs);
- void dispatch(unsigned wx, unsigned wy, unsigned wz);
+ void compute_dispatch(unsigned wx, unsigned wy, unsigned wz);
  void shader_image(texture_t t, unsigned unit, unsigned level, int layer, unsigned access);
  void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer, unsigned texel_type, unsigned access);
  void image_write_barrier();

engine/joint/v4k.h

@@ -16490,14 +16490,51 @@ enum ACCESS_MODE {
     READ_WRITE
 };
 
+/// Loads the compute shader and compiles a GL program.
+/// return: GL program, 0 if failed.
+/// cs: shader source code
 API unsigned compute(const char *cs);
-API void dispatch(unsigned wx, unsigned wy, unsigned wz);
-API void shader_image(texture_t t, unsigned unit, unsigned level, int layer /* -1 to disable layered access */, unsigned access);
-API void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer /* -1 to disable layered access */, unsigned texel_type, unsigned access);
+
+/// Runs the compute program with provided global workgroup size on x y z grid.
+/// wx: global workgroup size x
+/// wy: global workgroup size y
+/// wz: global workgroup size z
+API void compute_dispatch(unsigned wx, unsigned wy, unsigned wz);
+
+/// Binds a texture to the program
+/// !!! Set `layer` to -1 to disable layered access.
+/// t: texture to bind
+/// unit: texture unit bind index
+/// level: texture level access (MIP0, MIP1, ...)
+/// layer: bind layer
+/// access: texture access policy
+/// see: ACCESS_MODE
+API void shader_image(texture_t t, unsigned unit, unsigned level, int layer, unsigned access);
+
+/// Binds a texture to the program
+/// !!! Set `layer` to -1 to disable layered access.
+/// texture: GL texture handle
+/// unit: texture unit bind index
+/// level: texture level access (MIP0, MIP1, ...)
+/// layer: bind layer
+/// texel_type: image texel format (RGBA8, RGBA32F, ...)
+/// access: texture access policy
+/// see: ACCESS_MODE
+API void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer, unsigned texel_type, unsigned access);
+
+// gpu memory barriers
+
+/// Blocks main thread until all image operations are done by the GPU.
 API void image_write_barrier();
+
+/// Blocks main thread until all memory operations are done by the GPU.
 API void write_barrier();
 
 // ssbo
+/// `STATIC`, `DYNAMIC` AND `STREAM` specify the frequency at which we intend to access the data.
+/// `DRAW` favors CPU->GPU operations.
+/// `READ` favors GPU->CPU operations.
+/// `COPY` favors CPU->GPU->CPU operations.
 enum USAGE_MODE {
     STATIC_DRAW,
     STATIC_READ,
@@ -16512,12 +16549,41 @@ enum USAGE_MODE {
     STREAM_COPY
 };
 
+/// Create Shader Storage Buffer Object
+/// !!! `data` can be NULL
+/// data: optional pointer to data to upload
+/// len: buffer size, must not be 0
+/// usage: buffer usage policy
+/// see: USAGE_MODE
 API unsigned ssbo_create(const void *data, int len, unsigned usage);
+
+/// Destroys an SSBO resource
 API void ssbo_destroy(unsigned ssbo);
+
+/// Updates an existing SSBO
+/// !!! `len` can not exceed the original buffer size specified in `ssbo_create` !
+/// offset: offset to buffer memory
+/// len: amount of data to write
+/// data: pointer to data we aim to write, can not be NULL
 API void ssbo_update(int offset, int len, const void *data);
+
+/// Bind an SSBO resource to the provided bind unit index
+/// ssbo: resource object
+/// unit: bind unit index
 API void ssbo_bind(unsigned ssbo, unsigned unit);
+
+/// Map an SSBO resource to the system memory
+/// !!! Make sure to `ssbo_unmap` the buffer once done working with it.
+/// access: buffer access policy
+/// return: pointer to physical memory of the buffer
+/// see: ACCESS_MODE
 API void *ssbo_map(unsigned access);
+
+/// Unmaps an SSBO resource
+/// !!! Pointer provided by `ssbo_map` becomes invalid.
 API void ssbo_unmap();
+
+/// Unbinds an SSBO resource
 API void ssbo_unbind();
 
 // -----------------------------------------------------------------------------
@@ -340165,7 +340231,7 @@ unsigned compute(const char *cs){
     #endif
 }
 
-void dispatch(unsigned wx, unsigned wy, unsigned wz){
+void compute_dispatch(unsigned wx, unsigned wy, unsigned wz){
     glDispatchCompute(wx, wy, wz);
 }
 

engine/split/v4k_render.c

@@ -225,7 +225,7 @@ unsigned compute(const char *cs){
     #endif
 }
 
-void dispatch(unsigned wx, unsigned wy, unsigned wz){
+void compute_dispatch(unsigned wx, unsigned wy, unsigned wz){
     glDispatchCompute(wx, wy, wz);
 }
 

engine/split/v4k_render.h

@@ -335,14 +335,51 @@ enum ACCESS_MODE {
     READ_WRITE
 };
 
+/// Loads the compute shader and compiles a GL program.
+/// return: GL program, 0 if failed.
+/// cs: shader source code
 API unsigned compute(const char *cs);
-API void dispatch(unsigned wx, unsigned wy, unsigned wz);
-API void shader_image(texture_t t, unsigned unit, unsigned level, int layer /* -1 to disable layered access */, unsigned access);
-API void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer /* -1 to disable layered access */, unsigned texel_type, unsigned access);
+
+/// Runs the compute program with provided global workgroup size on x y z grid.
+/// wx: global workgroup size x
+/// wy: global workgroup size y
+/// wz: global workgroup size z
+API void compute_dispatch(unsigned wx, unsigned wy, unsigned wz);
+
+/// Binds a texture to the program
+/// !!! Set `layer` to -1 to disable layered access.
+/// t: texture to bind
+/// unit: texture unit bind index
+/// level: texture level access (MIP0, MIP1, ...)
+/// layer: bind layer
+/// access: texture access policy
+/// see: ACCESS_MODE
+API void shader_image(texture_t t, unsigned unit, unsigned level, int layer, unsigned access);
+
+/// Binds a texture to the program
+/// !!! Set `layer` to -1 to disable layered access.
+/// texture: GL texture handle
+/// unit: texture unit bind index
+/// level: texture level access (MIP0, MIP1, ...)
+/// layer: bind layer
+/// texel_type: image texel format (RGBA8, RGBA32F, ...)
+/// access: texture access policy
+/// see: ACCESS_MODE
+API void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer, unsigned texel_type, unsigned access);
+
+// gpu memory barriers
+
+/// Blocks main thread until all image operations are done by the GPU.
 API void image_write_barrier();
+
+/// Blocks main thread until all memory operations are done by the GPU.
 API void write_barrier();
 
 // ssbo
+/// `STATIC`, `DYNAMIC` AND `STREAM` specify the frequency at which we intend to access the data.
+/// `DRAW` favors CPU->GPU operations.
+/// `READ` favors GPU->CPU operations.
+/// `COPY` favors CPU->GPU->CPU operations.
 enum USAGE_MODE {
     STATIC_DRAW,
     STATIC_READ,
@@ -357,12 +394,41 @@ enum USAGE_MODE {
     STREAM_COPY
 };
 
+/// Create Shader Storage Buffer Object
+/// !!! `data` can be NULL
+/// data: optional pointer to data to upload
+/// len: buffer size, must not be 0
+/// usage: buffer usage policy
+/// see: USAGE_MODE
 API unsigned ssbo_create(const void *data, int len, unsigned usage);
+
+/// Destroys an SSBO resource
 API void ssbo_destroy(unsigned ssbo);
+
+/// Updates an existing SSBO
+/// !!! `len` can not exceed the original buffer size specified in `ssbo_create` !
+/// offset: offset to buffer memory
+/// len: amount of data to write
+/// data: pointer to data we aim to write, can not be NULL
 API void ssbo_update(int offset, int len, const void *data);
+
+/// Bind an SSBO resource to the provided bind unit index
+/// ssbo: resource object
+/// unit: bind unit index
 API void ssbo_bind(unsigned ssbo, unsigned unit);
+
+/// Map an SSBO resource to the system memory
+/// !!! Make sure to `ssbo_unmap` the buffer once done working with it.
+/// access: buffer access policy
+/// return: pointer to physical memory of the buffer
+/// see: ACCESS_MODE
 API void *ssbo_map(unsigned access);
+
+/// Unmaps an SSBO resource
+/// !!! Pointer provided by `ssbo_map` becomes invalid.
 API void ssbo_unmap();
+
+/// Unbinds an SSBO resource
 API void ssbo_unbind();
 
 // -----------------------------------------------------------------------------

engine/v4k.c

@@ -11139,7 +11139,7 @@ unsigned compute(const char *cs){
     #endif
 }
 
-void dispatch(unsigned wx, unsigned wy, unsigned wz){
+void compute_dispatch(unsigned wx, unsigned wy, unsigned wz){
     glDispatchCompute(wx, wy, wz);
 }
 

engine/v4k.h

@@ -2573,14 +2573,51 @@ enum ACCESS_MODE {
     READ_WRITE
 };
 
+/// Loads the compute shader and compiles a GL program.
+/// return: GL program, 0 if failed.
+/// cs: shader source code
 API unsigned compute(const char *cs);
-API void dispatch(unsigned wx, unsigned wy, unsigned wz);
-API void shader_image(texture_t t, unsigned unit, unsigned level, int layer /* -1 to disable layered access */, unsigned access);
-API void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer /* -1 to disable layered access */, unsigned texel_type, unsigned access);
+
+/// Runs the compute program with provided global workgroup size on x y z grid.
+/// wx: global workgroup size x
+/// wy: global workgroup size y
+/// wz: global workgroup size z
+API void compute_dispatch(unsigned wx, unsigned wy, unsigned wz);
+
+/// Binds a texture to the program
+/// !!! Set `layer` to -1 to disable layered access.
+/// t: texture to bind
+/// unit: texture unit bind index
+/// level: texture level access (MIP0, MIP1, ...)
+/// layer: bind layer
+/// access: texture access policy
+/// see: ACCESS_MODE
+API void shader_image(texture_t t, unsigned unit, unsigned level, int layer, unsigned access);
+
+/// Binds a texture to the program
+/// !!! Set `layer` to -1 to disable layered access.
+/// texture: GL texture handle
+/// unit: texture unit bind index
+/// level: texture level access (MIP0, MIP1, ...)
+/// layer: bind layer
+/// texel_type: image texel format (RGBA8, RGBA32F, ...)
+/// access: texture access policy
+/// see: ACCESS_MODE
+API void shader_image_unit(unsigned texture, unsigned unit, unsigned level, int layer, unsigned texel_type, unsigned access);
+
+// gpu memory barriers
+
+/// Blocks main thread until all image operations are done by the GPU.
 API void image_write_barrier();
+
+/// Blocks main thread until all memory operations are done by the GPU.
 API void write_barrier();
 
 // ssbo
+/// `STATIC`, `DYNAMIC` AND `STREAM` specify the frequency at which we intend to access the data.
+/// `DRAW` favors CPU->GPU operations.
+/// `READ` favors GPU->CPU operations.
+/// `COPY` favors CPU->GPU->CPU operations.
 enum USAGE_MODE {
     STATIC_DRAW,
     STATIC_READ,
@@ -2595,12 +2632,41 @@ enum USAGE_MODE {
     STREAM_COPY
 };
 
+/// Create Shader Storage Buffer Object
+/// !!! `data` can be NULL
+/// data: optional pointer to data to upload
+/// len: buffer size, must not be 0
+/// usage: buffer usage policy
+/// see: USAGE_MODE
 API unsigned ssbo_create(const void *data, int len, unsigned usage);
+
+/// Destroys an SSBO resource
 API void ssbo_destroy(unsigned ssbo);
+
+/// Updates an existing SSBO
+/// !!! `len` can not exceed the original buffer size specified in `ssbo_create` !
+/// offset: offset to buffer memory
+/// len: amount of data to write
+/// data: pointer to data we aim to write, can not be NULL
 API void ssbo_update(int offset, int len, const void *data);
+
+/// Bind an SSBO resource to the provided bind unit index
+/// ssbo: resource object
+/// unit: bind unit index
 API void ssbo_bind(unsigned ssbo, unsigned unit);
+
+/// Map an SSBO resource to the system memory
+/// !!! Make sure to `ssbo_unmap` the buffer once done working with it.
+/// access: buffer access policy
+/// return: pointer to physical memory of the buffer
+/// see: ACCESS_MODE
 API void *ssbo_map(unsigned access);
+
+/// Unmaps an SSBO resource
+/// !!! Pointer provided by `ssbo_map` becomes invalid.
 API void ssbo_unmap();
+
+/// Unbinds an SSBO resource
 API void ssbo_unbind();
 
 // -----------------------------------------------------------------------------

tools/docs/docs.c

@@ -73,6 +73,7 @@
 int DO_CSS = 1;
 int DO_DEBUG = 0;
 int DO_README = 1;
+int DO_CHANGELOG = 1;
 
 // C preprocessor:
 // 1. remove all /* C comments */
@@ -892,6 +893,16 @@ int main(int argc, char **argv) {
     array_unique(macros, sort_strcmp);
     { char *sep = ""; for(int i = 0, end = array_count(macros); i < end; ++i)     printf("%s[%s](#%s)", sep, macros[i], macros[i]), sep = ", "; }
 
+    if ( DO_CHANGELOG ) {
+        printf("\n## c h a n g e l o g\n\n");
+        char *chg = file_read("changelog.txt");
+        strrepl(&chg, "\r\n", "\n");
+        for each_substring(chg, "\n", it) {
+            // printf("<details><summary>%s</summary></details>\n", it);
+            printf("* %s\n", it);
+        }
+    }
+
     puts("\n<script>");
     puts("\nmarkdeepOptions = {");
     puts("\n    tocStyle:'medium', /* auto,none,short,medium,long */");