byte-engine-ghi 0.1.0

Graphics hardware interface layer used by Byte-Engine.
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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

use std::borrow::Cow;

use crate::{
	pipelines::{ShaderParameter, VertexElement},
	Formats,
};

/// The `Builder` struct collects portable raster state before a backend creates its native pipeline.
pub struct Builder<'a> {
	pub(crate) push_constant_ranges: Cow<'a, [crate::pipelines::PushConstantRange]>,
	pub(crate) vertex_elements: Cow<'a, [VertexElement<'a>]>,
	pub(crate) render_targets: Cow<'a, [AttachmentDescriptor]>,
	pub(crate) shaders: Cow<'a, [ShaderParameter<'a>]>,
	pub(crate) face_winding: FaceWinding,
	pub(crate) cull_mode: CullMode,
	pub(crate) depth_write: bool,
}

impl<'a> Builder<'a> {
	pub fn new(
		push_constant_ranges: &'a [crate::pipelines::PushConstantRange],
		vertex_elements: &'a [VertexElement],
		shaders: &'a [ShaderParameter],
		render_targets: &'a [AttachmentDescriptor],
	) -> Self {
		Self {
			push_constant_ranges: Cow::Borrowed(push_constant_ranges),
			vertex_elements: Cow::Borrowed(vertex_elements),
			shaders: Cow::Borrowed(shaders),
			render_targets: Cow::Borrowed(render_targets),
			face_winding: FaceWinding::Clockwise,
			cull_mode: CullMode::Back,
			depth_write: true,
		}
	}

	pub fn face_winding(mut self, face_winding: FaceWinding) -> Self {
		self.face_winding = face_winding;
		self
	}

	pub fn cull_mode(mut self, cull_mode: CullMode) -> Self {
		self.cull_mode = cull_mode;
		self
	}

	/// Selects whether passing depth fragments update the bound depth attachment.
	pub fn depth_write(mut self, depth_write: bool) -> Self {
		self.depth_write = depth_write;
		self
	}
}

#[derive(Clone, Copy, Default)]
pub enum FaceWinding {
	#[default]
	Clockwise,
	CounterClockwise,
}

#[derive(Clone, Copy, Default)]
pub enum CullMode {
	None,
	Front,
	#[default]
	Back,
}

#[derive(Clone, Copy, Default)]
pub enum BlendMode {
	#[default]
	None,
	/// Applies straight-alpha source-over blending to both color and alpha.
	Alpha,
}

#[derive(Clone, Copy)]
/// The `AttachmentDescriptor` struct captures the render-target state a raster pipeline needs for a single attachment.
pub struct AttachmentDescriptor {
	/// The format of the attachment.
	pub(crate) format: Formats,
	/// The image layer index for the attachment.
	pub(crate) layer: Option<u32>,
	/// The blend behavior to use when writing the attachment.
	pub(crate) blend: BlendMode,
}

impl AttachmentDescriptor {
	pub fn new(format: Formats) -> Self {
		Self {
			format,
			layer: None,
			blend: BlendMode::None,
		}
	}

	pub fn layer(mut self, layer: u32) -> Self {
		self.layer = Some(layer);
		self
	}

	pub fn blend(mut self, blend: BlendMode) -> Self {
		self.blend = blend;
		self
	}
}

#[cfg(test)]
mod tests {
	use super::{AttachmentDescriptor, BlendMode, Builder, CullMode, FaceWinding};

	#[test]
	fn attachment_descriptor_defaults_to_no_blending() {
		let descriptor = AttachmentDescriptor::new(crate::Formats::RGBA8UNORM);

		assert!(matches!(descriptor.blend, BlendMode::None));
	}

	#[test]
	fn attachment_descriptor_can_enable_alpha_blending() {
		let descriptor = AttachmentDescriptor::new(crate::Formats::RGBA8UNORM).blend(BlendMode::Alpha);

		assert!(matches!(descriptor.blend, BlendMode::Alpha));
	}

	#[test]
	fn builder_defaults_to_clockwise_backface_culling() {
		let builder = Builder::new(&[], &[], &[], &[]);

		assert!(matches!(builder.face_winding, FaceWinding::Clockwise));
		assert!(matches!(builder.cull_mode, CullMode::Back));
	}

	#[test]
	fn builder_defaults_to_depth_writes() {
		let builder = Builder::new(&[], &[], &[], &[]);

		assert!(builder.depth_write);
	}

	#[test]
	fn builder_can_disable_depth_writes() {
		let builder = Builder::new(&[], &[], &[], &[]).depth_write(false);

		assert!(!builder.depth_write);
	}
}