pixelflow_canvas 0.7.3 → 0.7.5

data/docs/.gitignore

@@ -0,0 +1,15 @@
+# Not sure what a .gitignore is?
+# See: https://git-scm.com/docs/gitignore
+
+# These are directly copied from Jekyll's first-party docs on `.gitignore` files:
+# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control
+
+# Ignore the default location of the built site, and caches and metadata generated by Jekyll
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Ignore folders generated by Bundler
+.bundle/
+vendor/

data/docs/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.3.4" # installed by `gem jekyll`
+# gem "webrick"        # required when using Ruby >= 3 and Jekyll <= 4.2.2
+
+gem "just-the-docs", "0.10.0" # pinned to the current release
+# gem "just-the-docs"        # always download the latest release

data/docs/Gemfile.lock

@@ -0,0 +1,92 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    bigdecimal (3.1.8)
+    colorator (1.1.0)
+    concurrent-ruby (1.3.4)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.17.0)
+    ffi (1.17.0-arm64-darwin)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.28.1-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.28.1-x86_64-linux)
+      bigdecimal
+      rake (>= 13)
+    http_parser.rb (0.8.0)
+    i18n (1.14.6)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.4)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.10.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (6.0.1)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rexml (3.3.7)
+    rouge (4.3.0)
+    safe_yaml (1.0.5)
+    sass-embedded (1.80.5)
+      google-protobuf (~> 4.28)
+      rake (>= 13)
+    sass-embedded (1.80.5-arm64-darwin)
+      google-protobuf (~> 4.28)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  arm64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  jekyll (~> 4.3.4)
+  just-the-docs (= 0.10.0)
+
+BUNDLED WITH
+   2.5.9

