Crate blue_engine

Expand description

§Blue Engine

Blue Engine is an easy to use, portable, and extendable/customizable graphics engine. Here lives the documentation for the engine.

§Setup

The setup and installation details live in the project’s guide. A basic program in Blue Engine is as follow:

§Example

use blue_engine::{
    prelude::{ Engine, ObjectSettings },
    primitive_shapes::triangle
};

fn main() {
    // initialize the engine
    let mut engine = Engine::new();

    // create a triangle
    triangle("my triangle", ObjectSettings::default(), &mut engine.renderer, &mut engine.objects);

   // run the engine
   engine
       .update_loop(move |_, _, _, _, _, _| {});
}

§Utilities

This crate is the core of the engine, but there is also utilities crate which have a lot of utilities for the engine such as lighting, physics, etc.

The code of the engine is organized in a rather different manner than traditional in the language. There are inspirations from other languages to make it easier to navigate the project.

§Older hardware

The engine uses WGPU under the hood for rendering. WGPU by nature is designed for modern hardware, so if you have or want to target older hardware, you might need to add a couple more things to EngineSettings during Engine::new_config:

set a backend that targets your older hardware, such as GL using the backends field: backend: blue_engine::wgpu::Backends::GL
experiement with the limits field, which describes what features you need. limits: blue_engine::wgpu::Limits::default(). there are three options for limits: default for normal hardware, downlevel_defaults which are compatible with GLES-3 and D3D-11, or downlevel_webgl2_defaults which is also compatible with WebGL2, and the lowest level for limits and can support very old hardware.

with these two changes, hopefully you can get Blue Engine to run on older hardware. If not, please let me know so I can help you further.

Modules§

engine: contains defintions of top level functionality of the Engine
error: interal error definitions of the engine
objects: contains the definition for Object type, which is a type that make it easier to manage data for rendering.
prelude: contains all the declarations such as structs, exports, enums, …
render: contains definition for rendering part of the engine.
utils: Utilities for the engine (soon moving to it’s own crate).
window: contains definition for creation of window and instance creation.

Structs§

Backends: Represents the backends that wgpu will use.
Camera: Container for the camera feature. The settings here are needed for algebra equations needed for camera vision and movement. Please leave it to the renderer to handle
CameraContainer: Container for Cameras
CommandEncoder: Encodes a series of GPU operations.
Engine: The engine is the main starting point of using the Blue Engine. Everything that runs on Blue Engine will be under this struct. The structure of engine is monolithic, but the underlying data and the way it works is not. It gives a set of default data to work with, but also allow you to go beyond that and work as low level as you wish to.
EngineSettings: Descriptor and settings for a window.
EventLoop: Provides a way to retrieve events from the system and from the windows that were registered to the events loop.
InputHelper: main struct
Instance: Instance buffer data storage
InstanceRaw: Instance buffer data that is sent to GPU
KeyEvent: Describes a keyboard input targeting a window.
LogicalPosition: A position represented in logical pixels.
LogicalSize: A size represented in logical pixels.
LogicalUnit: A logical pixel unit.
Object: Objects make it easier to work with Blue Engine, it automates most of work needed for creating 3D objects and showing them on screen. A range of default objects are available as well as ability to customize each of them and even create your own! You can also customize almost everything there is about them!
ObjectSettings: Extra settings to customize objects on time of creation
ObjectStorage: A unified way to handle objects
Operations: Pair of load and store operations for an attachment aspect.
PhysicalPosition: A position represented in physical pixels.
PhysicalSize: A size represented in physical pixels.
PhysicalUnit: A physical pixel unit.
Pipeline: Container for pipeline values. Each pipeline takes only 1 vertex shader, 1 fragment shader, 1 texture data, and optionally a vector of uniform data.
RenderPassColorAttachment: Describes a color attachment to a RenderPass.
RenderPassDescriptor: Describes the attachments of a render pass.
Renderer: Main renderer class. this will contain all methods and data related to the renderer
ShaderSettings: These definitions are taken from wgpu API docs
SignalStorage: Handles the live events in the engine
TextureView: Handle to a texture view.
Vertex: Will contain all details about a vertex and will be sent to GPU
VertexBuffers: Container for vertex and index buffer
Window: A wrapper for winit window to make it easier to use and more ergonomic.

Enums§

DeviceEvent: Represents raw hardware events that are not associated with any particular window.
ElementState: Describes the input state of a key.
Event: Describes a generic event.
Fullscreen: Fullscreen modes.
Key: Key represents the meaning of a keypress.
KeyCode: Code representing the location of a physical key
LoadOp: Operation to perform to the output attachment at the start of a render pass.
MemoryHints: Hints to the device about the memory allocation strategy.
MouseButton: Describes a button of a mouse controller.
PipelineData: Container for pipeline data. Allows for sharing resources with other objects
PixelUnit: A pixel unit that’s either physical or logical.
Position: A position that’s either physical or logical.
Projection: Container for the projection used by the camera
RotateAmount: Defines how the rotation amount is
RotateAxis: Defines how the rotation axis is
Size: A size that’s either physical or logical.
TextureData: Defines how the texture data is
TextureMode: Defines how the borders of texture would look like
WindowEvent: Describes an event from a [Window].

Constants§

DEPTH_FORMAT: Depth Format

Traits§

Pixel
Pod: Marker trait for “plain old data”.
Signal: Allows all events to be fetched directly, making it easier to add custom additions to the engine.
StringBuffer: A unified way to handle strings
StringBufferTrait: A trait for StringBuffer
Zeroable: Trait for types that can be safely created with zeroed.

Functions§

pixel_to_cartesian: This function helps in converting pixel value to the value that is between -1 and +1
validate_scale_factor: Checks that the scale factor is a normal positive f64.

Type Aliases§

CullMode: Face of a vertex.
FrontFace: Vertex winding order which classifies the “front” face of a triangle.
IndexFormat: Format of indices used with pipeline.
Matrix2: A 2x2 column major matrix.
Matrix3: A 3x3 column major matrix.
Matrix4: A 4x4 column major matrix.
PolygonMode: Type of drawing mode for polygons
PowerPreference: Power Preference when choosing a physical adapter.
Quaternion: A quaternion representing an orientation.
ShaderPrimitive: Primitive type the input mesh is composed of.
Shaders: Shaders are programs that runs on the GPU
Textures: Textures are image data that are sent to GPU to be set to a surface
UniformBuffers: Uniform Buffers are small amount of data that are sent from CPU to GPU
UnsignedIntType: The uint type used for indices and more
Vector2: A 2-dimensional vector.
Vector3: A 3-dimensional vector.
Vector4: A 4-dimensional vector.
WindowSize: To hold the width and height of the engine frames

Derive Macros§

Pod: Derive the Pod trait for a struct
Zeroable: Derive the Zeroable trait for a type.

Crate blue_engineCopy item path