From f74d903472b1542bacbd42d8fd78ef985c2c334b Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:26:57 +0000 Subject: [PATCH 1/8] Add detailed documentation for blit_rgn1_slip function Enhance the documentation for the blit_rgn1_slip function to clarify its purpose and behaviour. The updated comments explain how the function adjusts the region's origins and extent to ensure non-negative values, and specify the return values based on the region's position relative to positive space. --- inc/blit/rgn1.h | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/inc/blit/rgn1.h b/inc/blit/rgn1.h index a2d1f87..16b1112 100644 --- a/inc/blit/rgn1.h +++ b/inc/blit/rgn1.h @@ -61,6 +61,18 @@ static inline void blit_rgn1_norm(struct blit_rgn1 *rgn1) { assert(rgn1->extent >= 0); } +/*! + * \brief Slip a one-dimensional region into positive space. + * \details This function adjusts a one-dimensional region represented by the + * \c blit_rgn1 structure to ensure that both the origin and source origin are + * non-negative. If either the origin or source origin is negative, the region + * is "slipped" into positive space by adjusting the origins and reducing the + * extent accordingly. If the entire region is outside positive space, the + * function returns false. + * \param rgn1 Pointer to the \c blit_rgn1 structure to slip. + * \retval true if the region was successfully slipped into positive space. + * \retval false if the entire region is outside positive space. + */ static inline bool blit_rgn1_slip(struct blit_rgn1 *rgn1) { int offset = rgn1->origin < 0 ? (rgn1->origin < rgn1->origin_source ? -rgn1->origin : -rgn1->origin_source) : (rgn1->origin_source < 0 ? -rgn1->origin_source : 0); From d0606d689311a2e6bb5b8ed5dddca3e6f5b0ebf9 Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:29:00 +0000 Subject: [PATCH 2/8] Fix header guard formatting in rgn1.h Adjusted the formatting of the header guard in the rgn1.h file. --- inc/blit/rgn1.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inc/blit/rgn1.h b/inc/blit/rgn1.h index 16b1112..a51ff39 100644 --- a/inc/blit/rgn1.h +++ b/inc/blit/rgn1.h @@ -11,7 +11,7 @@ * clipping the region. */ - #ifndef __BLIT_RGN1_H__ +#ifndef __BLIT_RGN1_H__ #define __BLIT_RGN1_H__ #include From a072b74b934145717fbe99b1978987cc3e6d54c9 Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:29:20 +0000 Subject: [PATCH 3/8] Refactor blit_rgn1_slip for improved readability Reformat the calculation of the offset in the blit_rgn1_slip function to enhance clarity. The conditional logic is now more readable with proper indentation and line breaks. --- inc/blit/rgn1.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/inc/blit/rgn1.h b/inc/blit/rgn1.h index a51ff39..9818bdf 100644 --- a/inc/blit/rgn1.h +++ b/inc/blit/rgn1.h @@ -74,8 +74,10 @@ static inline void blit_rgn1_norm(struct blit_rgn1 *rgn1) { * \retval false if the entire region is outside positive space. */ static inline bool blit_rgn1_slip(struct blit_rgn1 *rgn1) { - int offset = - rgn1->origin < 0 ? (rgn1->origin < rgn1->origin_source ? -rgn1->origin : -rgn1->origin_source) : (rgn1->origin_source < 0 ? -rgn1->origin_source : 0); + int offset = rgn1->origin < 0 + ? (rgn1->origin < rgn1->origin_source ? -rgn1->origin + : -rgn1->origin_source) + : (rgn1->origin_source < 0 ? -rgn1->origin_source : 0); assert(offset >= 0); if (offset >= rgn1->extent) return false; From 91cbd3f2abe0559f16a3a0902133aee298d7622c Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:29:47 +0000 Subject: [PATCH 4/8] Remove unused editor options from README.md This change cleans up the README file by removing unnecessary editor configuration options that are not relevant to the project documentation. --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index e42673d..2fc11a7 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,3 @@ ---- -editor_options: - markdown: - wrap: 72 ---- - # Blit Blit (bit-block transfer) operations on planes of bits. This library From eca9cb5168339df9205150b6f1bad2767d04d21b Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:40:42 +0000 Subject: [PATCH 5/8] Update Doxygen configuration for improved documentation generation Set README.md as the main page for Doxygen documentation. Updated the source directories for Doxygen to include the project's source and exclude the binary directory. --- CMakeLists.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0f91c19..b832743 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,7 +39,11 @@ add_test(NAME left_shift_edge COMMAND test_runner test/left_shift_edge) # https://www.mcternan.me.uk/mscgen/ find_package(Doxygen OPTIONAL_COMPONENTS dot mscgen dia) if(DOXYGEN_FOUND) + set (DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md) set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) set(DOXYGEN_SOURCE_BROWSER YES) - doxygen_add_docs(doxy ${PROJECT_SOURCE_DIR}/inc ${PROJECT_SOURCE_DIR}/src) + set (DOXYGEN_EXCLUDE ${CMAKE_BINARY_DIR}) + doxygen_add_docs(doxy ${CMAKE_SOURCE_DIR} + COMMENT "Generating API documentation with Doxygen" + ) endif() From 05a79e1db5ee41ffc69553e5a28ccdc1615043bf Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:43:54 +0000 Subject: [PATCH 6/8] fix: standardise code block formatting in README.md Updated code block syntax in README.md to ensure consistent formatting across examples. Changed language identifiers from 'c' to '```c' and 'bash' to '```bash' for Doxygen compatibility. --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 2fc11a7..89962d3 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ unsigned integers (`blit_scanline_t` type). Key properties: **Example:** -``` c +```c BLIT_SCAN_DEFINE(image, 800, 600); // 800×600 bit image ``` @@ -94,7 +94,7 @@ All 16 binary operations combining source (S) and destination (D): Common operations have aliases: -``` c +```c blit_rop2_copy = blit_rop2_S blit_rop2_invert = blit_rop2_Sn blit_rop2_xor = blit_rop2_DSx @@ -113,7 +113,7 @@ Handles efficient bit-level alignment between source and destination: ### Low-Level API: `blit_rgn1_rop2` -``` c +```c bool blit_rgn1_rop2(struct blit_scan *result, struct blit_rgn1 *x, struct blit_rgn1 *y, @@ -136,7 +136,7 @@ bool blit_rgn1_rop2(struct blit_scan *result, ### Convenience API: `blit_rop2` -``` c +```c bool blit_rop2(struct blit_scan *result, int x, int y, int x_extent, int y_extent, const struct blit_scan *source, @@ -162,7 +162,7 @@ region inspection ### Copy a 32×32 region -``` c +```c BLIT_SCAN_DEFINE(dest, 256, 256); BLIT_SCAN_DEFINE(source, 256, 256); @@ -172,14 +172,14 @@ blit_rop2(&dest, 50, 50, 32, 32, &source, 100, 50, blit_rop2_copy); ### Invert a region -``` c +```c // Invert a 64×64 area at (0,0) in an image. blit_rop2(&image, 0, 0, 64, 64, &image, 0, 0, blit_rop2_invert); ``` ### XOR pattern overlay -``` c +```c BLIT_SCAN_DEFINE(pattern, 8, 8); BLIT_SCAN_DEFINE(canvas, 640, 480); @@ -193,7 +193,7 @@ for (int y = 0; y < 480; y += 8) { ### Using region structures (advanced) -``` c +```c struct blit_rgn1 x_rgn = {.origin = 10, .extent = 50, .origin_source = 20}; struct blit_rgn1 y_rgn = {.origin = 10, .extent = 50, .origin_source = 20}; @@ -212,7 +212,7 @@ if (blit_rgn1_rop2(&dest, &x_rgn, &y_rgn, &source, blit_rop2_and)) { ### Build Commands -``` bash +```bash mkdir build cd build cmake .. @@ -221,7 +221,7 @@ cmake --build . ### Running Tests -``` bash +```bash cd build ctest # Run all tests ctest --verbose # With detailed output @@ -236,7 +236,7 @@ Each of the 16 ROP2 codes maps to a static function implementing the bitwise operation. Take one example: the DSx (destination XOR source in reverse Polish) operation: -``` c +```c // Example: DSx (XOR) operation. static blit_scanline_t ropDSx(blit_scanline_t fetch, blit_scanline_t store) { return fetch ^ store; @@ -294,7 +294,7 @@ combinations. Run all tests using the following: -``` bash +```bash cd build ctest --verbose ``` From e015e6cb9d3cdf6923ab62006609fcb1530a1479 Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 11:51:20 +0000 Subject: [PATCH 7/8] feat: add GitHub Actions workflow for Doxygen documentation Create a new workflow to automate the generation and deployment of documentation using Doxygen. This includes steps for checking out the repository, installing dependencies, generating the documentation, and deploying it to GitHub Pages. --- .github/workflows/doxygen.yml | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .github/workflows/doxygen.yml diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml new file mode 100644 index 0000000..9d023a5 --- /dev/null +++ b/.github/workflows/doxygen.yml @@ -0,0 +1,35 @@ +name: Build Documentation + +on: + push: + branches: [ main ] + pull_request: + + # Allows running this workflow manually from the Actions tab. + workflow_dispatch: + +permissions: + contents: write + +jobs: + generate-docs: + concurrency: ci-${{ github.ref }} + runs-on: ubuntu-latest + steps: + - name: Checkout 🛎️ + uses: actions/checkout@v4 + + - name: Install Doxygen and Dependencies 📦 + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz mscgen dia + + - name: Generate Documentation 🔧 + run: | + cmake -S . -B build + cmake --build build --target doxy + + - name: Deploy Pages 🚀 + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: build/html From acb6e66aa4d8cadd0e9860dd9fec69b644671945 Mon Sep 17 00:00:00 2001 From: Roy Ratcliffe Date: Fri, 2 Jan 2026 12:01:59 +0000 Subject: [PATCH 8/8] fix: standardise spacing in Doxygen configuration Removed unnecessary spaces in the Doxygen settings to ensure consistent formatting and improve readability. --- CMakeLists.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index b832743..2ab8525 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -39,10 +39,10 @@ add_test(NAME left_shift_edge COMMAND test_runner test/left_shift_edge) # https://www.mcternan.me.uk/mscgen/ find_package(Doxygen OPTIONAL_COMPONENTS dot mscgen dia) if(DOXYGEN_FOUND) - set (DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md) + set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md) set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) set(DOXYGEN_SOURCE_BROWSER YES) - set (DOXYGEN_EXCLUDE ${CMAKE_BINARY_DIR}) + set(DOXYGEN_EXCLUDE ${CMAKE_BINARY_DIR}) doxygen_add_docs(doxy ${CMAKE_SOURCE_DIR} COMMENT "Generating API documentation with Doxygen" )