1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
//! # What is this? //! //! [![crates.io](https://img.shields.io/crates/v/luminance.svg)](https://crates.io/crates/luminance) //! ![License](https://img.shields.io/badge/license-BSD3-blue.svg?style=flat) //! //! `luminance` is an effort to make graphics rendering simple and elegant. //! //! The aims of `luminance` are: //! //! - Making the **unsafe** and **stateful** **OpenGL** API **safe** and **stateless**. //! - Providing a simple and easy interface; that is, exposing core concepts without anything //! extra – just the bare stuff. //! - Easy to read with a good documentation and set of tutorials, so that new comers don’t have //! to learn a lot of new concepts to get their feet wet. //! - Need-driven: every piece of code added in the project must come from a real use case. If you //! feel something is missing, feel free to open an issue or even contribute! //! //! # What’s included? //! //! `luminance` is a rendering framework, not a 3D engine nor a video game framework. As so, it //! doesn’t include specifics like lights, materials, asset management nor scene description. It //! only provides a rendering library you can plug in whatever you want to. //! //! > There are several so-called 3D-engines out there on [crates.io](https://crates.io). Feel free //! > to have a look around. //! //! ## Features set //! //! - **Buffers**: buffers are way to communicate with the GPU; they represent regions of memory //! you can write to and read from. There’re several kinds of buffers you can create, among //! *vertex and index buffers*, *shader buffers*, *uniform buffers*, and so on and so forth…. //! - **Framebuffers**: framebuffers are used to hold renders. Each time you want to perform a //! render, you need to perform it into a framebuffer. Framebuffers can then be combined with //! each other to produce effects. //! - **Shaders**: `luminance` supports five kinds of shader stages: //! + Tessellation control shaders. //! + Tessellation evaluation shaders. //! + Vertex shaders. //! + Geometry shaders. //! + Fragment shaders. //! - **Vertices, indices, primitives and tessellations**: those are used to define a shape you //! can render into a framebuffer. //! - **Textures**: textures represent information packed into arrays on the GPU, and can be used //! to customize a visual aspect or pass information around in shaders. //! - **Blending**: blending is the process of taking two colors from two framebuffers and mixing //! them between each other. //! - And a lot of other cool things like *GPU commands*, *pipelines*, *uniform interfaces* and so //! on… //! //! # How to dig in? //! //! `luminance` is written to be fairly simple. The documentation is very transparent about what the //! library does and several articles will appear as the development goes on. Keep tuned! The //! [online documentation](https://docs.rs/luminance) is also a good link to have around. //! //! # Current implementation //! //! Currently, **luminance is powered by OpenGL 3.3**. It might change, but it’ll always be in favor //! on supporting more devices and technologies – a shift to Vulkan is planned, for instance. //! //! # Windowing //! //! `luminance` does not provide a way to create windows because it’s important that it not depend //! on windowing libraries – so that end-users can use whatever they like. Furthermore, such //! libraries typically implement windowing and events features, which have nothing to do with our //! initial purpose. //! //! # User-guide and contributor-guide //! //! If you just plan to use `luminance`, just read the *User-guide* section. //! //! If you plan to contribute to `luminance` (by writing a windowing crate or hacking on `luminance` //! directly), feel free to read the *Contributor-guide* section after having read the *User-guid* //! section as well. //! //! ## User-guide //! //! In order to get started, you need to create an object which type implements `GraphicsContext`. //! `luminance` ships with the trait but no implementor. You need to head over //! [crates.io and search for luminance crates](https://crates.io/search?q=luminance) to find a //! windowing backend first. //! //! Such a backend should expose a type which implements `GraphicsContext`. You can create one per //! thread. This limitation enables `luminance` not to perform plenty of runtime branching, //! minimizing the runtime overhead. //! //! > If you really want several contexts, you will need several OS threads. //! //! `GraphicsContext` is the entry-point of everything `luminance` provides. Feel free to dig in its //! documentation for further information on how to use `luminance`. Most objects you can create //! will need a mutable reference to such a context object. //! //! ## Contributor-guide //! //! You want to hack around `luminance` or provide a windowing crate? Everything you have to know is //! described in this section. //! //! ### `GraphicsContext`, `GraphicsState` and TLS //! //! In order to implement `GraphicsContext`, you need to know several points: //! //! - You can get a `GraphicsState` with the `GraphicsState::new` function. You **have** to match //! the return value. Depending on whether your implementation is the first asking a //! `GraphicsState` on the current thread, you might get (or not) an `Ok(state)`. If not, a //! descriptive error is returned. //! - You’re advised to `map` and `map_err` over the `GraphicsState::new` returned value to //! implement your own `new` function for your backend type because of the restriction of having //! only one context per thread in `luminance`. extern crate gl; pub mod blending; pub mod buffer; pub mod context; pub mod depth_test; pub mod face_culling; #[macro_use] pub mod framebuffer; #[macro_use] pub mod gtup; pub mod linear; pub mod pipeline; pub mod pixel; pub mod render_state; pub mod shader; pub mod state; pub mod tess; pub mod texture; pub mod vertex;