Revamp core types, add several more functions

Revamped:
- Types
  - Removed `From` impl
  - Converted wrapper structs to macro
- Added macro for converting primitives with GL type aliases
- Removed extraneous error types, added proper enum to
  `ObjectCreationError`

Added:
- functions and enum for enable/disable
- functions and wrapper for uniforms

Author: matthew-e-brown

crates/core/src/errors.rs

@@ -1,59 +1,36 @@
-use gl::types::*;
-use thiserror::Error;
-
-
-/// The error returned when attempting to convert a raw [`GLenum`] into an actual Rust enum fails. This can happen when
-/// the given `GLenum` value does not match any variants.
-#[derive(Error, Debug)]
-#[error("could not convert `GLenum` value '{original_value:#X}' into enum of type `{attempted_type}`")]
-pub struct EnumConversionError {
-    original_value: GLenum,
-    attempted_type: &'static str,
-}
-
-impl EnumConversionError {
-    pub(crate) const fn new(value: GLenum, name: &'static str) -> Self {
-        Self {
-            original_value: value,
-            attempted_type: name,
-        }
-    }
-}
-
-
-/// The error returned when attempting to convert a raw [`GLbitfield`] into an actual Rust struct fails. This can happen
-/// when the given `GLbitfield` value does not
-#[derive(Error, Debug)]
-#[error("could not convert `GLbitfield` value '{original_value:#b}' into struct of type `{attempted_type}`")]
-pub struct BitfieldConversionError {
-    original_value: GLbitfield,
-    attempted_type: &'static str,
-}
-
-impl BitfieldConversionError {
-    pub(crate) const fn new(value: GLbitfield, name: &'static str) -> Self {
-        Self {
-            original_value: value,
-            attempted_type: name,
-        }
-    }
-}
+use std::fmt;
 
+use thiserror::Error;
 
-/// An error returned when OpenGL itself fails to create an object.
+/// This error is returned when creating an OpenGL "_object_" fails.
 ///
-/// This error is returned by several functions, and contains no extra details. It corresponds to when an
-/// object-creation function (e.g., [`glCreateShader`] and [`glCreateProgram`]) returns zero.
+/// This error corresponds to when an object-creation function like [`glCreateShader`] or [`glCreateProgram`] returns a
+/// value of zero.  There are no extra details associated with it.
 ///
 /// [`glCreateShader`]: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glCreateShader.xhtml
 /// [`glCreateProgram`]: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glCreateProgram.xhtml
-#[derive(Error, Debug)]
-#[error("OpenGL could not create {0} object")]
-// note: {0} should *include* article ("a shader" object) ("an ..." object)
-pub struct ObjectCreationError(&'static str);
+#[derive(Error, Debug, Clone, Copy)]
+#[error("OpenGL failed to create {0}.")] // note: {0} should *include* article ("an ..." object)
+pub struct ObjectCreationError(ObjectCreationErrorKind);
 
 impl ObjectCreationError {
-    pub(crate) const fn new(type_name: &'static str) -> Self {
-        Self(type_name)
+    pub(crate) const fn new(kind: ObjectCreationErrorKind) -> Self {
+        Self(kind)
+    }
+}
+
+/// Which object [failed to be created][ObjectCreationError].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ObjectCreationErrorKind {
+    Shader,
+    Program,
+}
+
+impl fmt::Display for ObjectCreationErrorKind {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.write_str(match self {
+            Self::Shader => "a shader object",
+            Self::Program => "a program object",
+        })
     }
 }

crates/core/src/funcs/buffers.rs

@@ -1,5 +1,6 @@
 use gl::types::*;
 
+use crate::gl_convert;
 use crate::types::*;
 
 
@@ -19,7 +20,7 @@ pub fn create_buffers(n: usize) -> Vec<BufferID> {
     }
 
     let mut names = vec![0; n];
