OpenGL drawing

## WebRender and OpenGL The general concept of interacting between OpenGL and webrender is fairly simple - you draw to a texture, hand it to webrender and webrender draws it when necessary. What can be quite confusing however, is the way that the process of drawing to an OpenGL texture is structured. The problem, however, is that if we'd allow directly pushing a `Texture` into the DOM, there would be no way of knowing how large that texture needs to be, since the size can depend on the size and number of its sibling DOM nodes. We need to know the size of the texture for aspect ratio correction and preventing stretched / blurry textures. Since the size of the rectangle that the texture should cover isn't known until it is time to layout the frame, we have to "delay" the rendering of the texture. In azuls case, the DOM-building step simply pushes a `GlTextureCallback` instead of the texture itself, i.e. a function that will render the texture in the future (after the layout step). The definition of a `GlTextureCallback` is the following: ```rust pub struct GlTextureCallback(pub fn(&StackCheckedPointer, LayoutInfo, HidpiAdjustedBounds) -> Option); ``` The `HidpiAdjustedBounds` contains the `width, height` of the desired texture as well as HiDPI information that you might need to scale the content of your texture correctly. If the callback returns `None`, the result is simply a white square. The `LayoutInfo` allows you to create an OpenGL texture like this: ```rust let mut texture = window_info.window.create_texture( hi_dpi_bounds.physical_size.width as usize, hi_dpi_bounds.physical_size.height as usize); ``` This creates an empty, uninitialized GPU texture. Note that we use the `physical_size` instead of the `logical_size` - the "logical size" is the HiDPI-adjusted version (which is usually what you want to calculate UI metrics), but the physical size is necessary in this case to provide the actual size of the texture, without a HiDPI scaling factor. Next, we clear the texture with the color red (255, 0, 0) and return it: ```rust texture.as_surface().clear_color(1.0, 0.0, 0.0, 1.0); return Some(texture); ``` Here, the `.as_surface()` activates the texture as the current FBO and draws to it. In this case we only clear the texture and return it, but of course, you can do much more here - upload and draw vertices and textures, activate and bind shaders, etc. See the `Surface` trait for more details. Azul requires at least OpenGL 3.1, which is checked at startup. You can rely on any function of OpenGL 3.1 being available at the time the callback is called. Here is a simple, full example: ```rust impl Layout for OpenGlAppState { fn layout(&self, _info: LayoutInfo) -> Dom { // See below for the meaning of StackCheckedPointer::new(self) Dom::new(NodeType::GlTexture(GlTextureCallback(render_my_texture), StackCheckedPointer::new(self))) } } fn render_my_texture( state: &StackCheckedPointer, info: LayoutInfo, hi_dpi_bounds: HidpiAdjustedBounds) -> Option { let mut texture = info.window.create_texture( hi_dpi_bounds.physical_size.width as usize, hi_dpi_bounds.physical_size.height as usize); texture.as_surface().clear_color(0.0, 1.0, 0.0, 1.0); Some(texture) } ``` This should give you a window with a red texture spanning the entire window. Remember than if a `Div` isn't limited in width / height, it will try to fill its parent, in this case the entire window. Try adding another `Div` in the `layout()` function and laying them out horizontally via CSS. You can decorate, skew, etc. your texture with CSS as you like. You can even use clipping and borders - OpenGL textures get treated the same way as regular images. ## Using and updating the components state in OpenGL textures Let's say you have a component that draws a cube to an OpenGL texture. You want to update the cube's rotation, translation and scale from another UI component. How would you implement such a widget? By now you have probably noticed the `StackCheckedPointer` that gets passed into the callback. This allows you to build a stack-allocated "component" that takes care of rendering itself, without the user calling any rendering code. As always, be careful to cast the pointer back to the type you created it with (see the [] chapter on why `StackCheckedPointer` is unsafe and how to migitate this problem to build a type-safe API). For example, we want to draw a cube, and control its rotation and scaling from another UI element. So we build a `CubeControl` that renders the cube and exposes an API to control the cubes rotation from any other UI element: ```rust // This is your "API" that other UI elements will mess with. For example, a user could hook up a button // to increase the scale by 0.1 every time a button is clicked. // // The point is that the CubeControl is just a dumb struct, it doesn't know about any other component. // The CubeControl contains all the "state" necessary for your renderer, the renderer itself doesn't know // about the state itself pub struct CubeControl { pub translation: Vector3, pub rotation: Quaternion, pub scaling: Vector3, } // This is your "rendering component", i.e. the thing that generates the DOM. // The procedure is similar to how you'd use a regular StackCheckedPointer #[derive(Default)] pub struct CubeRenderer { /* no state! */ } impl CubeRenderer { // The DOM stores the pointer to the state of the renderer. This state may be modified // by other UI controls before the GlTextureCallback is invoked. pub fn dom(data: &CubeControl) -> Dom { // Regular two-way data binding. Yes, you should use unwrap() here, since StackCheckedPointer // will only fail if the data is not on the stack. // // Think of this as a StackCheckedPointer - internally the `` type is erased // and you need to cast it back manually in the rendering callback let ptr = StackCheckedPointer::new(data); Dom::new(NodeType::GlTexture(GlTextureCallback(Self::render), ptr)) } // Private rendering function. External code doesn't need to know or care how the // `CubeRenderer` renders itself. fn render( state: &StackCheckedPointer, info: LayoutInfo, bounds: HidpiAdjustedBounds) { // Important: The type of the StackCheckedPointer has been erased // Casting the pointer back to anything else than a &mut CubeControl will invoke undefined behaviour. // HOWEVER: This function is (and should be) private. Only you, the **creator** of this component // can invoke UB, not the user. // // The way that the pointer is casted back is by giving it a function that has the same signature // as the render() function, but with a `&mut CubeControl` instead of a `&StackCheckedPointer`. // You do not have to worry about aliasing the pointer or race conditions, that is what the // StackCheckedPointer takes care of. fn render_inner(component_state: &mut CubeControl, info: LayoutInfo, bounds: HidpiAdjustedBounds) -> Texture { let texture = info.window.create_texture(width as u32, height as u32); // render_cube_to_surface (not included in this example for brevity) takes the texture // **and the current state of the component** and draws the cube on the surface according to the state render_cube_to_surface(texture.as_surface(), &component_state); // You could update your component_state here, if you'd like. texture } // Cast the StackCheckedPointer to a CubeControl, then invoke the render_inner function on it. Some(unsafe { state.invoke_mut_texture(render_inner, state, info, bounds) }) } } ``` Now, why is this so complicated? The answer is that now the API for the user of this component is very easy: ```rust // The data model of the final program struct DataModel { // Stores the state of the cubes rotation, scaling and translation. // The user doesn't need to know about any other details cube_control: CubeControl, } impl Layout for DataModel { fn layout(&self, _info: LayoutInfo) -> Dom { CubeRenderer::default().dom(&self.cube_control) } } ``` That's it! Now the user can hook up other components or custom callbacks that modify `self.cube_control` - but the application data is cleanly seperated from its view or other components. The user does also not need to care about how the component (in this case our `CubeRenderer`) renders itself, it is done "magically" by the framework - the framework determines when to call the `GlTextureCallback` and does so behind the back of the user. There is **no code** that the user has to write in order to render a `CubeRenderer`. The only limitation is that the `CubeControl` has to be stack-allocated, it can't be stored in a `Vec` or similar (because then, azul can't reason about the lifetime of the component, to make sure it's not dereferencing a dangling pointer). ## What is `StackCheckedPointer::new(self)` ? If you followed closely, you can probably already see what this is doing: `StackCheckedPointer` takes a reference to something on the stack that is contained in `T`. However, it can also take a reference to the **entire data model** (i.e. `T` itself). So `StackCheckedPointer::new(self)` essentially builds a `StackCheckedPointer` - the pointer can be safely casted back to a `OpenGlAppState`, at which point the callback has full control over the entire data model. Usually this is only something you'd want to do for prototyping, it's better for maintentance to build a custom component as shown above, for type safety reasons. ## Raw OpenGL For ease of use, azul exposes primitives of the `glium` library, which provide functions, such as for example `.clear_color()` - usually it's easier to work with that than with raw OpenGL - glium provides primitives for GLSL shader compilation and linking. Right now OpenGL is the only supported backend and that will probably stay this way in the future - since webrender is only portable to platforms that can target OpenGL, it wouldn't make sense to support other rendering backends, since webrender, the main appeal of this entire library, wouldn't run on them. There are experiments of porting webrender to Vulkan / DirectX or Metal, however these are, as the name implies, experimental indeed. ## Notes - It is not possible to render directly to the screen (for example, to use the built-in MSAA).