Added a basic example + Image renderer

.gitignore

@@ -24,3 +24,5 @@ Cargo.lock
 
 # png files generated by tests
 /*png
+
+.DS_Store

Cargo.toml

@@ -1,5 +1,11 @@
 [workspace]
 resolver = "2" # What does this do?
+members = [".", "examples/*"]
+# Only check / build vger crate by default (check all with `--workspace`)
+default-members = ["."]
+
+[workspace.dependencies]
+wgpu = "22"
 
 [package]
 name = "vger"
@@ -16,7 +22,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-wgpu = "22"
+wgpu = { workspace = true }
 euclid = "0.22.7"
 fontdue = "0.9.0"
 rect_packer = "0.2.1"

assets/fonts/Roboto/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2011 The Roboto Project Authors (https://github.com/googlefonts/roboto-classic)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

assets/fonts/Sniglet/OFL.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2008, Haley Fiege ([email protected]), Copyright (c) 2012, Brenda Gallo ([email protected]), Copyright (c) 2013, Pablo Impallari (www.impallari.com|[email protected])
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

examples/basic/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "basic"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+vger = { path = "../../" }
+winit = "0.30"
+nanorand = { version = "0.7" }
+wgpu = { workspace = true }
+futures = "0.3"

examples/basic/README.md

@@ -0,0 +1,129 @@
+Certainly! Below is an example of documentation for the code you provided, explaining the functionality, usage, and structure.
+
+---
+
+# 2D Graphics Application with `wgpu`, `winit`, and `vger`
+
+This Rust application demonstrates how to create a basic 2D graphics application using the `wgpu` library (for GPU rendering), the `winit` library (for window management and event handling), and the custom `vger` library (for high-level 2D graphics rendering). The application renders a simple red circle and some sample text to the window.
+
+## Features
+
+- Initializes a window with `winit`.
+- Sets up GPU rendering with `wgpu` and renders graphics with `vger`.
+- Supports window resizing and automatic content scaling.
+- Displays a red circle and some text on the screen.
+- Works in both native environments (e.g., Windows, macOS, Linux) and WebAssembly (WASM).
+
+---
+
+## Modules and Dependencies
+
+### `wgpu`
+
+`wgpu` is a safe, modern WebGPU implementation for Rust. It provides access to the GPU for graphics and compute tasks. In this application, `wgpu` is used to:
+
+- Create and configure the GPU device.
+- Manage the surface (the window) to which graphics will be rendered.
+- Submit rendering commands.
+
+### `winit`
+
+`winit` is a cross-platform window creation and event handling library. It is used to:
+
+- Create a window for rendering.
+- Handle window events, such as resizing, close requests, and redraw requests.
+- Ensure cross-platform compatibility (including support for WebAssembly in browsers).
+
+### `vger`
+
+`vger` is a custom high-level graphics library used for 2D drawing. It simplifies drawing shapes, text, and other graphics on the screen using `wgpu`. In this example, it is used to:
+
+- Draw shapes (e.g., circles).
+- Render text.
+- Provide a higher-level abstraction for GPU rendering.
+
+---
+
+## Application Structure
+
+### `DrawContext`
+
+The `DrawContext` structure holds the state necessary for rendering:
+
+- **`surface`**: The window surface that is rendered to.
+- **`device`**: The GPU device used to interact with the hardware.
+- **`config`**: The surface configuration, including window size, format, and other parameters.
+- **`vger`**: The `Vger` instance used to perform high-level 2D drawing.
+
+### `setup` (Async)
+
+This function is responsible for setting up the rendering context. It performs the following tasks:
+
+- Initializes the `wgpu` instance and selects a GPU adapter.
+- Creates the surface (i.e., the window) for rendering.
+- Configures the GPU device and queue.
+- Sets up the `vger` library for rendering.
+
+### `render`
+
+The `render` function is responsible for drawing content to the screen using `vger`. It performs the following tasks:
+
+- Saving and restoring drawing state.
+- Translates the drawing context.
+- Draws a red circle at the center of the window.
+- Renders sample text.
+
+### `App`
+
+The `App` struct represents the application and holds the window and rendering context. It implements the `ApplicationHandler` trait from `winit` to manage window events and the application lifecycle.
+
+- **`window`**: An `Option` containing the window (if it exists).
+- **`context`**: An `Option` containing the `DrawContext` (if the context has been initialized).
+
+### `ApplicationHandler` Implementation
+
+The `App` struct implements the `ApplicationHandler` trait, which provides methods for handling various events:
+
+- **`resumed`**: Initializes the window and rendering context when the application is resumed. This is where the `setup` function is called.
+- **`window_event`**: Handles window events, including:
+  - **CloseRequested**: Exits the event loop when the user closes the window.
+  - **Resized**: Updates the surface configuration when the window is resized, and triggers a redraw.
+  - **RedrawRequested**: Handles the actual rendering. It updates the rendering context, clears the frame, and presents the rendered content to the screen.
+
+---
+
+## Usage
+
+### Building and Running
+
+To build and run the application, follow these steps:
+
+1. If you're targeting a native platform (Windows, macOS, Linux):
+
+   - Build and run the project as a regular Rust application:
+     ```bash
+     cargo run -p basic
+     ```
+
+2. Once the application is running, a window will appear, and the red circle and text will be rendered to the screen. Resize the window, and the graphics will adjust accordingly.
+
+### Customization
+
+- **Text Rendering**: To render custom text, modify the string passed to the `vger.text()` function in the `render` function.
+- **Shapes**: Add more shapes (e.g., rectangles, lines) using the `vger` API to customize what is drawn to the screen.
+- **Window Size**: The window's size is automatically adjusted when resized by the user, and the application will reconfigure the GPU surface accordingly.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for more details.
+
+---
+
+## Notes
+
+- **WebAssembly (WASM)**: When targeting WebAssembly, the canvas is directly added to the HTML body. This is handled by the `winit` library in the `setup` function under the `#[cfg(target_arch = "wasm32")]` section.
+- **`vger` Library**: The `vger` library is a higher-level abstraction built on top of `wgpu`, designed for easy drawing of 2D graphics. You can extend it to create more complex drawings.
+
+---