lesson00 complete

Author: Lokathor

.cargo/config

@@ -0,0 +1,2 @@
+[build]
+rustflags = ["-C","target-feature=+crt-static"]

.travis.yml

@@ -0,0 +1,49 @@
+dist: xenial
+
+os:
+  - linux
+  - osx
+
+language: rust
+
+rust:
+  - stable
+
+cache:
+  cargo
+
+branches:
+  only:
+    - staging
+    - trying
+    - master
+
+before_script:
+  - |
+    if [[ $TRAVIS_OS_NAME == "linux" ]]; then \
+      (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update) && \
+      (test -x $HOME/.cargo/bin/mdbook || cargo install mdbook) && \
+      cargo install-update -a; \
+    fi
+script:
+  # builds all examples and builds+runs all tests
+  - cargo test
+  
+  # Also ensure that the book compiles right
+  - mdbook build
+
+# This deploy will push the mdbook output to the `ghpages` branch,
+# but you need to manually set up the GITHUB_TOKEN yourself for each
+# repo you make.
+
+deploy:
+  provider: pages
+  local-dir: target/book-output
+  skip-cleanup: true
+  github-token: $GITHUB_TOKEN
+  keep-history: false
+  name: DocsBot
+  verbose: true
+  on:
+    branch: master
+    condition: $TRAVIS_OS_NAME = linux

Cargo.lock

@@ -2,15 +2,16 @@
 name = "learn-opengl"
 description = "LearnOpenGL.com lessons in Rust"
 repository = "https://github.com/Lokathor/learn-opengl"
-version = "0.1.0"
+version = "0.0.0"
 authors = ["Lokathor <[email protected]>"]
 edition = "2018"
 license = "Zlib"
 
-publish = false
-
 [dependencies]
 bytemuck = "1"
-imagine = "0.0.2"
-beryllium = "0.2.0-alpha.1"
 ogl33 = { version = "0.1", features = ["debug_error_checks", "debug_trace_messages"]}
+
+[dev-dependencies]
+beryllium = "0.2.0-alpha.2"
+imagine = "0.0.2"
+ultraviolet = "0.3"

Cargo.toml

@@ -0,0 +1,7 @@
+
+# Learn OpenGL Rust
+
+[Introduction](introduction.md)
+
+* [Basics](basics/index.md)
+  * [Creating A Window](basics/creating-a-window.md)

SDL2.dll

@@ -0,0 +1,108 @@
+# Creating A Window
+
+So, this part of the tutorial is very library specific, so I won't focus on it
+too much.
+
+Basically, we have to open a window, and we also need a GL context to go with that window.
+
+On most platforms, you have to specify that you'll be using GL _before_ you create the window, so that the window itself can be created with the correct settings to support GL once it's made.
+
+In our case, first we turn on SDL itself:
+
+```rust
+use beryllium::*;
+
+fn main() {
+  let sdl = SDL::init(InitFlags::Everything).expect("couldn't start SDL");
+```
+
+Then we set some GL attributes that we want to use:
+
+```rust
+  sdl.gl_set_attribute(SdlGlAttr::MajorVersion, 3).unwrap();
+  sdl.gl_set_attribute(SdlGlAttr::MinorVersion, 3).unwrap();
+  sdl.gl_set_attribute(SdlGlAttr::Profile, GlProfile::Core).unwrap();
+  sdl
+    .gl_set_attribute(SdlGlAttr::Flags, ContextFlag::ForwardCompatible)
+    .unwrap();
+```
+
+Finally we can make our window.
+
+```rust
+  let _win = sdl
+    .create_gl_window(
+      "Hello Window",
+      WindowPosition::Centered,
+      800,
+      600,
+      WindowFlags::Shown,
+    )
+    .expect("couldn't make a window and context");
+```
+
+Once we have a window, we can poll for events. Right now we just wait for a quit
+event (user clicked the X on the window, pressed Alt+F4, etc) and then quit when
+that happens.
+
+```rust
+  'main_loop: loop {
+    while let Some(event) = sdl.poll_events().and_then(Result::ok) {
+      // handle events this frame
+      match event {
+        Event::Quit(_) => break 'main_loop,
+        _ => (),
+      }
+
+      // here's where we could change the world state and draw.
+    }
+  }
+}
+```
+
+That's all there is to it. Just a milk run.
+
+## Extras
+
+I'm developing mostly on Windows, and Windows is where most of your market share of users will end up being, so here's some bonus Windows tips:
+
+### Windows Subsystem
+
+I'm going to put the following attribute at the top of the file:
+
+```rust
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+```
+
+This will make is to that a "release" build (with the `--release` flag) will use the "windows" subsystem on Windows, instead of the "console" subsystem. This makes the process not have a console by default, which prevents a little terminal window from running in the background when the program runs on its own. However, we only want that in release mode because we want the ability to print debug message in debug mode.
+
+### Static C Runtime
+
+Also, I'm going to add a `.cargo/` folder to the project and put a `config` file inside.
+
+```toml
+[build]
+rustflags = ["-C","target-feature=+crt-static"]
+```
+
+This will make Rust compile in a static C runtime when it builds the binaries, so that the binaries can be sent to others without them needing to have the MSVC redistributable DLLs or other files like that on their machine. It's not on by default because I don't even know why. I think it makes programs marginally larger, but it doesn't seem to make them compile slower so whatever.
+
+We could instead make a totally `no_std` program if we wanted to, but that's a whole set of steps and not really OpenGL related at all, so for this tutorial book we'll use the "quick and dirty" way to get our programs to be easily portable.
+
+### Static Linking SDL2
+
+Finally, instead of dynamic linking with SDL2 we could static link with it.
+
+All we have to static link SDL2 instead is change our Cargo.toml file so that instead of saying
+
+```toml
+beryllium = "0.2.0-alpha.2"
+```
+
+it says
+
+```toml
+beryllium = { version = "0.2.0-alpha.1", default-features = false, features = ["link_static"] }
+```
+
+However, when we do this, we have to build the SDL2 static lib, which takes longer (about +30 seconds). So I leave it in dynamic link during development because it makes CI go faster.

