@gtkx/ffi 0.1.44 → 0.1.46

package/dist/generated/gdk/glcontext.d.ts

@@ -1,26 +1,229 @@
 import { Ref } from "@gtkx/native";
 import { GLAPI } from "./enums.js";
 import { DrawContext } from "./draw-context.js";
+/**
+ * Represents a platform-specific OpenGL draw context.
+ *
+ * `GdkGLContext`s are created for a surface using
+ * [method@Gdk.Surface.create_gl_context], and the context will match
+ * the characteristics of the surface.
+ *
+ * A `GdkGLContext` is not tied to any particular normal framebuffer.
+ * For instance, it cannot draw to the surface back buffer. The GDK
+ * repaint system is in full control of the painting to that. Instead,
+ * you can create render buffers or textures and use [func@cairo_draw_from_gl]
+ * in the draw function of your widget to draw them. Then GDK will handle
+ * the integration of your rendering with that of other widgets.
+ *
+ * Support for `GdkGLContext` is platform-specific and context creation
+ * can fail, returning %NULL context.
+ *
+ * A `GdkGLContext` has to be made "current" in order to start using
+ * it, otherwise any OpenGL call will be ignored.
+ *
+ * ## Creating a new OpenGL context
+ *
+ * In order to create a new `GdkGLContext` instance you need a `GdkSurface`,
+ * which you typically get during the realize call of a widget.
+ *
+ * A `GdkGLContext` is not realized until either [method@Gdk.GLContext.make_current]
+ * or [method@Gdk.GLContext.realize] is called. It is possible to specify
+ * details of the GL context like the OpenGL version to be used, or whether
+ * the GL context should have extra state validation enabled after calling
+ * [method@Gdk.Surface.create_gl_context] by calling [method@Gdk.GLContext.realize].
+ * If the realization fails you have the option to change the settings of
+ * the `GdkGLContext` and try again.
+ *
+ * ## Using a GdkGLContext
+ *
+ * You will need to make the `GdkGLContext` the current context before issuing
+ * OpenGL calls; the system sends OpenGL commands to whichever context is current.
+ * It is possible to have multiple contexts, so you always need to ensure that
+ * the one which you want to draw with is the current one before issuing commands:
+ *
+ * ```c
+ * gdk_gl_context_make_current (context);
+ * ```
+ *
+ * You can now perform your drawing using OpenGL commands.
+ *
+ * You can check which `GdkGLContext` is the current one by using
+ * [func@Gdk.GLContext.get_current]; you can also unset any `GdkGLContext`
+ * that is currently set by calling [func@Gdk.GLContext.clear_current].
+ */
 export declare class GLContext extends DrawContext {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Clears the current `GdkGLContext`.
+     *
+     * Any OpenGL call after this function returns will be ignored
+     * until [method@Gdk.GLContext.make_current] is called.
+     */
     static clearCurrent(): void;
+    /**
+     * Retrieves the current `GdkGLContext`.
+     */
     static getCurrent(): GLContext;
+    /**
+     * Gets the allowed APIs set via gdk_gl_context_set_allowed_apis().
+     */
     getAllowedApis(): GLAPI;
+    /**
+     * Gets the API currently in use.
+     *
+     * If the renderer has not been realized yet, 0 is returned.
+     */
     getApi(): GLAPI;
+    /**
+     * Retrieves whether the context is doing extra validations and runtime checking.
+     *
+     * See [method@Gdk.GLContext.set_debug_enabled].
+     */
     getDebugEnabled(): boolean;
+    /**
+     * Retrieves whether the context is forward-compatible.
+     *
+     * See [method@Gdk.GLContext.set_forward_compatible].
+     */
     getForwardCompatible(): boolean;
+    /**
+     * Retrieves required OpenGL version set as a requirement for the `context` realization. It will not change even if a greater OpenGL version is supported
+     * and used after the `context` is realized. See
+     * [method@Gdk.GLContext.get_version] for the real version in use.
+     *
+     * See [method@Gdk.GLContext.set_required_version].
+     * @param major - return location for the major version to request
+     * @param minor - return location for the minor version to request
+     */
     getRequiredVersion(major?: Ref<number> | null, minor?: Ref<number> | null): void;
+    /**
+     * Used to retrieves the `GdkGLContext` that this `context` share data with.
+     *
+     * As many contexts can share data now and no single shared context exists
+     * anymore, this function has been deprecated and now always returns %NULL.
+     */
     getSharedContext(): GLContext | null;
+    /**
+     * Checks whether the `context` is using an OpenGL or OpenGL ES profile.
+     */
     getUseEs(): boolean;
+    /**
+     * Retrieves the OpenGL version of the @context.
+     *
+     * The `context` must be realized prior to calling this function.
+     * @param major - return location for the major version
+     * @param minor - return location for the minor version
+     */
     getVersion(major: Ref<number>, minor: Ref<number>): void;
+    /**
+     * Whether the `GdkGLContext` is in legacy mode or not.
+     *
+     * The `GdkGLContext` must be realized before calling this function.
+     *
+     * When realizing a GL context, GDK will try to use the OpenGL 3.2 core
+     * profile; this profile removes all the OpenGL API that was deprecated
+     * prior to the 3.2 version of the specification. If the realization is
+     * successful, this function will return %FALSE.
+     *
+     * If the underlying OpenGL implementation does not support core profiles,
+     * GDK will fall back to a pre-3.2 compatibility profile, and this function
+     * will return %TRUE.
+     *
+     * You can use the value returned by this function to decide which kind
+     * of OpenGL API to use, or whether to do extension discovery, or what
+     * kind of shader programs to load.
+     */
     isLegacy(): boolean;
+    /**
+     * Checks if the two GL contexts can share resources.
+     *
+     * When they can, the texture IDs from `other` can be used in @self. This
+     * is particularly useful when passing `GdkGLTexture` objects between
+     * different contexts.
+     *
+     * Contexts created for the same display with the same properties will
+     * always be compatible, even if they are created for different surfaces.
+     * For other contexts it depends on the GL backend.
+     *
+     * Both contexts must be realized for this check to succeed. If either one
+     * is not, this function will return %FALSE.
+     * @param other - the `GdkGLContext` that should be compatible with @self
+     */
     isShared(other: GLContext): boolean;
+    /**
+     * Makes the `context` the current one.
+     */
     makeCurrent(): void;
+    /**
+     * Realizes the given `GdkGLContext`.
+     *
+     * It is safe to call this function on a realized `GdkGLContext`.
+     */
     realize(): boolean;
+    /**
+     * Sets the allowed APIs. When gdk_gl_context_realize() is called, only the
+     * allowed APIs will be tried. If you set this to 0, realizing will always fail.
+     *
+     * If you set it on a realized context, the property will not have any effect.
+     * It is only relevant during gdk_gl_context_realize().
+     *
+     * By default, all APIs are allowed.
+     * @param apis - the allowed APIs
+     */
     setAllowedApis(apis: GLAPI): void;
+    /**
+     * Sets whether the `GdkGLContext` should perform extra validations and
+     * runtime checking.
+     *
+     * This is useful during development, but has additional overhead.
+     *
+     * The `GdkGLContext` must not be realized or made current prior to
+     * calling this function.
+     * @param enabled - whether to enable debugging in the context
+     */
     setDebugEnabled(enabled: boolean): void;
+    /**
+     * Sets whether the `GdkGLContext` should be forward-compatible.
+     *
+     * Forward-compatible contexts must not support OpenGL functionality that
+     * has been marked as deprecated in the requested version; non-forward
+     * compatible contexts, on the other hand, must support both deprecated and
+     * non deprecated functionality.
+     *
+     * The `GdkGLContext` must not be realized or made current prior to calling
+     * this function.
+     * @param compatible - whether the context should be forward-compatible
+     */
     setForwardCompatible(compatible: boolean): void;
+    /**
+     * Sets the major and minor version of OpenGL to request.
+     *
+     * Setting `major` and `minor` to zero will use the default values.
+     *
+     * Setting `major` and `minor` lower than the minimum versions required
+     * by GTK will result in the context choosing the minimum version.
+     *
+     * The `context` must not be realized or made current prior to calling
+     * this function.
+     * @param major - the major version to request
+     * @param minor - the minor version to request
+     */
     setRequiredVersion(major: number, minor: number): void;
+    /**
+     * Requests that GDK create an OpenGL ES context instead of an OpenGL one.
+     *
+     * Not all platforms support OpenGL ES.
+     *
+     * The `context` must not have been realized.
+     *
+     * By default, GDK will attempt to automatically detect whether the
+     * underlying GL implementation is OpenGL or OpenGL ES once the `context` is realized.
+     *
+     * You should check the return value of [method@Gdk.GLContext.get_use_es]
+     * after calling [method@Gdk.GLContext.realize] to decide whether to use
+     * the OpenGL or OpenGL ES API, extensions, or shaders.
+     * @param useEs - whether the context should use OpenGL ES instead of OpenGL,
+     */
     setUseEs(useEs: number): void;
 }

