yog_gfx/
lib.rs

1//! Yog graphics — low-level GPU pipeline access for mods.
2//!
3//! Provides ergonomic wrappers around `YogGfxApi`, the stable C ABI table for
4//! GPU operations (VAO/VBO, GLSL shaders, textures, draw calls, render state).
5//!
6//! # Render contexts
7//!
8//! Mods receive a [`GfxContext`] in two places:
9//!
10//! - `on_hud_render(|ctx| { ... })` — called every frame after the HUD is drawn.
11//!   `ctx.view_proj()` is zeroed; `ctx.draw2d()` works.
12//! - `on_world_render(|ctx| { ... })` — called after world geometry.
13//!   `ctx.view_proj()` holds the camera view-projection matrix in camera-relative
14//!   space; `ctx.camera_pos()` is the world-space camera position.
15//!
16//! # GPU resource lifetime
17//!
18//! GPU handles (`u32`) must be created and destroyed on the render thread.
19//! Store handles between frames; pass `ctx` on every render call.
20//!
21//! ```ignore
22//! use yog_gfx::{GfxContext, gl::{Buffer, ShaderProgram, VertexArray}};
23//!
24//! struct MyRenderer {
25//!     vbo: Option<Buffer>,
26//!     vao: Option<VertexArray>,
27//!     prog: Option<ShaderProgram>,
28//! }
29//!
30//! impl MyRenderer {
31//!     fn ensure_init(&mut self, ctx: &GfxContext) {
32//!         if self.vbo.is_some() { return; }
33//!         let vbo = ctx.create_buffer();
34//!         vbo.upload(ctx, &MY_VERTICES, false);
35//!         let prog = ctx.create_shader(VERT_SRC, FRAG_SRC).unwrap();
36//!         let vao = ctx.create_vao();
37//!         vao.attrib(ctx, &vbo, 0, 3, yog_gfx::core::DataType::F32, false, 24, 0);
38//!         self.vbo = Some(vbo);
39//!         self.vao = Some(vao);
40//!         self.prog = Some(prog);
41//!     }
42//!
43//!     fn render(&mut self, ctx: &GfxContext) {
44//!         self.ensure_init(ctx);
45//!         let vao = self.vao.as_ref().unwrap();
46//!         let prog = self.prog.as_ref().unwrap();
47//!         prog.uniform_mat4(ctx, "uViewProj", &ctx.view_proj());
48//!         ctx.draw_arrays(vao, prog, yog_gfx::core::DrawMode::Triangles, 0, 3);
49//!     }
50//! }
51//! ```
52
53pub mod core;
54pub mod gl;
55pub mod draw2d;
56
57use yog_abi::YogGfxApi;
58
59/// Handle to the GPU and draw capabilities for a single render frame.
60///
61/// Valid only within an `on_hud_render` or `on_world_render` callback.
62/// Do **not** store across frames — store GPU resource handles (`u32`) instead.
63#[derive(Copy, Clone)]
64pub struct GfxContext(*const YogGfxApi);
65
66unsafe impl Send for GfxContext {}
67unsafe impl Sync for GfxContext {}
68
69impl GfxContext {
70    #[doc(hidden)]
71    pub unsafe fn from_raw(raw: *const YogGfxApi) -> Self { Self(raw) }
72
73    #[inline]
74    fn api(&self) -> &YogGfxApi { unsafe { &*self.0 } }
75
76    // ── Frame info ────────────────────────────────────────────────────────────
77
78    /// GUI pixel dimensions of the screen for this frame.
79    pub fn screen_size(&self) -> (i32, i32) {
80        let a = self.api();
81        (a.screen_w, a.screen_h)
82    }
83
84    /// Partial-tick interpolation factor (0.0–1.0).
85    pub fn delta_tick(&self) -> f32 { self.api().delta_tick }
86
87    /// View-projection matrix in camera-relative space (column-major, 16 × f32).
88    /// Zeros during `on_hud_render`; filled during `on_world_render`.
89    pub fn view_proj(&self) -> [f32; 16] { self.api().view_proj }
90
91    /// Camera world-space position.  All zeros during `on_hud_render`.
92    pub fn camera_pos(&self) -> [f32; 3] { self.api().camera_pos }
93
94    /// Local player world-space position (eye height).  All zeros during `on_hud_render`.
95    /// Use this to anchor geometry to the player; differs from `camera_pos` in third-person.
96    pub fn player_pos(&self) -> [f32; 3] { self.api().player_pos }
97
98    // ── GPU buffer ───────────────────────────────────────────────────────────
99
100    /// Allocate a new GPU buffer (VBO or EBO). Returns handle 0 on failure.
101    pub fn create_buffer(&self) -> gl::Buffer {
102        gl::Buffer { handle: unsafe { (self.api().buf_create)() } }
103    }
104
105    /// Delete a buffer allocated by `create_buffer`.
106    pub fn delete_buffer(&self, buf: gl::Buffer) {
107        unsafe { (self.api().buf_delete)(buf.handle) }
108    }
109
110    // ── Vertex array ─────────────────────────────────────────────────────────
111
112    /// Allocate a new vertex array object. Returns handle 0 on failure.
113    pub fn create_vao(&self) -> gl::VertexArray {
114        gl::VertexArray { handle: unsafe { (self.api().vao_create)() } }
115    }
116
117    /// Delete a vertex array allocated by `create_vao`.
118    pub fn delete_vao(&self, vao: gl::VertexArray) {
119        unsafe { (self.api().vao_delete)(vao.handle) }
120    }
121
122    // ── Shader program ────────────────────────────────────────────────────────
123
124    /// Compile and link a GLSL shader program.
125    /// Returns `Err(())` and logs on compile/link failure.
126    pub fn create_shader(&self, vert_src: &str, frag_src: &str) -> Result<gl::ShaderProgram, ()> {
127        use yog_abi::YogStr;
128        let mut handle = 0u32;
129        let ok = unsafe {
130            (self.api().prog_create)(
131                YogStr::from_str(vert_src),
132                YogStr::from_str(frag_src),
133                &mut handle,
134            )
135        };
136        if ok && handle != 0 { Ok(gl::ShaderProgram { handle }) } else { Err(()) }
137    }
138
139    /// Delete a shader program.
140    pub fn delete_shader(&self, prog: gl::ShaderProgram) {
141        unsafe { (self.api().prog_delete)(prog.handle) }
142    }
143
144    // ── Texture ───────────────────────────────────────────────────────────────
145
146    /// Upload RGBA8 pixel data as a new GPU texture.
147    /// `linear`: `true` = bilinear filter, `false` = nearest.
148    pub fn create_texture_rgba(&self, w: u32, h: u32, pixels: &[u8], linear: bool) -> gl::Texture {
149        gl::Texture { handle: unsafe { (self.api().tex_create)(w, h, pixels.as_ptr(), linear) } }
150    }
151
152    /// Get the GL texture handle that Minecraft uses for an identifier
153    /// (e.g. `"minecraft:textures/gui/icons.png"`).  Returns handle 0 if not found.
154    pub fn texture_from_mc(&self, id: &str) -> gl::Texture {
155        use yog_abi::YogStr;
156        gl::Texture { handle: unsafe { (self.api().tex_from_mc)(YogStr::from_str(id)) } }
157    }
158
159    /// Delete a texture.
160    pub fn delete_texture(&self, tex: gl::Texture) {
161        unsafe { (self.api().tex_delete)(tex.handle) }
162    }
163
164    /// Bind a texture to the given sampler unit (0–7).
165    pub fn bind_texture(&self, unit: u32, tex: &gl::Texture) {
166        unsafe { (self.api().tex_bind)(unit, tex.handle) }
167    }
168
169    // ── Draw calls ────────────────────────────────────────────────────────────
170
171    /// Draw primitives using a vertex array (no index buffer).
172    pub fn draw_arrays(
173        &self, vao: &gl::VertexArray, prog: &gl::ShaderProgram,
174        mode: core::DrawMode, first: u32, count: u32,
175    ) {
176        unsafe { (self.api().draw_arrays)(vao.handle, prog.handle, mode as u8, first, count) }
177    }
178
179    /// Draw primitives via an index buffer.
180    /// `u32_indices`: `true` = `u32` indices, `false` = `u16` indices.
181    pub fn draw_elements(
182        &self, vao: &gl::VertexArray, ebo: &gl::Buffer, prog: &gl::ShaderProgram,
183        mode: core::DrawMode, count: u32, u32_indices: bool,
184    ) {
185        unsafe {
186            (self.api().draw_elements)(vao.handle, ebo.handle, prog.handle, mode as u8, count, u32_indices)
187        }
188    }
189
190    // ── Render state ──────────────────────────────────────────────────────────
191
192    /// Enable or disable alpha blending.
193    /// `src`/`dst`: GL blend factor constants from [`core::blend`].
194    pub fn set_blend(&self, enabled: bool, src: u32, dst: u32) {
195        unsafe { (self.api().set_blend)(enabled, src, dst) }
196    }
197
198    /// Enable or disable depth testing and writing.
199    pub fn set_depth(&self, test: bool, write: bool) {
200        unsafe { (self.api().set_depth)(test, write) }
201    }
202
203    /// Enable scissor clipping to a GUI-pixel rectangle.
204    pub fn set_scissor(&self, x: i32, y: i32, w: i32, h: i32) {
205        unsafe { (self.api().set_scissor)(x, y, w, h) }
206    }
207
208    /// Disable scissor clipping.
209    pub fn clear_scissor(&self) {
210        unsafe { (self.api().clear_scissor)() }
211    }
212
213    /// Set the GL viewport in physical pixels (x, y, width, height).
214    pub fn set_viewport(&self, x: i32, y: i32, w: i32, h: i32) {
215        unsafe { (self.api().set_viewport)(x, y, w, h) }
216    }
217
218    // ── 2D convenience ────────────────────────────────────────────────────────
219
220    /// Access the 2D drawing helpers (text, rectangles, MC textures).
221    /// These only work during `on_hud_render`.
222    pub fn draw2d(&self) -> draw2d::Draw2D<'_> { draw2d::Draw2D::new(self) }
223}
yog_gfx/lib.rs

yog_gfx/
lib.rs
