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}