package/dist/generated/gdk/glcontext.js

@@ -1,6 +1,56 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import { DrawContext } from "./draw-context.js";
+/**
+ * Represents a platform-specific OpenGL draw context.
+ *
+ * `GdkGLContext`s are created for a surface using
+ * [method@Gdk.Surface.create_gl_context], and the context will match
+ * the characteristics of the surface.
+ *
+ * A `GdkGLContext` is not tied to any particular normal framebuffer.
+ * For instance, it cannot draw to the surface back buffer. The GDK
+ * repaint system is in full control of the painting to that. Instead,
+ * you can create render buffers or textures and use [func@cairo_draw_from_gl]
+ * in the draw function of your widget to draw them. Then GDK will handle
+ * the integration of your rendering with that of other widgets.
+ *
+ * Support for `GdkGLContext` is platform-specific and context creation
+ * can fail, returning %NULL context.
+ *
+ * A `GdkGLContext` has to be made "current" in order to start using
+ * it, otherwise any OpenGL call will be ignored.
+ *
+ * ## Creating a new OpenGL context
+ *
+ * In order to create a new `GdkGLContext` instance you need a `GdkSurface`,
+ * which you typically get during the realize call of a widget.
+ *
+ * A `GdkGLContext` is not realized until either [method@Gdk.GLContext.make_current]
+ * or [method@Gdk.GLContext.realize] is called. It is possible to specify
+ * details of the GL context like the OpenGL version to be used, or whether
+ * the GL context should have extra state validation enabled after calling
+ * [method@Gdk.Surface.create_gl_context] by calling [method@Gdk.GLContext.realize].
+ * If the realization fails you have the option to change the settings of
+ * the `GdkGLContext` and try again.
+ *
+ * ## Using a GdkGLContext
+ *
+ * You will need to make the `GdkGLContext` the current context before issuing
+ * OpenGL calls; the system sends OpenGL commands to whichever context is current.
+ * It is possible to have multiple contexts, so you always need to ensure that
+ * the one which you want to draw with is the current one before issuing commands:
+ *
+ * ```c
+ * gdk_gl_context_make_current (context);
+ * ```
+ *
+ * You can now perform your drawing using OpenGL commands.
+ *
+ * You can check which `GdkGLContext` is the current one by using
+ * [func@Gdk.GLContext.get_current]; you can also unset any `GdkGLContext`
+ * that is currently set by calling [func@Gdk.GLContext.clear_current].
+ */
 export class GLContext extends DrawContext {
     constructor(...args) {
         super(...args);
@@ -16,11 +66,20 @@ export class GLContext extends DrawContext {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Clears the current `GdkGLContext`.
+     *
+     * Any OpenGL call after this function returns will be ignored
+     * until [method@Gdk.GLContext.make_current] is called.
+     */
     static clearCurrent() {
         call("libgtk-4.so.1", "gdk_gl_context_clear_current", [], {
             type: "undefined",
         });
     }
+    /**
+     * Retrieves the current `GdkGLContext`.
+     */
     static getCurrent() {
         const ptr = call("libgtk-4.so.1", "gdk_gl_context_get_current", [], {
             type: "gobject",
@@ -28,6 +87,9 @@ export class GLContext extends DrawContext {
         });
         return getObject(ptr, GLContext);
     }
+    /**
+     * Gets the allowed APIs set via gdk_gl_context_set_allowed_apis().
+     */
     getAllowedApis() {
         return call("libgtk-4.so.1", "gdk_gl_context_get_allowed_apis", [
             {
@@ -36,6 +98,11 @@ export class GLContext extends DrawContext {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the API currently in use.
+     *
+     * If the renderer has not been realized yet, 0 is returned.
+     */
     getApi() {
         return call("libgtk-4.so.1", "gdk_gl_context_get_api", [
             {
@@ -44,6 +111,11 @@ export class GLContext extends DrawContext {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Retrieves whether the context is doing extra validations and runtime checking.
+     *
+     * See [method@Gdk.GLContext.set_debug_enabled].
+     */
     getDebugEnabled() {
         return call("libgtk-4.so.1", "gdk_gl_context_get_debug_enabled", [
             {
@@ -52,6 +124,11 @@ export class GLContext extends DrawContext {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves whether the context is forward-compatible.
+     *
+     * See [method@Gdk.GLContext.set_forward_compatible].
+     */
     getForwardCompatible() {
         return call("libgtk-4.so.1", "gdk_gl_context_get_forward_compatible", [
             {
@@ -60,6 +137,15 @@ export class GLContext extends DrawContext {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves required OpenGL version set as a requirement for the `context` realization. It will not change even if a greater OpenGL version is supported
+     * and used after the `context` is realized. See
+     * [method@Gdk.GLContext.get_version] for the real version in use.
+     *
+     * See [method@Gdk.GLContext.set_required_version].
+     * @param major - return location for the major version to request
+     * @param minor - return location for the minor version to request
+     */
     getRequiredVersion(major, minor) {
         call("libgtk-4.so.1", "gdk_gl_context_get_required_version", [
             {
@@ -84,6 +170,12 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Used to retrieves the `GdkGLContext` that this `context` share data with.
+     *
+     * As many contexts can share data now and no single shared context exists
+     * anymore, this function has been deprecated and now always returns %NULL.
+     */
     getSharedContext() {
         const ptr = call("libgtk-4.so.1", "gdk_gl_context_get_shared_context", [
             {
@@ -95,6 +187,9 @@ export class GLContext extends DrawContext {
             return null;
         return getObject(ptr, GLContext);
     }
+    /**
+     * Checks whether the `context` is using an OpenGL or OpenGL ES profile.
+     */
     getUseEs() {
         return call("libgtk-4.so.1", "gdk_gl_context_get_use_es", [
             {
@@ -103,6 +198,13 @@ export class GLContext extends DrawContext {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the OpenGL version of the @context.
+     *
+     * The `context` must be realized prior to calling this function.
+     * @param major - return location for the major version
+     * @param minor - return location for the minor version
+     */
     getVersion(major, minor) {
         call("libgtk-4.so.1", "gdk_gl_context_get_version", [
             {
@@ -125,6 +227,24 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Whether the `GdkGLContext` is in legacy mode or not.
+     *
+     * The `GdkGLContext` must be realized before calling this function.
+     *
+     * When realizing a GL context, GDK will try to use the OpenGL 3.2 core
+     * profile; this profile removes all the OpenGL API that was deprecated
+     * prior to the 3.2 version of the specification. If the realization is
+     * successful, this function will return %FALSE.
+     *
+     * If the underlying OpenGL implementation does not support core profiles,
+     * GDK will fall back to a pre-3.2 compatibility profile, and this function
+     * will return %TRUE.
+     *
+     * You can use the value returned by this function to decide which kind
+     * of OpenGL API to use, or whether to do extension discovery, or what
+     * kind of shader programs to load.
+     */
     isLegacy() {
         return call("libgtk-4.so.1", "gdk_gl_context_is_legacy", [
             {
@@ -133,6 +253,21 @@ export class GLContext extends DrawContext {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if the two GL contexts can share resources.
+     *
+     * When they can, the texture IDs from `other` can be used in @self. This
+     * is particularly useful when passing `GdkGLTexture` objects between
+     * different contexts.
+     *
+     * Contexts created for the same display with the same properties will
+     * always be compatible, even if they are created for different surfaces.
+     * For other contexts it depends on the GL backend.
+     *
+     * Both contexts must be realized for this check to succeed. If either one
+     * is not, this function will return %FALSE.
+     * @param other - the `GdkGLContext` that should be compatible with @self
+     */
     isShared(other) {
         return call("libgtk-4.so.1", "gdk_gl_context_is_shared", [
             {
@@ -145,6 +280,9 @@ export class GLContext extends DrawContext {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Makes the `context` the current one.
+     */
     makeCurrent() {
         call("libgtk-4.so.1", "gdk_gl_context_make_current", [
             {
@@ -153,6 +291,11 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Realizes the given `GdkGLContext`.
+     *
+     * It is safe to call this function on a realized `GdkGLContext`.
+     */
     realize() {
         const error = { value: null };
         const result = call("libgtk-4.so.1", "gdk_gl_context_realize", [
@@ -177,6 +320,16 @@ export class GLContext extends DrawContext {
         }
         return result;
     }
+    /**
+     * Sets the allowed APIs. When gdk_gl_context_realize() is called, only the
+     * allowed APIs will be tried. If you set this to 0, realizing will always fail.
+     *
+     * If you set it on a realized context, the property will not have any effect.
+     * It is only relevant during gdk_gl_context_realize().
+     *
+     * By default, all APIs are allowed.
+     * @param apis - the allowed APIs
+     */
     setAllowedApis(apis) {
         call("libgtk-4.so.1", "gdk_gl_context_set_allowed_apis", [
             {
@@ -189,6 +342,16 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the `GdkGLContext` should perform extra validations and
+     * runtime checking.
+     *
+     * This is useful during development, but has additional overhead.
+     *
+     * The `GdkGLContext` must not be realized or made current prior to
+     * calling this function.
+     * @param enabled - whether to enable debugging in the context
+     */
     setDebugEnabled(enabled) {
         call("libgtk-4.so.1", "gdk_gl_context_set_debug_enabled", [
             {
@@ -201,6 +364,18 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the `GdkGLContext` should be forward-compatible.
+     *
+     * Forward-compatible contexts must not support OpenGL functionality that
+     * has been marked as deprecated in the requested version; non-forward
+     * compatible contexts, on the other hand, must support both deprecated and
+     * non deprecated functionality.
+     *
+     * The `GdkGLContext` must not be realized or made current prior to calling
+     * this function.
+     * @param compatible - whether the context should be forward-compatible
+     */
     setForwardCompatible(compatible) {
         call("libgtk-4.so.1", "gdk_gl_context_set_forward_compatible", [
             {
@@ -213,6 +388,19 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the major and minor version of OpenGL to request.
+     *
+     * Setting `major` and `minor` to zero will use the default values.
+     *
+     * Setting `major` and `minor` lower than the minimum versions required
+     * by GTK will result in the context choosing the minimum version.
+     *
+     * The `context` must not be realized or made current prior to calling
+     * this function.
+     * @param major - the major version to request
+     * @param minor - the minor version to request
+     */
     setRequiredVersion(major, minor) {
         call("libgtk-4.so.1", "gdk_gl_context_set_required_version", [
             {
@@ -229,6 +417,21 @@ export class GLContext extends DrawContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Requests that GDK create an OpenGL ES context instead of an OpenGL one.
+     *
+     * Not all platforms support OpenGL ES.
+     *
+     * The `context` must not have been realized.
+     *
+     * By default, GDK will attempt to automatically detect whether the
+     * underlying GL implementation is OpenGL or OpenGL ES once the `context` is realized.
+     *
+     * You should check the return value of [method@Gdk.GLContext.get_use_es]
+     * after calling [method@Gdk.GLContext.realize] to decide whether to use
+     * the OpenGL or OpenGL ES API, extensions, or shaders.
+     * @param useEs - whether the context should use OpenGL ES instead of OpenGL,
+     */
     setUseEs(useEs) {
         call("libgtk-4.so.1", "gdk_gl_context_set_use_es", [
             {