book-src/SUMMARY.md

@@ -0,0 +1,65 @@
+# Basics
+
+TODO: maybe some of this can go into the Introduction. whatever.
+
+It's become the "older" style among the graphics APIs, with Vulkan / DX12 / Metal being the new hotness.
+
+However, I think that it's easy enough to use and you don't often need the final ounce of performance that you can get with Vulkan.
+
+We'll be using OpenGL 3.3. The latest version is 4.6, but we'll be using 3.3. The main reason for this is because if we take a quick look at Mac's [supported OpenGL versions](https://support.apple.com/en-us/HT202823) we can see that they support 3.3 on old stuff and 4.1 on new stuff. Macs don't get OpenGL 4.6 like Windows and Linux have. Oh well. Feel free to use this book and then learn the stuff that got added after 3.3 if you don't care about supporting old macs.
+
+OpenGL is a _specification_, and it's a specification for a C API. It's probably implemented in C as well, but actually you could implement it in any language that can expose a C API. Time to rewrite OGL in Rust, ne?
+
+So we'll be doing a lot of FFI calls. FFI calls are naturally `unsafe`. If you're not comfortable with that then go use [glium](https://docs.rs/glium), or [wgpu](https://docs.rs/wgpu) or something. Phaazon converted their [luminance tutorial](https://github.com/rust-tutorials/learn-luminance) into a more bookish form recently too. You don't _have_ to use OpenGL directly.
+
+But if you want to know how people _built_ those other libraries, you gotta learn this direct usage stuff.
+
+## Prior Knowledge
+
+You should generally be familiar with all the topics covered in [The Rust
+Programming Language](https://doc.rust-lang.org/book/), but you don't need to
+have them memorized you can look things up again if you need to.
+
+I usually tell folks that they should read [The
+Rustonomicon](https://doc.rust-lang.org/nomicon/) before doing a lot of unsafe
+code. However, with GL you're not really doing a lot of hackery _within Rust_
+that could go wrong. It's just that the driver could explode in your face if you
+look at it funny. Or even if you don't, because drivers are just buggy
+sometimes. Oh well, that's life.
+
+## Libraries Used
+
+As I start this project, this is what my Cargo.toml looks like.
+
+```toml
+[dependencies]
+bytemuck = "1"
+ogl33 = { version = "0.1", features = ["debug_error_checks", "debug_trace_messages"]}
+
+[dev-dependencies]
+beryllium = "0.2.0-alpha.2"
+imagine = "0.0.2"
+ultraviolet = "0.3"
+```
+
+So the library itself, where we'll put our useful GL helpers, will depend on
+
+* [ogl33](https://docs.rs/ogl33), which gives us bindings to OpenGL.
+  * It works mostly like the [gl](https://docs.rs/gl) crate, except it _only_
+    connects to OpenGL 3.3 (the `gl` crate builds for 4.6).
+* [bytemuck](https://docs.rs/bytemuck), which is a handy crate for casting around data types.
+
+And then if you're not familiar with "dev-dependencies", that's bonus dependencies that tests and examples can use. Since our example programs will be examples, they can use extra things that aren't critical to the lib itself. That way if someone else wants to use the lib they can use _just_ the lib in their own program, without having to also build the stuff we're using for our examples.
+
+* [beryllium](https://docs.rs/beryllium) is an SDL2 wrapper. It will dynamic link by default so you'll need `SDL2.dll` in your path to run a program. You can swap this to static linking, I describe that at the end of the first lesson.
+  * Other options: [winit](https://docs.rs/winit), [glfw](https://docs.rs/glfw)
+* [imagine](https://docs.rs/imagine) is a PNG parser (not used right away, but soon enough).
+  * Other options: [image](https://docs.rs/image), which uses [png](https://docs.rs/png)
+* [ultraviolet](https://docs.rs/ultraviolet) is a graphics linear algebra crate.
+  * Other options: [glam](https://docs.rs/glam), [nalgebra-glm](https://docs.rs/nalgebra-glm)
+
+Full disclosure: I wrote almost all of the crates on the list. Other than
+`ultraviolet`, which was done by [Fusha](https://github.com/termhn), because I'm
+a dummy who can't do math.
+
+However, I'm writing the book, so I get to use my own crates while I do it. I think this is fair, and I'm also providing alternative suggestions for each one, so I don't feel bad about it.

book-src/basics/creating-a-window.md

@@ -0,0 +1,20 @@
+# Introduction
+
+This is a book, well, "book", about learning OpenGL usage with Rust.
+
+It's based on [learnopengl.com](https://learnopengl.com/), which is for C++.
+
+It's about OpenGL (OGL), which is one particular flavor of GL within the larger
+GL family. There's also OpenGL ES (GLES), which is for embedded systems like
+phones and raspberry pi, and there's WebGL which is for GL in the browser.
+
+I don't expect that I will write all the lesson text well enough
+in the first draft for it to be a stand alone teaching method.
+
+However, the code itself will compile and work of course, so if you
+look at the code and read the pages here and the pages there it'll hopefully
+make some sense when you add it all up.
+
+Sorry, but books like this are kinda difficult to write properly, 
+and I want to put more focus on getting out working examples than on
+having perfect tutorial text.

book-src/basics/index.md

@@ -0,0 +1,10 @@
+[book]
+title = "Learn OpenGL Rust"
+authors = ["Lokathor"]
+description = "A version of the LearnOpenGL book for Rust."
+src = "book-src"
+language = "en"
+
+[build]
+build-dir = "target/book-output"
+create-missing = true

book-src/introduction.md

@@ -0,0 +1,36 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+#![allow(clippy::single_match)]
+
+use beryllium::*;
+
+fn main() {
+  let sdl = SDL::init(InitFlags::Everything).expect("couldn't start SDL");
+  sdl.gl_set_attribute(SdlGlAttr::MajorVersion, 3).unwrap();
+  sdl.gl_set_attribute(SdlGlAttr::MinorVersion, 3).unwrap();
+  sdl.gl_set_attribute(SdlGlAttr::Profile, GlProfile::Core).unwrap();
+  sdl
+    .gl_set_attribute(SdlGlAttr::Flags, ContextFlag::ForwardCompatible)
+    .unwrap();
+
+  let _win = sdl
+    .create_gl_window(
+      "Hello Window",
+      WindowPosition::Centered,
+      800,
+      600,
+      WindowFlags::Shown,
+    )
+    .expect("couldn't make a window and context");
+
+  'main_loop: loop {
+    while let Some(event) = sdl.poll_events().and_then(Result::ok) {
+      // handle events this frame
+      match event {
+        Event::Quit(_) => break 'main_loop,
+        _ => (),
+      }
+
+      // here's where we could change the world state and draw.
+    }
+  }
+}

book.toml

@@ -1,2 +1 @@
-
 //