gsk4/auto/
gl_shader.rs

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

gsk4/auto/
gl_shader.rs
