Improve the readme (#497)

* Improve the readme

* doc tweaks

* new cube screenshot

* scale images with exactly factor 2

README.md

@@ -2,25 +2,25 @@
 [![Documentation Status](https://readthedocs.org/projects/wgpu-py/badge/?version=stable)](https://wgpu-py.readthedocs.io)
 [![PyPI version](https://badge.fury.io/py/wgpu.svg)](https://badge.fury.io/py/wgpu)
 
+
 # wgpu-py
 
-A Python implementation of WebGPU - the next generation GPU API.
+A Python implementation of WebGPU - the next generation GPU API. 🚀
 
-<img width=300 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/cube.png' />
-<img width=300 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/triangle_auto.png' />
+<div>
+  <img width=320 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/triangle_auto.png' />
+  <img width=320 src='https://raw.githubusercontent.com/pygfx/wgpu-py/main/examples/screenshots/cube.png' />
+</div>
 
 
 ## Introduction
 
-In short, this is a Python lib wrapping
-[wgpu-native](https://github.com/gfx-rs/wgpu) and exposing it with a Pythonic
-API similar to the [WebGPU spec](https://gpuweb.github.io/gpuweb/).
+The purpose of wgpu-py to to provide Python with a powerful and reliable GPU API.
 
-The OpenGL API is old and showing it's cracks. New API's like Vulkan, Metal and
-DX12 provide a modern way to control the GPU, but these API's are too low-level
-for general use. The WebGPU API follows the same concepts, but with a simpler
-(higher level) spelling. The Python `wgpu` library brings the WebGPU API to
-Python.
+It serves as a basis to build a broad range of applications and libraries
+related to visualization and GPU compute. We use it in
+[pygfx](https://github.com/pygfx/pygfx) to create a modern Pythonic render
+engine.
 
 To get an idea of what this API looks like have a look at
 [triangle.py](https://github.com/pygfx/wgpu-py/blob/main/examples/triangle.py)
@@ -29,21 +29,35 @@ and the other [examples](https://github.com/pygfx/wgpu-py/blob/main/examples/).
 
 ## Status
 
-> **Note**
->
-> The wgpu-API has not settled yet, use with care!
-
-* Coverage of the WebGPU spec is complete enough to build e.g.
-  [pygfx](https://github.com/pygfx/pygfx).
-* Test coverage of the API is close to 100%.
-* Support for Windows, Linux, and MacOS (Intel and M1).
 * Until WebGPU settles as a standard, its specification may change, and with
   that our API will probably too. Check the [changelog](CHANGELOG.md) when you
   upgrade!
+* Coverage of the WebGPU spec is complete enough to build e.g.
+  [pygfx](https://github.com/pygfx/pygfx).
+* Test coverage of the API is close to 100%.
+* Support for Windows, Linux (x86 and aarch64), and MacOS (Intel and M1).
 
 
-## Installation
+## What is WebGPU / wgpu?
 
+WGPU is the future for GPU graphics; the successor to OpenGL.
+
+WebGPU is a JavaScript API with a well-defined
+[spec](https://gpuweb.github.io/gpuweb/), the successor to WebGL. The somewhat
+broader term "wgpu" is used to refer to "desktop" implementations of WebGPU in
+various languages.
+
+OpenGL is old and showing it's cracks. New API's like Vulkan, Metal and DX12
+provide a modern way to control the GPU, but these are too low-level for general
+use. WebGPU follows the same concepts, but with a simpler (higher level) API.
+With wgpu-py we bring WebGPU to Python.
+
+Technically speaking, wgpu-py is a wrapper for
+[wgpu-native](https://github.com/gfx-rs/wgpu-native), exposing its functionality with a Pythonic
+API closely resembling the [WebGPU spec](https://gpuweb.github.io/gpuweb/).
+
+
+## Installation
 
 ```
 pip install wgpu glfw
@@ -88,6 +102,7 @@ well with Asyncio or Trio.
 
 This code is distributed under the 2-clause BSD license.
 
+
 ## Projects using `wgpu-py`
 
 * [pygfx](https://github.com/pygfx/pygfx) - A python render engine running on wgpu.
@@ -96,6 +111,7 @@ This code is distributed under the 2-clause BSD license.
 * [fastplotlib](https://github.com/fastplotlib/fastplotlib) - A fast plotting library
 * [xdsl](https://github.com/xdslproject/xdsl) - A Python Compiler Design Toolkit (optional wgpu interpreter)
 
+
 ## Developers
 
 * Clone the repo.

docs/guide.rst

@@ -2,7 +2,7 @@ Guide
 =====
 
 
-This library (``wgpu``) presents a Pythonic API for the `WebGPU spec
+The ``wgpu`` library presents a Pythonic API for the `WebGPU spec
 <https://gpuweb.github.io/gpuweb/>`_. It is an API to control graphics
 hardware. Like OpenGL but modern. Or like Vulkan but higher level.
 GPU programming is a craft that requires knowledge of how GPU's work.

docs/index.rst

@@ -1,5 +1,5 @@
 Welcome to the wgpu-py docs!
-==============================
+============================
 
 .. automodule:: wgpu
 

examples/cube.py

@@ -19,7 +19,7 @@
 # %% Create canvas and device
 
 # Create a canvas to render to
-canvas = WgpuCanvas(title="wgpu cube")
+canvas = WgpuCanvas(title="wgpu cube", size=(640, 480))
 
 # Create a wgpu device
 adapter = wgpu.gpu.request_adapter(power_preference="high-performance")
@@ -175,8 +175,9 @@
 @vertex
 fn vs_main(in: VertexInput) -> VertexOutput {
     let ndc: vec4<f32> = r_locals.transform * in.pos;
+    let xy_ratio = 0.75;  // hardcoded for 640x480 canvas size
     var out: VertexOutput;
-    out.pos = vec4<f32>(ndc.x, ndc.y, 0.0, 1.0);
+    out.pos = vec4<f32>(ndc.x * xy_ratio, ndc.y, 0.0, 1.0);
     out.texcoord = in.texcoord;
     return out;
 }
@@ -368,7 +369,7 @@ def draw_frame():
             {
                 "view": current_texture_view,
                 "resolve_target": None,
-                "clear_value": (1, 1, 1, 1),
+                "clear_value": (0, 0, 0, 1),
                 "load_op": wgpu.LoadOp.clear,
                 "store_op": wgpu.StoreOp.store,
             }

wgpu/__init__.py

@@ -1,5 +1,5 @@
 """
-The wgpu library is a Python implementation of WebGPU.
+The next generation GPU API for Python.
 """
 
 from ._coreutils import logger  # noqa: F401,F403