-    let n: GLsizei = n.try_into().expect("buffer creation count should fit into `GLsizei`");
+    let n = gl_convert!(n, GLsizei, "number of buffers");
 
     unsafe {
         gl::CreateBuffers(n, names.as_mut_ptr());
@@ -29,26 +30,41 @@ pub fn create_buffers(n: usize) -> Vec<BufferID> {
 }
 
 
+pub fn delete_buffer(buffer: BufferID) {
+    unsafe {
+        // cast is safe because `BufferID` is `repr(transparent)`
+        gl::DeleteBuffers(1, &buffer as *const BufferID as *const _)
+    }
+}
+
+
+pub fn delete_buffers(buffers: &[BufferID]) {
+    let n = gl_convert!(buffers.len(), GLsizei, "number of buffers");
+    let p = buffers.as_ptr().cast(); // cast is safe because `BufferID` is `repr(transparent)`
+    unsafe {
+        gl::DeleteBuffers(n, p);
+    }
+}
+
+
 pub fn bind_buffer(target: BufferTarget, buffer: BufferID) {
     unsafe {
-        gl::BindBuffer(target.into(), buffer.name());
+        gl::BindBuffer(target.raw(), buffer.raw());
     }
 }
 
 
-pub fn buffer_data(target: BufferTarget, data: impl AsRef<[u8]>, usage: BufferUsage) {
-    let data = data.as_ref();
-    let size: GLsizeiptr = data.len().try_into().expect("buffer data size should fit into `GLsizeiptr`");
+pub fn buffer_data(target: BufferTarget, data: &[u8], usage: BufferUsage) {
+    let size = gl_convert!(data.len(), GLsizeiptr, "buffer data size");
     unsafe {
-        gl::BufferData(target.into(), size, data.as_ptr().cast(), usage.into());
+        gl::BufferData(target.raw(), size, data.as_ptr().cast(), usage.raw());
     }
 }
 
 
-pub fn named_buffer_data(buffer: BufferID, data: impl AsRef<[u8]>, usage: BufferUsage) {
-    let data = data.as_ref();
-    let size: GLsizeiptr = data.len().try_into().expect("buffer data size should fit into `GLsizeiptr`");
+pub fn named_buffer_data(buffer: BufferID, data: &[u8], usage: BufferUsage) {
+    let size = gl_convert!(data.len(), GLsizeiptr, "buffer data size");
     unsafe {
-        gl::NamedBufferData(buffer.name(), size, data.as_ptr().cast(), usage.into());
+        gl::NamedBufferData(buffer.raw(), size, data.as_ptr().cast(), usage.raw());
     }
 }

crates/core/src/funcs/mod.rs

@@ -1,29 +1,32 @@
 mod buffers;
 mod shaders;
+mod uniforms;
 mod vertex;
 
 use gl::types::*;
 
 pub use self::buffers::*;
 pub use self::shaders::*;
+pub use self::uniforms::*;
 pub use self::vertex::*;
+use crate::gl_convert;
 use crate::types::ClearMask;
+use crate::types::EnableCap;
 
 
 pub fn load_with<F>(load_fn: F)
 where
-    F: FnMut(&'static str) -> *const core::ffi::c_void,
+    F: FnMut(&'static str) -> *const std::ffi::c_void,
 {
     gl::load_with(load_fn)
 }
 
 
 pub fn viewport(x: i32, y: i32, width: i32, height: i32) {
-    let x: GLint = x.try_into().expect("viewport x-position should fit into `GLint`");
-    let y: GLint = y.try_into().expect("viewport y-position should fit into `GLint`");
-    let width: GLsizei = width.try_into().expect("viewport width should fit into `GLsizei`");
-    let height: GLsizei = height.try_into().expect("viewport height should fit into `GLsizei`");
-
+    let x = gl_convert!(x, GLint, "viewport x-position");
+    let y = gl_convert!(y, GLint, "viewport y-position");
+    let width = gl_convert!(width, GLsizei, "viewport width");
+    let height = gl_convert!(height, GLsizei, "viewport height");
     unsafe {
         gl::Viewport(x, y, width, height);
     }
@@ -32,19 +35,31 @@ pub fn viewport(x: i32, y: i32, width: i32, height: i32) {
 
 pub fn clear_color(red: f32, green: f32, blue: f32, alpha: f32) {
     let msg = "clear color should be made of valid `GLfloat`s";
-    let r: GLfloat = red.try_into().expect(msg);
-    let g: GLfloat = green.try_into().expect(msg);
-    let b: GLfloat = blue.try_into().expect(msg);
-    let a: GLfloat = alpha.try_into().expect(msg);
-
+    let r = gl_convert!(red, GLfloat, msg: msg);
+    let g = gl_convert!(green, GLfloat, msg: msg);
+    let b = gl_convert!(blue, GLfloat, msg: msg);
+    let a = gl_convert!(alpha, GLfloat, msg: msg);
     unsafe {
         gl::ClearColor(r, g, b, a);
     }
 }
 
 
+pub fn enable(cap: EnableCap) {
+    unsafe {
+        gl::Enable(cap.raw());
+    }
+}
+
+pub fn disable(cap: EnableCap) {
+    unsafe {
+        gl::Disable(cap.raw());
+    }
+}
+
+
 pub fn clear(mask: ClearMask) {
     unsafe {
-        gl::Clear(mask.into());
+        gl::Clear(mask.raw());
     }
 }