data/{LICENSE.txt → docs/LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2024 Michael Specht
+Copyright (c) 2022 just-the-docs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/docs/README.md

@@ -0,0 +1,174 @@
+# just-the-docs-template
+
+This is a *bare-minimum* template to create a [Jekyll] site that:
+
+- uses the [Just the Docs] theme;
+- can be built and published on [GitHub Pages];
+- can be built and previewed locally, and published on other platforms.
+
+More specifically, the created site:
+
+- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem;
+- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages.
+
+To get started with creating a site, simply:
+
+1. click "[use this template]" to create a GitHub repository
+2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions
+
+If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](#hosting-your-docs-from-an-existing-project-repo).
+
+After completing the creation of your new site on GitHub, update it as needed:
+
+## Replace the content of the template pages
+
+Update the following files to your own content:
+
+- `index.md` (your new home page)
+- `README.md` (information for those who access your site repo on GitHub)
+
+## Changing the version of the theme and/or Jekyll
+
+Simply edit the relevant line(s) in the `Gemfile`.
+
+## Adding a plugin
+
+The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin.
+
+To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]:
+
+- Add the following to your site's `Gemfile`:
+
+  ```ruby
+  gem "jekyll-default-layout"
+  ```
+
+- And add the following to your site's `_config.yml`:
+
+  ```yaml
+  plugins:
+    - jekyll-default-layout
+  ```
+
+Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
+
+## Publishing your site on GitHub Pages
+
+1.  If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to:
+
+    ```yaml
+    title: YOUR TITLE
+    description: YOUR DESCRIPTION
+    theme: just-the-docs
+
+    url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME
+
+    aux_links: # remove if you don't want this link to appear on your pages
+      Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME
+    ```
+
+2.  Push your updated `_config.yml` to your site on GitHub.
+
+3.  In your newly created repo on GitHub:
+    - go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`.
+    - if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`.
+
+## Building and previewing your site locally
+
+Assuming [Jekyll] and [Bundler] are installed on your computer:
+
+1.  Change your working directory to the root directory of your site.
+
+2.  Run `bundle install`.
+
+3.  Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`.
+
+    The built site is stored in the directory `_site`.
+
+## Publishing your built site on a different platform
+
+Just upload all the files in the directory `_site`.
+
+## Customization
+
+You're free to customize sites that you create with this template, however you like!
+
+[Browse our documentation][Just the Docs] to learn more about how to use this theme.
+
+## Hosting your docs from an existing project repo
+
+You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/just-the-docs-template), you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a `docs` directory. You can clone the template to your local machine or download the `.zip` file to access the files.
+
+### Copy the template files
+
+1.  Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files.
+
+2.  Create a `docs` directory at your project root and copy all remaining template files into this directory.
+
+### Modify the GitHub Actions workflow
+
+The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the `pages.yml` file. You'll need to edit this file to that so that your build and deploy steps look to your `docs` directory, rather than the project root.
+
+1.  Set the default `working-directory` param for the build job.
+
+    ```yaml
+    build:
+      runs-on: ubuntu-latest
+      defaults:
+        run:
+          working-directory: docs
+    ```
+
+2.  Set the `working-directory` param for the Setup Ruby step.
+
+    ```yaml
+    - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: '${{ github.workspace }}/docs'
+    ```
+
+3.  Set the path param for the Upload artifact step:
+
+    ```yaml
+    - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: "docs/_site/"
+    ```
+
+4.  Modify the trigger so that only changes within the `docs` directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy.
+
+    ```yaml
+    on:
+      push:
+        branches:
+          - "main"
+        paths:
+          - "docs/**"
+    ```
+
+## Licensing and Attribution
+
+This repository is licensed under the [MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!
+
+The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows]. A copy of their MIT License is available in [actions/starter-workflows].
+
+----
+
+[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
+
+[Jekyll]: https://jekyllrb.com
+[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
+[GitHub Pages]: https://docs.github.com/en/pages
+[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
+[Bundler]: https://bundler.io
+[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate
+[`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout
+[`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag
+[MIT License]: https://en.wikipedia.org/wiki/MIT_License
+[starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml
+[actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE

data/docs/_config.yml

@@ -0,0 +1,11 @@
+title: Pixelflow Canvas
+description: A virtual CRT for old school graphics programming in Visual Studio Code.
+theme: just-the-docs
+
+url: https://github.com/specht/pixelflow_canvas_ruby
+
+aux_links:
+  Github: https://github.com/specht/pixelflow_canvas_ruby
+callouts:
+  info:
+    color: yellow

data/docs/advanced_use.md

@@ -0,0 +1,37 @@
+---
+title: Advanced use
+layout: page
+nav_order: 3
+---
+
+# Using masks
+
+Masks can be used to specify which parts of the image should be affected by drawing operations.
+
+To set a mask, use the `set_mask` method:
+
+```ruby
+canvas.set_mask do
+    add_color(5)
+end
+```
+
+In the example above, the mask is set to all pixels that currently have a color of 5. This means that any drawing operation will only affect pixels that have a color of 5 until the mask is removed.
+
+Remove a mask by calling the `remove_mask` method:
+
+```ruby
+canvas.remove_mask
+```
+# Saving the canvas
+
+You can save the canvas to a file using the `save_as_png` method.
+
+```ruby
+canvas.save_as_png("output.png")
+```
+
+# Event polling
+
+The Pixelflow Canvas is not just a canvas for drawing, it also has built-in event polling capabilities. You can use the `fetch_events` method to get the next event from the event queue.
+

data/docs/drawing_things.md

@@ -0,0 +1,296 @@
+---
+title: Drawing things
+layout: page
+nav_order: 2
+---
+
+<style>
+img.full {
+    width: 100%;
+    max-width: 100%;
+    margin: 0;
+    padding: 0;
+    image-rendering: pixelated;
+    border-radius: 1em;
+    box-shadow: 0 0 1em rgba(0, 0, 0, 0.2);
+    padding: 1em;
+}
+</style>
+
+# Drawing things
+
+The `Canvas` class provides a number of methods for drawing things on the canvas. These methods are used to draw pixels, lines, rectangles, circles, ellipses, arcs, Bézier curves, triangles, and text.
+
+## Drawing and reading pixels
+
+The `set_pixel` method sets the color of a single pixel on the canvas.
+
+```ruby
+canvas.set_pixel(160, 90, 10) # in palette mode
+canvas.set_pixel(160, 90, 0, 255, 0) # in RGB mode
+```
+
+To read the color of a pixel, use the `get_pixel` method.
+
+```ruby
+color = canvas.get_pixel(160, 90)
+```
+
+Depending on the color mode, the `get_pixel` method returns either a palette index or an array of RGB values.
+
+## Setting the current color
+
+The `set_color` method sets the color that will be used by all subsequent drawing operations.
+
+```ruby
+canvas.set_color(10)
+```
+
+You can omit the color argument in the `set_pixel` method if you have previously set the color using the `set_color` method.
+
+```ruby
+canvas.set_color(10)
+canvas.set_pixel(160, 90)
+```
+
+## Drawing lines
+
+Use the `draw_line` method to draw a line between two points.
+
+```ruby
+canvas.set_color(10)
+canvas.draw_line(10, 10, 100, 50)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(8)
+    draw_line(0, 0, 63, 17)
+end
+code end --><img class='full' src='images/code/0ba813cd6b7e0ae0.png'>
+
+## Drawing rectangles
+
+Use the `draw_rect` and `fill_rect` methods to draw rectangles. Specify the coordinates of the upper-left corner and the lower-right corner of the rectangle.
+
+```ruby
+canvas.set_color(3)
+canvas.fill_rect(10, 10, 100, 50)
+canvas.set_color(10)
+canvas.draw_rect(10, 10, 100, 50)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(7)
+    fill_rect(0, 0, 63, 17)
+    set_color(8)
+    draw_rect(0, 0, 63, 17)
+end
+code end --><img class='full' src='images/code/584e2ee3b7526718.png'>
+
+## Drawing circles
+
+Use the `draw_circle` and `fill_circle` methods to draw circles. Specify the center and the radius of the circle.
+
+```ruby
+canvas.set_color(3)
+canvas.fill_circle(160, 90, 50)
+canvas.set_color(10)
+canvas.draw_circle(160, 90, 50)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 19, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 18)
+    set_color(7)
+    fill_circle(32, 9, 9)
+    set_color(8)
+    draw_circle(32, 9, 9)
+end
+code end --><img class='full' src='images/code/809d9ce7d7a8ce6c.png'>
+
+## Drawing ellipses
+
+Use the `draw_ellipse` and `fill_ellipse` methods to draw ellipses. Specify the center, the horizontal radius, and the vertical radius of the ellipse.
+
+```ruby
+canvas.set_color(3)
+canvas.fill_ellipse(160, 90, 50, 30)
+canvas.set_color(10)
+canvas.draw_ellipse(160, 90, 50, 30)
+```
+<!-- code begin
+Pixelflow::Canvas.new(64, 19, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 18)
+    set_color(7)
+    fill_ellipse(32, 9, 16, 9)
+    set_color(8)
+    draw_ellipse(32, 9, 16, 9)
+end
+code end --><img class='full' src='images/code/3871051301832e44.png'>
+
+## Drawing circular arcs
+
+Use the `draw_arc` and `fill_arc` methods to draw arcs. Specify the center, the radius, the start angle, and the end angle of the arc.
+
+```ruby
+canvas.set_color(3)
+canvas.fill_arc(160, 90, 50, 0, 180)
+canvas.set_color(10)
+canvas.draw_arc(160, 90, 50, 0, 180)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(7)
+    fill_arc(32, 0, 18, 30, 150)
+    set_color(8)
+    draw_arc(32, 0, 18, 30, 150)
+end
+code end --><img class='full' src='images/code/4eb9d4f97e05c739.png'>
+
+## Drawing Bézier curves
+
+Use the `draw_quadratic_bezier` and `draw_cubic_bezier` methods to draw quadratic and cubic Bézier curves, respectively.
+
+```ruby
+canvas.set_color(10)
+canvas.draw_quadratic_bezier(10, 10, 50, 50, 100, 10)
+canvas.draw_cubic_bezier(10, 10, 50, 50, 100, 50, 150, 10)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(8)
+    draw_quadratic_bezier(0, 17, 16, -8, 63, 17)
+end
+code end --><img class='full' src='images/code/ec32331b354119d2.png'>
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(8)
+    draw_cubic_bezier(0, 17, 16, -8, 47, 30, 63, 0)
+end
+code end --><img class='full' src='images/code/40acf0284459aa0e.png'>
+
+## Drawing triangles
+
+Use the `draw_triangle` and `fill_triangle` methods to draw triangles. Specify the coordinates of the three vertices of the triangle.
+
+```ruby
+canvas.set_color(3)
+canvas.fill_triangle(10, 10, 100, 50, 50, 100)
+canvas.set_color(10)
+canvas.draw_triangle(10, 10, 100, 50, 50, 100)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(7)
+    fill_triangle(10, 0, 52, 6, 31, 17)
+    set_color(8)
+    draw_triangle(10, 0, 52, 6, 31, 17)
+end
+code end --><img class='full' src='images/code/85abc3576f6d78b1.png'>
+
+## Flood filling
+
+The `flood_fill` method fills an area of the canvas with the current color. Specify the starting point of the fill operation.
+
+```ruby
+canvas.set_color(10)
+canvas.draw_circle(110, 90, 50)
+canvas.draw_circle(210, 90, 40)
+canvas.flood_fill(160, 90)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 18, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 17)
+    set_color(8)
+    draw_circle(25, 12, 12)
+    draw_circle(39, 12, 8)
+    set_color(7)
+    flood_fill(25, 14)
+    flood_fill(39, 14)
+end
+code end --><img class='full' src='images/code/ef667cfe7ff65c27.png'>
+
+## Drawing text
+
+Use the `draw_text` method to draw text on the canvas. Specify the position, the text to draw, the font name, and the scale factor.
+
+```ruby
+canvas.set_color(10)
+canvas.draw_text(10, 10, "Hello, world!", "4x6", 2)
+```
+
+<!-- code begin
+Pixelflow::Canvas.new(64, 14, :palette) do
+    set_color(15)
+    fill_rect(0, 0, 63, 13)
+    set_color(8)
+    draw_text(7, 4, "Hello, world!", "4x6", 1)
+end
+code end --><img class='full' src='images/code/30c5ac94e5fa22ba.png'>
+
+
+Use `text_width` to get the width and height of a given text string in pixels.
+
+```ruby
+width = canvas.text_width("Hello, world!", "4x6", 2)
+```
+
+There are several built-in fonts available:
+
+<!-- fonts start -->
+
+#### 4x6
+
+<img src='images/4x6.png' alt='4x6'>
+
+#### 6x10
+
+<img src='images/6x10.png' alt='6x10'>
+
+#### 7x13
+
+<img src='images/7x13.png' alt='7x13'>
+
+#### 7x13B
+
+<img src='images/7x13B.png' alt='7x13B'>
+
+#### 8x13
+
+<img src='images/8x13.png' alt='8x13'>
+
+#### 8x13B
+
+<img src='images/8x13B.png' alt='8x13B'>
+
+#### 9x15
+
+<img src='images/9x15.png' alt='9x15'>
+
+#### 9x15B
+
+<img src='images/9x15B.png' alt='9x15B'>
+
+<!-- fonts end -->