gsk4/auto/gl_shader.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4#![allow(deprecated)]
5
6use crate::{ffi, GLUniformType, Renderer};
7use glib::{prelude::*, translate::*};
8
9glib::wrapper! {
10 /// A [`GLShader`][crate::GLShader] is a snippet of GLSL that is meant to run in the
11 /// fragment shader of the rendering pipeline.
12 ///
13 /// A fragment shader gets the coordinates being rendered as input and
14 /// produces the pixel values for that particular pixel. Additionally,
15 /// the shader can declare a set of other input arguments, called
16 /// uniforms (as they are uniform over all the calls to your shader in
17 /// each instance of use). A shader can also receive up to 4
18 /// textures that it can use as input when producing the pixel data.
19 ///
20 /// [`GLShader`][crate::GLShader] is usually used with gtk_snapshot_push_gl_shader()
21 /// to produce a [`GLShaderNode`][crate::GLShaderNode] in the rendering hierarchy,
22 /// and then its input textures are constructed by rendering the child
23 /// nodes to textures before rendering the shader node itself. (You can
24 /// pass texture nodes as children if you want to directly use a texture
25 /// as input).
26 ///
27 /// The actual shader code is GLSL code that gets combined with
28 /// some other code into the fragment shader. Since the exact
29 /// capabilities of the GPU driver differs between different OpenGL
30 /// drivers and hardware, GTK adds some defines that you can use
31 /// to ensure your GLSL code runs on as many drivers as it can.
32 ///
33 /// If the OpenGL driver is GLES, then the shader language version
34 /// is set to 100, and GSK_GLES will be defined in the shader.
35 ///
36 /// Otherwise, if the OpenGL driver does not support the 3.2 core profile,
37 /// then the shader will run with language version 110 for GL2 and 130 for GL3,
38 /// and GSK_LEGACY will be defined in the shader.
39 ///
40 /// If the OpenGL driver supports the 3.2 code profile, it will be used,
41 /// the shader language version is set to 150, and GSK_GL3 will be defined
42 /// in the shader.
43 ///
44 /// The main function the shader must implement is:
45 ///
46 /// **⚠️ The following code is in glsl ⚠️**
47 ///
48 /// ```glsl
49 /// void mainImage(out vec4 fragColor,
50 /// in vec2 fragCoord,
51 /// in vec2 resolution,
52 /// in vec2 uv)
53 /// ```
54 ///
55 /// Where the input @fragCoord is the coordinate of the pixel we're
56 /// currently rendering, relative to the boundary rectangle that was
57 /// specified in the [`GLShaderNode`][crate::GLShaderNode], and @resolution is the width and
58 /// height of that rectangle. This is in the typical GTK coordinate
59 /// system with the origin in the top left. @uv contains the u and v
60 /// coordinates that can be used to index a texture at the
61 /// corresponding point. These coordinates are in the [0..1]x[0..1]
62 /// region, with 0, 0 being in the lower left corder (which is typical
63 /// for OpenGL).
64 ///
65 /// The output @fragColor should be a RGBA color (with
66 /// premultiplied alpha) that will be used as the output for the
67 /// specified pixel location. Note that this output will be
68 /// automatically clipped to the clip region of the glshader node.
69 ///
70 /// In addition to the function arguments the shader can define
71 /// up to 4 uniforms for textures which must be called u_textureN
72 /// (i.e. u_texture1 to u_texture4) as well as any custom uniforms
73 /// you want of types int, uint, bool, float, vec2, vec3 or vec4.
74 ///
75 /// All textures sources contain premultiplied alpha colors, but if some
76 /// there are outer sources of colors there is a gsk_premultiply() helper
77 /// to compute premultiplication when needed.
78 ///
79 /// Note that GTK parses the uniform declarations, so each uniform has to
80 /// be on a line by itself with no other code, like so:
81 ///
82 /// **⚠️ The following code is in glsl ⚠️**
83 ///
84 /// ```glsl
85 /// uniform float u_time;
86 /// uniform vec3 u_color;
87 /// uniform sampler2D u_texture1;
88 /// uniform sampler2D u_texture2;
89 /// ```
90 ///
91 /// GTK uses the "gsk" namespace in the symbols it uses in the
92 /// shader, so your code should not use any symbols with the prefix gsk
93 /// or GSK. There are some helper functions declared that you can use:
94 ///
95 /// **⚠️ The following code is in glsl ⚠️**
96 ///
97 /// ```glsl
98 /// vec4 GskTexture(sampler2D sampler, vec2 texCoords);
99 /// ```
100 ///
101 /// This samples a texture (e.g. u_texture1) at the specified
102 /// coordinates, and contains some helper ifdefs to ensure that
103 /// it works on all OpenGL versions.
104 ///
105 /// You can compile the shader yourself using [`compile()`][Self::compile()],
106 /// otherwise the GSK renderer will do it when it handling the glshader
107 /// node. If errors occurs, the returned @error will include the glsl
108 /// sources, so you can see what GSK was passing to the compiler. You
109 /// can also set GSK_DEBUG=shaders in the environment to see the sources
110 /// and other relevant information about all shaders that GSK is handling.
111 ///
112 /// # An example shader
113 ///
114 /// **⚠️ The following code is in glsl ⚠️**
115 ///
116 /// ```glsl
117 /// uniform float position;
118 /// uniform sampler2D u_texture1;
119 /// uniform sampler2D u_texture2;
120 ///
121 /// void mainImage(out vec4 fragColor,
122 /// in vec2 fragCoord,
123 /// in vec2 resolution,
124 /// in vec2 uv) {
125 /// vec4 source1 = GskTexture(u_texture1, uv);
126 /// vec4 source2 = GskTexture(u_texture2, uv);
127 ///
128 /// fragColor = position * source1 + (1.0 - position) * source2;
129 /// }
130 /// ```
131 ///
132 /// # Deprecation
133 ///
134 /// This feature was deprecated in GTK 4.16 after the new rendering infrastructure
135 /// introduced in 4.14 did not support it.
136 /// The lack of Vulkan integration would have made it a very hard feature to support.
137 ///
138 /// If you want to use OpenGL directly, you should look at [GtkGLArea](../gtk4/class.GLArea.html)
139 /// which uses a different approach and is still well supported.
140 ///
141 /// ## Properties
142 ///
143 ///
144 /// #### `resource`
145 /// Resource containing the source code for the shader.
146 ///
147 /// If the shader source is not coming from a resource, this
148 /// will be [`None`].
149 ///
150 /// Readable | Writeable | Construct Only
151 ///
152 ///
153 /// #### `source`
154 /// The source code for the shader, as a `GBytes`.
155 ///
156 /// Readable | Writeable | Construct Only
157 #[doc(alias = "GskGLShader")]
158 pub struct GLShader(Object<ffi::GskGLShader, ffi::GskGLShaderClass>);
159
160 match fn {
161 type_ => || ffi::gsk_gl_shader_get_type(),
162 }
163}
164
165impl GLShader {
166 /// Creates a [`GLShader`][crate::GLShader] that will render pixels using the specified code.
167 ///
168 /// # Deprecated since 4.16
169 ///
170 /// GTK's new Vulkan-focused rendering
171 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
172 /// for OpenGL rendering.
173 /// ## `sourcecode`
174 /// GLSL sourcecode for the shader, as a `GBytes`
175 ///
176 /// # Returns
177 ///
178 /// A new [`GLShader`][crate::GLShader]
179 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
180 #[allow(deprecated)]
181 #[doc(alias = "gsk_gl_shader_new_from_bytes")]
182 #[doc(alias = "new_from_bytes")]
183 pub fn from_bytes(sourcecode: &glib::Bytes) -> GLShader {
184 assert_initialized_main_thread!();
185 unsafe {
186 from_glib_full(ffi::gsk_gl_shader_new_from_bytes(
187 sourcecode.to_glib_none().0,
188 ))
189 }
190 }
191
192 /// Creates a [`GLShader`][crate::GLShader] that will render pixels using the specified code.
193 ///
194 /// # Deprecated since 4.16
195 ///
196 /// GTK's new Vulkan-focused rendering
197 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
198 /// for OpenGL rendering.
199 /// ## `resource_path`
200 /// path to a resource that contains the GLSL sourcecode for
201 /// the shader
202 ///
203 /// # Returns
204 ///
205 /// A new [`GLShader`][crate::GLShader]
206 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
207 #[allow(deprecated)]
208 #[doc(alias = "gsk_gl_shader_new_from_resource")]
209 #[doc(alias = "new_from_resource")]
210 pub fn from_resource(resource_path: &str) -> GLShader {
211 assert_initialized_main_thread!();
212 unsafe {
213 from_glib_full(ffi::gsk_gl_shader_new_from_resource(
214 resource_path.to_glib_none().0,
215 ))
216 }
217 }
218
219 // rustdoc-stripper-ignore-next
220 /// Creates a new builder-pattern struct instance to construct [`GLShader`] objects.
221 ///
222 /// This method returns an instance of [`GLShaderBuilder`](crate::builders::GLShaderBuilder) which can be used to create [`GLShader`] objects.
223 pub fn builder() -> GLShaderBuilder {
224 GLShaderBuilder::new()
225 }
226
227 /// Tries to compile the @self for the given @renderer.
228 ///
229 /// If there is a problem, this function returns [`false`] and reports
230 /// an error. You should use this function before relying on the shader
231 /// for rendering and use a fallback with a simpler shader or without
232 /// shaders if it fails.
233 ///
234 /// Note that this will modify the rendering state (for example
235 /// change the current GL context) and requires the renderer to be
236 /// set up. This means that the widget has to be realized. Commonly you
237 /// want to call this from the realize signal of a widget, or during
238 /// widget snapshot.
239 ///
240 /// # Deprecated since 4.16
241 ///
242 /// GTK's new Vulkan-focused rendering
243 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
244 /// for OpenGL rendering.
245 /// ## `renderer`
246 /// a [`Renderer`][crate::Renderer]
247 ///
248 /// # Returns
249 ///
250 /// [`true`] on success, [`false`] if an error occurred
251 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
252 #[allow(deprecated)]
253 #[doc(alias = "gsk_gl_shader_compile")]
254 pub fn compile(&self, renderer: &impl IsA<Renderer>) -> Result<(), glib::Error> {
255 unsafe {
256 let mut error = std::ptr::null_mut();
257 let is_ok = ffi::gsk_gl_shader_compile(
258 self.to_glib_none().0,
259 renderer.as_ref().to_glib_none().0,
260 &mut error,
261 );
262 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
263 if error.is_null() {
264 Ok(())
265 } else {
266 Err(from_glib_full(error))
267 }
268 }
269 }
270
271 /// Looks for a uniform by the name @name, and returns the index
272 /// of the uniform, or -1 if it was not found.
273 ///
274 /// # Deprecated since 4.16
275 ///
276 /// GTK's new Vulkan-focused rendering
277 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
278 /// for OpenGL rendering.
279 /// ## `name`
280 /// uniform name
281 ///
282 /// # Returns
283 ///
284 /// The index of the uniform, or -1
285 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
286 #[allow(deprecated)]
287 #[doc(alias = "gsk_gl_shader_find_uniform_by_name")]
288 pub fn find_uniform_by_name(&self, name: &str) -> i32 {
289 unsafe {
290 ffi::gsk_gl_shader_find_uniform_by_name(self.to_glib_none().0, name.to_glib_none().0)
291 }
292 }
293
294 /// Gets the value of the uniform @idx in the @args block.
295 ///
296 /// The uniform must be of bool type.
297 ///
298 /// # Deprecated since 4.16
299 ///
300 /// GTK's new Vulkan-focused rendering
301 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
302 /// for OpenGL rendering.
303 /// ## `args`
304 /// uniform arguments
305 /// ## `idx`
306 /// index of the uniform
307 ///
308 /// # Returns
309 ///
310 /// The value
311 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
312 #[allow(deprecated)]
313 #[doc(alias = "gsk_gl_shader_get_arg_bool")]
314 #[doc(alias = "get_arg_bool")]
315 pub fn arg_bool(&self, args: &glib::Bytes, idx: i32) -> bool {
316 unsafe {
317 from_glib(ffi::gsk_gl_shader_get_arg_bool(
318 self.to_glib_none().0,
319 args.to_glib_none().0,
320 idx,
321 ))
322 }
323 }
324
325 /// Gets the value of the uniform @idx in the @args block.
326 ///
327 /// The uniform must be of float type.
328 ///
329 /// # Deprecated since 4.16
330 ///
331 /// GTK's new Vulkan-focused rendering
332 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
333 /// for OpenGL rendering.
334 /// ## `args`
335 /// uniform arguments
336 /// ## `idx`
337 /// index of the uniform
338 ///
339 /// # Returns
340 ///
341 /// The value
342 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
343 #[allow(deprecated)]
344 #[doc(alias = "gsk_gl_shader_get_arg_float")]
345 #[doc(alias = "get_arg_float")]
346 pub fn arg_float(&self, args: &glib::Bytes, idx: i32) -> f32 {
347 unsafe {
348 ffi::gsk_gl_shader_get_arg_float(self.to_glib_none().0, args.to_glib_none().0, idx)
349 }
350 }
351
352 /// Gets the value of the uniform @idx in the @args block.
353 ///
354 /// The uniform must be of int type.
355 ///
356 /// # Deprecated since 4.16
357 ///
358 /// GTK's new Vulkan-focused rendering
359 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
360 /// for OpenGL rendering.
361 /// ## `args`
362 /// uniform arguments
363 /// ## `idx`
364 /// index of the uniform
365 ///
366 /// # Returns
367 ///
368 /// The value
369 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
370 #[allow(deprecated)]
371 #[doc(alias = "gsk_gl_shader_get_arg_int")]
372 #[doc(alias = "get_arg_int")]
373 pub fn arg_int(&self, args: &glib::Bytes, idx: i32) -> i32 {
374 unsafe { ffi::gsk_gl_shader_get_arg_int(self.to_glib_none().0, args.to_glib_none().0, idx) }
375 }
376
377 /// Gets the value of the uniform @idx in the @args block.
378 ///
379 /// The uniform must be of uint type.
380 ///
381 /// # Deprecated since 4.16
382 ///
383 /// GTK's new Vulkan-focused rendering
384 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
385 /// for OpenGL rendering.
386 /// ## `args`
387 /// uniform arguments
388 /// ## `idx`
389 /// index of the uniform
390 ///
391 /// # Returns
392 ///
393 /// The value
394 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
395 #[allow(deprecated)]
396 #[doc(alias = "gsk_gl_shader_get_arg_uint")]
397 #[doc(alias = "get_arg_uint")]
398 pub fn arg_uint(&self, args: &glib::Bytes, idx: i32) -> u32 {
399 unsafe {
400 ffi::gsk_gl_shader_get_arg_uint(self.to_glib_none().0, args.to_glib_none().0, idx)
401 }
402 }
403
404 /// Get the size of the data block used to specify arguments for this shader.
405 ///
406 /// # Deprecated since 4.16
407 ///
408 /// GTK's new Vulkan-focused rendering
409 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
410 /// for OpenGL rendering.
411 ///
412 /// # Returns
413 ///
414 /// The size of the data block
415 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
416 #[allow(deprecated)]
417 #[doc(alias = "gsk_gl_shader_get_args_size")]
418 #[doc(alias = "get_args_size")]
419 pub fn args_size(&self) -> usize {
420 unsafe { ffi::gsk_gl_shader_get_args_size(self.to_glib_none().0) }
421 }
422
423 /// Returns the number of textures that the shader requires.
424 ///
425 /// This can be used to check that the a passed shader works
426 /// in your usecase. It is determined by looking at the highest
427 /// u_textureN value that the shader defines.
428 ///
429 /// # Deprecated since 4.16
430 ///
431 /// GTK's new Vulkan-focused rendering
432 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
433 /// for OpenGL rendering.
434 ///
435 /// # Returns
436 ///
437 /// The number of texture inputs required by @self
438 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
439 #[allow(deprecated)]
440 #[doc(alias = "gsk_gl_shader_get_n_textures")]
441 #[doc(alias = "get_n_textures")]
442 pub fn n_textures(&self) -> i32 {
443 unsafe { ffi::gsk_gl_shader_get_n_textures(self.to_glib_none().0) }
444 }
445
446 /// Get the number of declared uniforms for this shader.
447 ///
448 /// # Deprecated since 4.16
449 ///
450 /// GTK's new Vulkan-focused rendering
451 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
452 /// for OpenGL rendering.
453 ///
454 /// # Returns
455 ///
456 /// The number of declared uniforms
457 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
458 #[allow(deprecated)]
459 #[doc(alias = "gsk_gl_shader_get_n_uniforms")]
460 #[doc(alias = "get_n_uniforms")]
461 pub fn n_uniforms(&self) -> i32 {
462 unsafe { ffi::gsk_gl_shader_get_n_uniforms(self.to_glib_none().0) }
463 }
464
465 /// Gets the resource path for the GLSL sourcecode being used
466 /// to render this shader.
467 ///
468 /// # Deprecated since 4.16
469 ///
470 /// GTK's new Vulkan-focused rendering
471 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
472 /// for OpenGL rendering.
473 ///
474 /// # Returns
475 ///
476 /// The resource path for the shader
477 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
478 #[allow(deprecated)]
479 #[doc(alias = "gsk_gl_shader_get_resource")]
480 #[doc(alias = "get_resource")]
481 pub fn resource(&self) -> Option<glib::GString> {
482 unsafe { from_glib_none(ffi::gsk_gl_shader_get_resource(self.to_glib_none().0)) }
483 }
484
485 /// Gets the GLSL sourcecode being used to render this shader.
486 ///
487 /// # Deprecated since 4.16
488 ///
489 /// GTK's new Vulkan-focused rendering
490 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
491 /// for OpenGL rendering.
492 ///
493 /// # Returns
494 ///
495 /// The source code for the shader
496 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
497 #[allow(deprecated)]
498 #[doc(alias = "gsk_gl_shader_get_source")]
499 #[doc(alias = "get_source")]
500 pub fn source(&self) -> glib::Bytes {
501 unsafe { from_glib_none(ffi::gsk_gl_shader_get_source(self.to_glib_none().0)) }
502 }
503
504 /// Get the name of the declared uniform for this shader at index @idx.
505 ///
506 /// # Deprecated since 4.16
507 ///
508 /// GTK's new Vulkan-focused rendering
509 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
510 /// for OpenGL rendering.
511 /// ## `idx`
512 /// index of the uniform
513 ///
514 /// # Returns
515 ///
516 /// The name of the declared uniform
517 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
518 #[allow(deprecated)]
519 #[doc(alias = "gsk_gl_shader_get_uniform_name")]
520 #[doc(alias = "get_uniform_name")]
521 pub fn uniform_name(&self, idx: i32) -> glib::GString {
522 unsafe {
523 from_glib_none(ffi::gsk_gl_shader_get_uniform_name(
524 self.to_glib_none().0,
525 idx,
526 ))
527 }
528 }
529
530 /// Get the offset into the data block where data for this uniforms is stored.
531 ///
532 /// # Deprecated since 4.16
533 ///
534 /// GTK's new Vulkan-focused rendering
535 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
536 /// for OpenGL rendering.
537 /// ## `idx`
538 /// index of the uniform
539 ///
540 /// # Returns
541 ///
542 /// The data offset
543 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
544 #[allow(deprecated)]
545 #[doc(alias = "gsk_gl_shader_get_uniform_offset")]
546 #[doc(alias = "get_uniform_offset")]
547 pub fn uniform_offset(&self, idx: i32) -> i32 {
548 unsafe { ffi::gsk_gl_shader_get_uniform_offset(self.to_glib_none().0, idx) }
549 }
550
551 /// Get the type of the declared uniform for this shader at index @idx.
552 ///
553 /// # Deprecated since 4.16
554 ///
555 /// GTK's new Vulkan-focused rendering
556 /// does not support this feature. Use [GtkGLArea](../gtk4/class.GLArea.html)
557 /// for OpenGL rendering.
558 /// ## `idx`
559 /// index of the uniform
560 ///
561 /// # Returns
562 ///
563 /// The type of the declared uniform
564 #[cfg_attr(feature = "v4_16", deprecated = "Since 4.16")]
565 #[allow(deprecated)]
566 #[doc(alias = "gsk_gl_shader_get_uniform_type")]
567 #[doc(alias = "get_uniform_type")]
568 pub fn uniform_type(&self, idx: i32) -> GLUniformType {
569 unsafe {
570 from_glib(ffi::gsk_gl_shader_get_uniform_type(
571 self.to_glib_none().0,
572 idx,
573 ))
574 }
575 }
576}
577
578// rustdoc-stripper-ignore-next
579/// A [builder-pattern] type to construct [`GLShader`] objects.
580///
581/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
582#[must_use = "The builder must be built to be used"]
583pub struct GLShaderBuilder {
584 builder: glib::object::ObjectBuilder<'static, GLShader>,
585}
586
587impl GLShaderBuilder {
588 fn new() -> Self {
589 Self {
590 builder: glib::object::Object::builder(),
591 }
592 }
593
594 /// Resource containing the source code for the shader.
595 ///
596 /// If the shader source is not coming from a resource, this
597 /// will be [`None`].
598 pub fn resource(self, resource: impl Into<glib::GString>) -> Self {
599 Self {
600 builder: self.builder.property("resource", resource.into()),
601 }
602 }
603
604 /// The source code for the shader, as a `GBytes`.
605 pub fn source(self, source: &glib::Bytes) -> Self {
606 Self {
607 builder: self.builder.property("source", source.clone()),
608 }
609 }
610
611 // rustdoc-stripper-ignore-next
612 /// Build the [`GLShader`].
613 #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
614 pub fn build(self) -> GLShader {
615 assert_initialized_main_thread!();
616 self.builder.build()
617 }
618}