Add environment variable overrides for wgpu::PowerPreference (#94)

* Add environment variable overrides for `wgpu::PowerPreference`

* Bump MSRV

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
         rust:
           - stable
           - beta
-          - 1.40.0
+          - 1.41.0
     steps:
       - name: Checkout sources
         uses: actions/checkout@v2
@@ -39,7 +39,7 @@ jobs:
         rust:
           - stable
           - beta
-          - 1.40.0
+          - 1.41.0
     steps:
       - name: Checkout sources
         uses: actions/checkout@v2

.travis.yml

@@ -2,7 +2,7 @@ language: rust
 dist: bionic
 rust:
 # MSRV
-- 1.40.0
+- 1.41.0
 
 # Stable release channel
 - stable

README.md

@@ -29,6 +29,13 @@ Rapidly prototype a simple 2D game, pixel-based animations, software renderers,
 - [Minimal example with `winit`](./examples/minimal-winit)
 - [Pixel Invaders](./examples/invaders)
 
+## Troubleshooting
+
+The most common issue is having an outdated graphics driver installed on the host machine. `pixels`
+requests a low power (aka integrated) GPU by default. If the examples are not working for any reason, you may try setting the `PIXELS_HIGH_PERF` environment variable (the value does not matter, e.g. `PIXELS_HIGH_PERF=1` is fine) to see if that addresses the issue on your host machine.
+
+You should also try to keep your graphics drivers up-to-date, especially if you have an old Intel integrated GPU. Keep in mind that some drivers and GPUs are EOL and will not be supported.
+
 ## Comparison with `minifb`
 
 The [`minifb`](https://crates.io/crates/minifb) crate shares some similarities with `pixels`; it also allows rapid prototyping of 2D games and emulators. But it requires the use of its own window/GUI management, event loop, and input handling. One of the disadvantages with the `minifb` approach is the lack of hardware acceleration (except on macOS, which uses Metal but is not configurable). An advantage is that it relies on fewer dependencies.

src/lib.rs

@@ -8,11 +8,28 @@
 //! The GPU interface is offered by [`wgpu`](https://crates.io/crates/wgpu), and is re-exported for
 //! your convenience. Use a windowing framework or context manager of your choice;
 //! [`winit`](https://crates.io/crates/winit) is a good place to start.
+//!
+//! # Environment variables
+//!
+//! * `PIXELS_HIGH_PERF`: Switch the default adapter to high performance.
+//! * `PIXELS_LOW_POWER`: Switch the default adapter to low power.
+//!
+//! These variables change the default adapter to request either high performance or low power.
+//! (I.e. discrete or integrated GPUs.) The value is not checked, only the existence
+//! of the variable is relevant.
+//!
+//! The order of precedence for choosing a power preference is:
+//!
+//! 1. Application's specific adapter request through [`PixelsBuilder::request_adapter_options`]
+//! 2. `PIXELS_HIGH_PERF`
+//! 3. `PIXELS_LOW_POWER`
+//! 4. `wgpu` default power preference (usually low power)
 
 #![deny(clippy::all)]
 #![forbid(unsafe_code)]
 
 use std::cell::RefCell;
+use std::env;
 use std::rc::Rc;
 
 pub use crate::macros::*;
@@ -574,7 +591,7 @@ impl<'req> PixelsBuilder<'req> {
             &self.request_adapter_options.map_or_else(
                 || wgpu::RequestAdapterOptions {
                     compatible_surface,
-                    power_preference: wgpu::PowerPreference::Default,
+                    power_preference: get_default_power_preference(),
                 },
                 |rao| wgpu::RequestAdapterOptions {
                     compatible_surface: rao.compatible_surface.or(compatible_surface),
@@ -725,3 +742,14 @@ fn get_texture_format_size(texture_format: wgpu::TextureFormat) -> u32 {
         | wgpu::TextureFormat::Rgba32Float => 16,
     }
 }
+
+fn get_default_power_preference() -> wgpu::PowerPreference {
+    env::var("PIXELS_HIGH_PERF").map_or_else(
+        |_| {
+            env::var("PIXELS_LOW_POWER").map_or(wgpu::PowerPreference::Default, |_| {
+                wgpu::PowerPreference::LowPower
+            })
+        },
+        |_| wgpu::PowerPreference::HighPerformance,
+    )
+}