@gtkx/ffi 0.1.45 → 0.1.46

package/dist/gl/gl.js

@@ -1,8 +1,19 @@
+/**
+ * OpenGL function bindings via libGL.
+ * These wrap raw OpenGL calls for use in GtkGLArea render handlers.
+ */
 import { call, createRef } from "@gtkx/native";
 const LIB = "libGL.so.1";
+/**
+ * Clear buffers to preset values.
+ * @param mask - Bitwise OR of masks indicating buffers to clear (GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, etc.)
+ */
 export function glClear(mask) {
     call(LIB, "glClear", [{ type: { type: "int", size: 32, unsigned: true }, value: mask }], { type: "undefined" });
 }
+/**
+ * Specify clear values for the color buffers.
+ */
 export function glClearColor(red, green, blue, alpha) {
     call(LIB, "glClearColor", [
         { type: { type: "float", size: 32 }, value: red },
@@ -11,6 +22,9 @@ export function glClearColor(red, green, blue, alpha) {
         { type: { type: "float", size: 32 }, value: alpha },
     ], { type: "undefined" });
 }
+/**
+ * Set the viewport.
+ */
 export function glViewport(x, y, width, height) {
     call(LIB, "glViewport", [
         { type: { type: "int", size: 32, unsigned: false }, value: x },
@@ -19,18 +33,35 @@ export function glViewport(x, y, width, height) {
         { type: { type: "int", size: 32, unsigned: false }, value: height },
     ], { type: "undefined" });
 }
+/**
+ * Enable server-side GL capabilities.
+ */
 export function glEnable(cap) {
     call(LIB, "glEnable", [{ type: { type: "int", size: 32, unsigned: true }, value: cap }], { type: "undefined" });
 }
+/**
+ * Disable server-side GL capabilities.
+ */
 export function glDisable(cap) {
     call(LIB, "glDisable", [{ type: { type: "int", size: 32, unsigned: true }, value: cap }], { type: "undefined" });
 }
+/**
+ * Specify the clear value for the depth buffer.
+ */
 export function glClearDepth(depth) {
     call(LIB, "glClearDepth", [{ type: { type: "float", size: 64 }, value: depth }], { type: "undefined" });
 }
+/**
+ * Specify the value used for depth buffer comparisons.
+ */
 export function glDepthFunc(func) {
     call(LIB, "glDepthFunc", [{ type: { type: "int", size: 32, unsigned: true }, value: func }], { type: "undefined" });
 }
+/**
+ * Creates a shader object.
+ * @param type - GL_VERTEX_SHADER or GL_FRAGMENT_SHADER
+ * @returns Shader object ID
+ */
 export function glCreateShader(type) {
     return call(LIB, "glCreateShader", [{ type: { type: "int", size: 32, unsigned: true }, value: type }], {
         type: "int",
@@ -38,6 +69,10 @@ export function glCreateShader(type) {
         unsigned: true,
     });
 }
+/**
+ * Replaces the source code in a shader object.
+ * Note: This simplified version passes a single null-terminated string.
+ */
 export function glShaderSource(shader, source) {
     call(LIB, "glShaderSource", [
         { type: { type: "int", size: 32, unsigned: true }, value: shader },
@@ -46,11 +81,17 @@ export function glShaderSource(shader, source) {
         { type: { type: "int", size: 64, unsigned: true }, value: 0 },
     ], { type: "undefined" });
 }
+/**
+ * Compiles a shader object.
+ */
 export function glCompileShader(shader) {
     call(LIB, "glCompileShader", [{ type: { type: "int", size: 32, unsigned: true }, value: shader }], {
         type: "undefined",
     });
 }
+/**
+ * Returns a parameter from a shader object.
+ */
 export function glGetShaderiv(shader, pname) {
     const params = createRef(0);
     call(LIB, "glGetShaderiv", [
@@ -60,6 +101,9 @@ export function glGetShaderiv(shader, pname) {
     ], { type: "undefined" });
     return params.value;
 }
+/**
+ * Returns the information log for a shader object.
+ */
 export function glGetShaderInfoLog(shader, _maxLength) {
     const logLength = glGetShaderiv(shader, 0x8b84);
     if (logLength <= 0) {
@@ -67,30 +111,48 @@ export function glGetShaderInfoLog(shader, _maxLength) {
     }
     return `Shader info log length: ${logLength} (use console.error for details)`;
 }
+/**
+ * Deletes a shader object.
+ */
 export function glDeleteShader(shader) {
     call(LIB, "glDeleteShader", [{ type: { type: "int", size: 32, unsigned: true }, value: shader }], {
         type: "undefined",
     });
 }
+/**
+ * Creates a program object.
+ */
 export function glCreateProgram() {
     return call(LIB, "glCreateProgram", [], { type: "int", size: 32, unsigned: true });
 }
+/**
+ * Attaches a shader object to a program object.
+ */
 export function glAttachShader(program, shader) {
     call(LIB, "glAttachShader", [
         { type: { type: "int", size: 32, unsigned: true }, value: program },
         { type: { type: "int", size: 32, unsigned: true }, value: shader },
     ], { type: "undefined" });
 }
+/**
+ * Links a program object.
+ */
 export function glLinkProgram(program) {
     call(LIB, "glLinkProgram", [{ type: { type: "int", size: 32, unsigned: true }, value: program }], {
         type: "undefined",
     });
 }
+/**
+ * Installs a program object as part of current rendering state.
+ */
 export function glUseProgram(program) {
     call(LIB, "glUseProgram", [{ type: { type: "int", size: 32, unsigned: true }, value: program }], {
         type: "undefined",
     });
 }
+/**
+ * Returns a parameter from a program object.
+ */
 export function glGetProgramiv(program, pname) {
     const params = createRef(0);
     call(LIB, "glGetProgramiv", [
@@ -100,6 +162,9 @@ export function glGetProgramiv(program, pname) {
     ], { type: "undefined" });
     return params.value;
 }
+/**
+ * Returns the information log for a program object.
+ */
 export function glGetProgramInfoLog(program, _maxLength) {
     const logLength = glGetProgramiv(program, 0x8b84);
     if (logLength <= 0) {
@@ -107,23 +172,35 @@ export function glGetProgramInfoLog(program, _maxLength) {
     }
     return `Program info log length: ${logLength} (use console.error for details)`;
 }
+/**
+ * Deletes a program object.
+ */
 export function glDeleteProgram(program) {
     call(LIB, "glDeleteProgram", [{ type: { type: "int", size: 32, unsigned: true }, value: program }], {
         type: "undefined",
     });
 }
+/**
+ * Returns the location of a uniform variable.
+ */
 export function glGetUniformLocation(program, name) {
     return call(LIB, "glGetUniformLocation", [
         { type: { type: "int", size: 32, unsigned: true }, value: program },
         { type: { type: "string" }, value: name },
     ], { type: "int", size: 32, unsigned: false });
 }
+/**
+ * Specify the value of a uniform variable (1 float).
+ */
 export function glUniform1f(location, v0) {
     call(LIB, "glUniform1f", [
         { type: { type: "int", size: 32, unsigned: false }, value: location },
         { type: { type: "float", size: 32 }, value: v0 },
     ], { type: "undefined" });
 }
+/**
+ * Specify the value of a uniform variable (2 floats).
+ */
 export function glUniform2f(location, v0, v1) {
     call(LIB, "glUniform2f", [
         { type: { type: "int", size: 32, unsigned: false }, value: location },
@@ -131,6 +208,9 @@ export function glUniform2f(location, v0, v1) {
         { type: { type: "float", size: 32 }, value: v1 },
     ], { type: "undefined" });
 }
+/**
+ * Specify the value of a uniform variable (3 floats).
+ */
 export function glUniform3f(location, v0, v1, v2) {
     call(LIB, "glUniform3f", [
         { type: { type: "int", size: 32, unsigned: false }, value: location },
@@ -139,6 +219,9 @@ export function glUniform3f(location, v0, v1, v2) {
         { type: { type: "float", size: 32 }, value: v2 },
     ], { type: "undefined" });
 }
+/**
+ * Specify the value of a uniform variable (4 floats).
+ */
 export function glUniform4f(location, v0, v1, v2, v3) {
     call(LIB, "glUniform4f", [
         { type: { type: "int", size: 32, unsigned: false }, value: location },
@@ -148,12 +231,18 @@ export function glUniform4f(location, v0, v1, v2, v3) {
         { type: { type: "float", size: 32 }, value: v3 },
     ], { type: "undefined" });
 }
+/**
+ * Specify the value of a uniform variable (1 int).
+ */
 export function glUniform1i(location, v0) {
     call(LIB, "glUniform1i", [
         { type: { type: "int", size: 32, unsigned: false }, value: location },
         { type: { type: "int", size: 32, unsigned: false }, value: v0 },
     ], { type: "undefined" });
 }
+/**
+ * Specify the value of a 4x4 matrix uniform variable.
+ */
 export function glUniformMatrix4fv(location, count, transpose, value) {
     call(LIB, "glUniformMatrix4fv", [
         { type: { type: "int", size: 32, unsigned: false }, value: location },
@@ -162,6 +251,9 @@ export function glUniformMatrix4fv(location, count, transpose, value) {
         { type: { type: "array", itemType: { type: "float", size: 32 } }, value },
     ], { type: "undefined" });
 }
+/**
+ * Generate a single vertex array object name.
+ */
 export function glGenVertexArray() {
     const array = createRef(0);
     call(LIB, "glGenVertexArrays", [
@@ -170,17 +262,26 @@ export function glGenVertexArray() {
     ], { type: "undefined" });
     return array.value;
 }
+/**
+ * Bind a vertex array object.
+ */
 export function glBindVertexArray(array) {
     call(LIB, "glBindVertexArray", [{ type: { type: "int", size: 32, unsigned: true }, value: array }], {
         type: "undefined",
     });
 }
+/**
+ * Delete a vertex array object.
+ */
 export function glDeleteVertexArray(array) {
     call(LIB, "glDeleteVertexArrays", [
         { type: { type: "int", size: 32, unsigned: false }, value: 1 },
         { type: { type: "array", itemType: { type: "int", size: 32, unsigned: true } }, value: [array] },
     ], { type: "undefined" });
 }
+/**
+ * Generate a single buffer object name.
+ */
 export function glGenBuffer() {
     const buffer = createRef(0);
     call(LIB, "glGenBuffers", [
@@ -189,18 +290,30 @@ export function glGenBuffer() {
     ], { type: "undefined" });
     return buffer.value;
 }
+/**
+ * Bind a named buffer object.
+ */
 export function glBindBuffer(target, buffer) {
     call(LIB, "glBindBuffer", [
         { type: { type: "int", size: 32, unsigned: true }, value: target },
         { type: { type: "int", size: 32, unsigned: true }, value: buffer },
     ], { type: "undefined" });
 }
+/**
+ * Delete a buffer object.
+ */
 export function glDeleteBuffer(buffer) {
     call(LIB, "glDeleteBuffers", [
         { type: { type: "int", size: 32, unsigned: false }, value: 1 },
         { type: { type: "array", itemType: { type: "int", size: 32, unsigned: true } }, value: [buffer] },
     ], { type: "undefined" });
 }
+/**
+ * Creates and initializes a buffer object's data store.
+ * @param target - Buffer target (GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER, etc.)
+ * @param data - Array of float values
+ * @param usage - Usage hint (GL_STATIC_DRAW, GL_DYNAMIC_DRAW, etc.)
+ */
 export function glBufferData(target, data, usage) {
     const size = data.length * 4;
     call(LIB, "glBufferData", [
@@ -210,6 +323,9 @@ export function glBufferData(target, data, usage) {
         { type: { type: "int", size: 32, unsigned: true }, value: usage },
     ], { type: "undefined" });
 }
+/**
+ * Define an array of generic vertex attribute data.
+ */
 export function glVertexAttribPointer(index, size, type, normalized, stride, offset) {
     call(LIB, "glVertexAttribPointer", [
         { type: { type: "int", size: 32, unsigned: true }, value: index },
@@ -220,16 +336,25 @@ export function glVertexAttribPointer(index, size, type, normalized, stride, off
         { type: { type: "int", size: 64, unsigned: true }, value: offset },
     ], { type: "undefined" });
 }
+/**
+ * Enable a generic vertex attribute array.
+ */
 export function glEnableVertexAttribArray(index) {
     call(LIB, "glEnableVertexAttribArray", [{ type: { type: "int", size: 32, unsigned: true }, value: index }], {
         type: "undefined",
     });
 }
+/**
+ * Disable a generic vertex attribute array.
+ */
 export function glDisableVertexAttribArray(index) {
     call(LIB, "glDisableVertexAttribArray", [{ type: { type: "int", size: 32, unsigned: true }, value: index }], {
         type: "undefined",
     });
 }
+/**
+ * Render primitives from array data.
+ */
 export function glDrawArrays(mode, first, count) {
     call(LIB, "glDrawArrays", [
         { type: { type: "int", size: 32, unsigned: true }, value: mode },
@@ -237,6 +362,13 @@ export function glDrawArrays(mode, first, count) {
         { type: { type: "int", size: 32, unsigned: false }, value: count },
     ], { type: "undefined" });
 }
+/**
+ * Creates and initializes a buffer object's data store with unsigned short data.
+ * Use this for element/index buffers with GL_UNSIGNED_SHORT type.
+ * @param target - Buffer target (typically GL_ELEMENT_ARRAY_BUFFER)
+ * @param data - Array of unsigned short values (indices)
+ * @param usage - Usage hint (GL_STATIC_DRAW, GL_DYNAMIC_DRAW, etc.)
+ */
 export function glBufferDataUshort(target, data, usage) {
     const size = data.length * 2;
     call(LIB, "glBufferData", [
@@ -246,6 +378,9 @@ export function glBufferDataUshort(target, data, usage) {
         { type: { type: "int", size: 32, unsigned: true }, value: usage },
     ], { type: "undefined" });
 }
+/**
+ * Render primitives from array data with indices.
+ */
 export function glDrawElements(mode, count, type, offset) {
     call(LIB, "glDrawElements", [
         { type: { type: "int", size: 32, unsigned: true }, value: mode },
@@ -254,12 +389,18 @@ export function glDrawElements(mode, count, type, offset) {
         { type: { type: "int", size: 64, unsigned: true }, value: offset },
     ], { type: "undefined" });
 }
+/**
+ * Returns the location of an attribute variable.
+ */
 export function glGetAttribLocation(program, name) {
     return call(LIB, "glGetAttribLocation", [
         { type: { type: "int", size: 32, unsigned: true }, value: program },
         { type: { type: "string" }, value: name },
     ], { type: "int", size: 32, unsigned: false });
 }
+/**
+ * Associate a generic vertex attribute index with a named attribute variable.
+ */
 export function glBindAttribLocation(program, index, name) {
     call(LIB, "glBindAttribLocation", [
         { type: { type: "int", size: 32, unsigned: true }, value: program },
@@ -267,6 +408,9 @@ export function glBindAttribLocation(program, index, name) {
         { type: { type: "string" }, value: name },
     ], { type: "undefined" });
 }
+/**
+ * Return error information.
+ */
 export function glGetError() {
     return call(LIB, "glGetError", [], { type: "int", size: 32, unsigned: true });
 }

package/dist/gl/index.d.ts

@@ -1,2 +1,14 @@
+/**
+ * OpenGL bindings via libGL for use with GtkGLArea.
+ *
+ * Example usage:
+ * ```typescript
+ * import * as GL from "@gtkx/ffi/gl";
+ *
+ * // In a render handler:
+ * GL.glClearColor(0.5, 0.5, 0.5, 1.0);
+ * GL.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
+ * ```
+ */
 export * from "./constants.js";
 export * from "./gl.js";

package/dist/gl/index.js

@@ -1,2 +1,14 @@
+/**
+ * OpenGL bindings via libGL for use with GtkGLArea.
+ *
+ * Example usage:
+ * ```typescript
+ * import * as GL from "@gtkx/ffi/gl";
+ *
+ * // In a render handler:
+ * GL.glClearColor(0.5, 0.5, 0.5, 1.0);
+ * GL.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
+ * ```
+ */
 export * from "./constants.js";
 export * from "./gl.js";

package/dist/native-error.d.ts

@@ -1,6 +1,17 @@
+/**
+ * Error class that wraps a GLib GError.
+ * Extends the native JavaScript Error with GError-specific properties.
+ */
 export declare class NativeError extends Error {
+    /** The raw GError pointer */
     readonly ptr: unknown;
+    /** The GLib error domain (GQuark) */
     readonly domain: number;
+    /** The error code within the domain */
     readonly code: number;
+    /**
+     * Creates a NativeError from a GError pointer.
+     * @param ptr - The GError pointer from a failed FFI call
+     */
     constructor(ptr: unknown);
 }

package/dist/native-error.js

@@ -1,8 +1,19 @@
 import { read } from "@gtkx/native";
+/**
+ * Error class that wraps a GLib GError.
+ * Extends the native JavaScript Error with GError-specific properties.
+ */
 export class NativeError extends Error {
+    /** The raw GError pointer */
     ptr;
+    /** The GLib error domain (GQuark) */
     domain;
+    /** The error code within the domain */
     code;
+    /**
+     * Creates a NativeError from a GError pointer.
+     * @param ptr - The GError pointer from a failed FFI call
+     */
     constructor(ptr) {
         const message = read(ptr, { type: "string" }, 8);
         super(message ?? "Unknown error");

package/dist/native.d.ts

@@ -7,10 +7,39 @@ type NativeEventMap = {
     start: [];
     stop: [];
 };
+/**
+ * Event emitter for GTK lifecycle events.
+ * Emits "start" when GTK is initialized and "stop" before shutdown.
+ */
 export declare const events: EventEmitter<NativeEventMap>;
+/**
+ * Wraps a native pointer in a class instance without calling the constructor.
+ * Used when receiving pointers from FFI calls that need to be wrapped as TypeScript objects.
+ * @param ptr - The native pointer to wrap
+ * @param cls - The class whose prototype should be used
+ * @returns A new instance with the pointer attached
+ */
 export declare const getObject: <T extends object>(ptr: unknown, cls: {
     prototype: T;
 }) => T;
+/**
+ * Starts the GTK application with the given application ID.
+ * Sets up a keep-alive timer to prevent Node.js from exiting.
+ * This function is idempotent - calling it multiple times returns the existing app.
+ * @param appId - The application ID (e.g., "com.example.myapp")
+ * @param flags - Optional GIO application flags
+ * @returns The GTK Application instance
+ */
 export declare const start: (appId: string, flags?: ApplicationFlags) => Application;
+/**
+ * Gets the current GTK application instance.
+ * @returns The GTK Application instance
+ * @throws Error if GTK has not been started yet
+ */
 export declare const getCurrentApp: () => Application;
+/**
+ * Stops the GTK application and cleans up the keep-alive timer.
+ * Emits the "stop" event before shutting down to allow cleanup.
+ * This function is idempotent - calling it when not started does nothing.
+ */
 export declare const stop: () => void;

package/dist/native.js

@@ -4,7 +4,18 @@ export { createRef, getObjectId };
 import { Application } from "./generated/gtk/application.js";
 let currentApp = null;
 let keepAliveTimeout = null;
+/**
+ * Event emitter for GTK lifecycle events.
+ * Emits "start" when GTK is initialized and "stop" before shutdown.
+ */
 export const events = new EventEmitter();
+/**
+ * Wraps a native pointer in a class instance without calling the constructor.
+ * Used when receiving pointers from FFI calls that need to be wrapped as TypeScript objects.
+ * @param ptr - The native pointer to wrap
+ * @param cls - The class whose prototype should be used
+ * @returns A new instance with the pointer attached
+ */
 export const getObject = (ptr, cls) => {
     const instance = Object.create(cls.prototype);
     instance.ptr = ptr;
@@ -13,6 +24,14 @@ export const getObject = (ptr, cls) => {
 const keepAlive = () => {
     keepAliveTimeout = setTimeout(() => keepAlive(), 2147483647);
 };
+/**
+ * Starts the GTK application with the given application ID.
+ * Sets up a keep-alive timer to prevent Node.js from exiting.
+ * This function is idempotent - calling it multiple times returns the existing app.
+ * @param appId - The application ID (e.g., "com.example.myapp")
+ * @param flags - Optional GIO application flags
+ * @returns The GTK Application instance
+ */
 export const start = (appId, flags) => {
     if (currentApp) {
         return currentApp;
@@ -23,12 +42,22 @@ export const start = (appId, flags) => {
     keepAlive();
     return currentApp;
 };
+/**
+ * Gets the current GTK application instance.
+ * @returns The GTK Application instance
+ * @throws Error if GTK has not been started yet
+ */
 export const getCurrentApp = () => {
     if (!currentApp) {
         throw new Error("GTK application not initialized. Call start() first.");
     }
     return currentApp;
 };
+/**
+ * Stops the GTK application and cleans up the keep-alive timer.
+ * Emits the "stop" event before shutting down to allow cleanup.
+ * This function is idempotent - calling it when not started does nothing.
+ */
 export const stop = () => {
     if (!currentApp) {
         return;

package/dist/types.d.ts

@@ -4,6 +4,11 @@ type SignalParam = {
         prototype: object;
     };
 };
+/**
+ * Signal parameter metadata for type-safe signal connections.
+ * Used by generated connect methods to wrap signal handler arguments.
+ * @internal
+ */
 export type SignalMeta = Record<string, {
     params: SignalParam[];
     returnType?: import("@gtkx/native").Type;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/ffi",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "Generated TypeScript FFI bindings for GTK4 libraries",
   "keywords": [
     "gtk",
@@ -46,10 +46,10 @@
     "dist"
   ],
   "dependencies": {
-    "@gtkx/native": "0.1.45"
+    "@gtkx/native": "0.1.46"
   },
   "devDependencies": {
-    "@gtkx/gir": "0.1.45"
+    "@gtkx/gir": "0.1.46"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",