@defold-typescript/types 0.40.0 → 0.41.0

package/generated/versions/defold-1.12.4/render.d.ts

@@ -18,9 +18,17 @@ declare global {
     type render_target = Opaque<"render_target">;
     type texture = Opaque<"texture">;
     type ClearBufferKey = typeof graphics.BUFFER_TYPE_COLOR0_BIT | typeof graphics.BUFFER_TYPE_DEPTH_BIT | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
+    /**
+     * The rendering context was lost. Rendering is paused and all graphics resources become invalid. Passed to the `render.set_listener` callback.
+     */
+    const CONTEXT_EVENT_CONTEXT_LOST: number & { readonly __brand: "render.CONTEXT_EVENT_CONTEXT_LOST" };
+    /**
+     * The rendering context was restored. Rendering is still paused and graphics resources are still invalid, but can be reloaded. Passed to the `render.set_listener` callback.
+     */
+    const CONTEXT_EVENT_CONTEXT_RESTORED: number & { readonly __brand: "render.CONTEXT_EVENT_CONTEXT_RESTORED" };
     const FRUSTUM_PLANES_ALL: number & { readonly __brand: "render.FRUSTUM_PLANES_ALL" };
     const FRUSTUM_PLANES_SIDES: number & { readonly __brand: "render.FRUSTUM_PLANES_SIDES" };
-    const RENDER_TARGET_DEFAULT: number & { readonly __brand: "render.RENDER_TARGET_DEFAULT" };
+    const RENDER_TARGET_DEFAULT: undefined;
     /**
      * Depth sort far-to-near (default; good for transparent passes).
      */
@@ -33,6 +41,10 @@ declare global {
      * No per-call sorting; draw entries in insertion order.
      */
     const SORT_NONE: number & { readonly __brand: "render.SORT_NONE" };
+    /**
+     * Render target buffer flag that samples a depth or stencil buffer as a texture, for `render.render_target`.
+     */
+    const TEXTURE_BIT: number & { readonly __brand: "render.TEXTURE_BIT" };
     /**
      * Clear buffers in the currently enabled render target with specified value. If the render target has been created with multiple
      * color attachments, all buffers will be cleared with the same value.
@@ -40,9 +52,7 @@ declare global {
      * @param buffers - table with keys specifying which buffers to clear and values set to clear values. Available keys are:
      *
      * - `graphics.BUFFER_TYPE_COLOR0_BIT`
-     *
      * - `graphics.BUFFER_TYPE_DEPTH_BIT`
-     *
      * - `graphics.BUFFER_TYPE_STENCIL_BIT`
      * @example
      * ```ts
@@ -60,39 +70,41 @@ declare global {
      *
      * @returns new constant buffer
      * @example
+     * Set a "tint" constant in a constant buffer in the render script:
      * ```ts
-     * export default defineRenderScript({
-     *   init() {
-     *     return { my_pred: render.predicate([hash("my_tag")]) };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // Set a "tint" constant in a constant buffer in the render script:
-     *     const constants = render.constant_buffer();
-     *     constants.tint = vmath.vector4(1, 1, 1, 1);
-     *
-     *     // Then use the constant buffer when drawing a predicate:
-     *     render.draw(self.my_pred, { constants });
-     *
-     *     // The constant buffer also supports array values by specifying constants in an array:
-     *     const constants2 = render.constant_buffer();
-     *     constants2.light_colors = [];
-     *     constants2.light_colors[0] = vmath.vector4(1, 0, 0, 1);
-     *     constants2.light_colors[1] = vmath.vector4(0, 1, 0, 1);
-     *     constants2.light_colors[2] = vmath.vector4(0, 0, 1, 1);
-     *
-     *     // You can also create the array by passing the vectors directly:
-     *     const constants3 = render.constant_buffer();
-     *     constants3.light_colors = [
-     *       vmath.vector4(1, 0, 0, 1),
-     *       vmath.vector4(0, 1, 0, 1),
-     *       vmath.vector4(0, 0, 1, 1),
-     *     ];
-     *
-     *     // Add more constants to the array
-     *     constants3.light_colors[3] = vmath.vector4(1, 1, 1, 1);
-     *   },
-     * });
+     * const constants = render.constant_buffer();
+     * constants.tint = vmath.vector4(1, 1, 1, 1);
+     * ```
+     * @example
+     * Then use the constant buffer when drawing a predicate:
+     * ```ts
+     * function draw_tinted(self: { my_pred: Opaque<"render_predicate"> }) {
+     *   const constants = render.constant_buffer();
+     *   constants.tint = vmath.vector4(1, 1, 1, 1);
+     *   render.draw(self.my_pred, { constants });
+     * }
+     * ```
+     * @example
+     * The constant buffer also supports array values by specifying constants in a table:
+     * ```ts
+     * const constants = render.constant_buffer();
+     * constants.light_colors = [];
+     * constants.light_colors[0] = vmath.vector4(1, 0, 0, 1);
+     * constants.light_colors[1] = vmath.vector4(0, 1, 0, 1);
+     * constants.light_colors[2] = vmath.vector4(0, 0, 1, 1);
+     * ```
+     * @example
+     * You can also create the table by passing the vectors directly when creating the table:
+     * ```ts
+     * const constants = render.constant_buffer();
+     * constants.light_colors = [
+     *   vmath.vector4(1, 0, 0, 1),
+     *   vmath.vector4(0, 1, 0, 1),
+     *   vmath.vector4(0, 0, 1, 1),
+     * ];
+     *
+     * // Add more constants to the array
+     * constants.light_colors[3] = vmath.vector4(1, 1, 1, 1);
      * ```
      */
     function constant_buffer(): Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] };
@@ -144,15 +156,10 @@ declare global {
      * @param state - state to disable
      *
      * - `graphics.STATE_DEPTH_TEST`
-     *
      * - `graphics.STATE_STENCIL_TEST`
-     *
      * - `graphics.STATE_BLEND`
-     *
      * - `graphics.STATE_ALPHA_TEST` ( not available on iOS and Android)
-     *
      * - `graphics.STATE_CULL_FACE`
-     *
      * - `graphics.STATE_POLYGON_OFFSET_FILL`
      * @example
      * ```ts
@@ -238,8 +245,10 @@ declare global {
      *     render.set_compute();
      *   },
      * });
-     *
-     * // Dispatch a compute program with a constant buffer:
+     * ```
+     * @example
+     * Dispatch a compute program with a constant buffer:
+     * ```ts
      * const constants = render.constant_buffer();
      * constants.tint = vmath.vector4(1, 1, 1, 1);
      * render.dispatch_compute(32, 32, 32, { constants });
@@ -261,7 +270,6 @@ declare global {
      * int Determines which sides of the frustum will be used. Default is render.FRUSTUM_PLANES_SIDES.
      *
      * - render.FRUSTUM_PLANES_SIDES : The left, right, top and bottom sides of the frustum.
-     *
      * - render.FRUSTUM_PLANES_ALL : All 6 sides of the frustum.
      *
      * `constants`
@@ -272,35 +280,43 @@ declare global {
      * ```ts
      * export default defineRenderScript({
      *   init() {
-     *     return {
-     *       // define a predicate matching anything with material tag "my_tag"
-     *       my_pred: render.predicate([hash("my_tag")]),
-     *       proj: vmath.matrix4_perspective(math.rad(45), render.get_window_width() / render.get_window_height(), 0.1, 1000),
-     *       view: vmath.matrix4_look_at(vmath.vector3(0, 0, 10), vmath.vector3(0, 0, 0), vmath.vector3(0, 1, 0)),
-     *     };
+     *     // define a predicate matching anything with material tag "my_tag"
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
      *   },
      *
      *   update(self, dt) {
      *     // draw everything in the my_pred predicate
      *     render.draw(self.my_pred);
-     *
-     *     // Draw predicate with constants:
-     *     const constants = render.constant_buffer();
-     *     constants.tint = vmath.vector4(1, 1, 1, 1);
-     *     render.draw(self.my_pred, { constants });
-     *
-     *     // Draw with predicate and frustum culling (without near+far planes):
-     *     const frustum = self.proj.mul(self.view);
-     *     render.draw(self.my_pred, { frustum });
-     *
-     *     // Draw with predicate and frustum culling (with near+far planes):
-     *     const frustum2 = self.proj.mul(self.view);
-     *     render.draw(self.my_pred, { frustum: frustum2, frustum_planes: render.FRUSTUM_PLANES_ALL });
      *   },
      * });
      * ```
+     * @example
+     * Draw predicate with constants:
+     * ```ts
+     * function draw_tinted(self: { my_pred: Opaque<"render_predicate"> }) {
+     *   const constants = render.constant_buffer();
+     *   constants.tint = vmath.vector4(1, 1, 1, 1);
+     *   render.draw(self.my_pred, { constants });
+     * }
+     * ```
+     * @example
+     * Draw with predicate and frustum culling (without near+far planes):
+     * ```ts
+     * function draw_culled(self: { my_pred: Opaque<"render_predicate">; proj: Matrix4; view: Matrix4 }) {
+     *   const frustum = self.proj.mul(self.view);
+     *   render.draw(self.my_pred, { frustum });
+     * }
+     * ```
+     * @example
+     * Draw with predicate and frustum culling (with near+far planes):
+     * ```ts
+     * function draw_culled(self: { my_pred: Opaque<"render_predicate">; proj: Matrix4; view: Matrix4 }) {
+     *   const frustum = self.proj.mul(self.view);
+     *   render.draw(self.my_pred, { frustum, frustum_planes: render.FRUSTUM_PLANES_ALL });
+     * }
+     * ```
      */
-    function draw(predicate: number, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }; sort_order?: number }): void;
+    function draw(predicate: Opaque<"render_predicate">, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | Vector4[] | Matrix4[] }; sort_order?: number }): void;
     /**
      * Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.
      *
@@ -312,7 +328,6 @@ declare global {
      * int Determines which sides of the frustum will be used. Default is render.FRUSTUM_PLANES_SIDES.
      *
      * - render.FRUSTUM_PLANES_SIDES : The left, right, top and bottom sides of the frustum.
-     *
      * - render.FRUSTUM_PLANES_ALL : All sides of the frustum.
      * @example
      * ```ts
@@ -355,15 +370,10 @@ declare global {
      * @param state - state to enable
      *
      * - `graphics.STATE_DEPTH_TEST`
-     *
      * - `graphics.STATE_STENCIL_TEST`
-     *
      * - `graphics.STATE_BLEND`
-     *
      * - `graphics.STATE_ALPHA_TEST` ( not available on iOS and Android)
-     *
      * - `graphics.STATE_CULL_FACE`
-     *
      * - `graphics.STATE_POLYGON_OFFSET_FILL`
      * @example
      * ```ts
@@ -404,18 +414,14 @@ declare global {
      * If The render target has been created as depth and/or stencil textures, these buffer types can be used:
      *
      * - `graphics.BUFFER_TYPE_DEPTH_BIT`
-     *
      * - `graphics.BUFFER_TYPE_STENCIL_BIT`
      *
      * If the render target has been created with multiple color attachments, these buffer types can be used
      * to enable those textures as well. Currently 4 color attachments are supported:
      *
      * - `graphics.BUFFER_TYPE_COLOR0_BIT`
-     *
      * - `graphics.BUFFER_TYPE_COLOR1_BIT`
-     *
      * - `graphics.BUFFER_TYPE_COLOR2_BIT`
-     *
      * - `graphics.BUFFER_TYPE_COLOR3_BIT`
      * @example
      * ```ts
@@ -507,9 +513,7 @@ declare global {
      * @param buffer_type - which type of buffer to retrieve the height from
      *
      * - `graphics.BUFFER_TYPE_COLOR0_BIT`
-     *
      * - `graphics.BUFFER_TYPE_DEPTH_BIT`
-     *
      * - `graphics.BUFFER_TYPE_STENCIL_BIT`
      * @returns the height of the render target buffer texture
      * @example
@@ -550,11 +554,8 @@ declare global {
      * @param buffer_type - which type of buffer to retrieve the width from
      *
      * - `graphics.BUFFER_TYPE_COLOR0_BIT`
-     *
      * - `graphics.BUFFER_TYPE_COLOR[x]_BIT` (x: [0..3], if supported!)
-     *
      * - `graphics.BUFFER_TYPE_DEPTH_BIT`
-     *
      * - `graphics.BUFFER_TYPE_STENCIL_BIT`
      * @returns the width of the render target buffer texture
      * @example
@@ -643,7 +644,7 @@ declare global {
      * const p = render.predicate([hash("opaque"), hash("smoke")]);
      * ```
      */
-    function predicate(tags: (string | Hash)[]): number;
+    function predicate(tags: (string | Hash)[]): Opaque<"render_predicate">;
     /**
      * Specifies the arithmetic used when computing pixel values that are written to the frame
      * buffer. In RGBA mode, pixels can be drawn using a function that blends the source RGBA
@@ -711,11 +712,8 @@ declare global {
      * The blended RGBA values of a pixel comes from the following equations:
      *
      * - Rd = min(kR, Rs * sR + Rd * dR)
-     *
      * - Gd = min(kG, Gs * sG + Gd * dG)
-     *
      * - Bd = min(kB, Bs * sB + Bd * dB)
-     *
      * - Ad = min(kA, As * sA + Ad * dA)
      *
      * Blend function `(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA)` is useful for
@@ -746,29 +744,27 @@ declare global {
      * `use_frustum`
      * boolean If true, the renderer will use the cameras view-projection matrix for frustum culling (default: false)
      * @example
+     * Set the current camera to be used for rendering
      * ```ts
-     * export default defineRenderScript({
-     *   init() {
-     *     return { my_pred: render.predicate([hash("my_tag")]) };
-     *   },
-     *
-     *   update(self, dt) {
-     *     // Set the current camera to be used for rendering
-     *     render.set_camera("main:/my_go#camera");
-     *     render.draw(self.my_pred);
-     *     render.set_camera(undefined);
-     *
-     *     // Use the camera frustum for frustum culling together with a specific frustum plane option for the draw command
-     *     // The camera frustum will take precedence over the frustum plane option in render.draw
-     *     render.set_camera("main:/my_go#camera", { use_frustum: true });
-     *     // However, we can still customize the frustum planes regardless of the camera option!
-     *     render.draw(self.my_pred, { frustum_planes: render.FRUSTUM_PLANES_ALL });
-     *     render.set_camera();
-     *   },
-     * });
+     * function draw_through_camera(self: { my_pred: Opaque<"render_predicate"> }) {
+     *   render.set_camera("main:/my_go#camera");
+     *   render.draw(self.my_pred);
+     *   render.set_camera(undefined);
+     * }
+     * ```
+     * @example
+     * Use the camera frustum for frustum culling together with a specific frustum plane option for the draw command
+     * ```ts
+     * function draw_through_camera(self: { my_pred: Opaque<"render_predicate"> }) {
+     *   // The camera frustum will take precedence over the frustum plane option in render.draw
+     *   render.set_camera("main:/my_go#camera", { use_frustum: true });
+     *   // However, we can still customize the frustum planes regardless of the camera option!
+     *   render.draw(self.my_pred, { frustum_planes: render.FRUSTUM_PLANES_ALL });
+     *   render.set_camera();
+     * }
      * ```
      */
-    function set_camera(camera?: Url | number | string, options?: { use_frustum?: boolean }): void;
+    function set_camera(camera?: Url | number | string | Hash, options?: { use_frustum?: boolean }): void;
     /**
      * Specifies whether the individual color components in the frame buffer is enabled for writing (`true`) or disabled (`false`). For example, if `blue` is `false`, nothing is written to the blue component of any pixel in any of the color buffers, regardless of the drawing operation attempted. Note that writing are either enabled or disabled for entire color components, not the individual bits of a component.
      * The component masks are all initially `true`.
@@ -818,9 +814,7 @@ declare global {
      * @param face_type - face type
      *
      * - `graphics.FACE_TYPE_FRONT`
-     *
      * - `graphics.FACE_TYPE_BACK`
-     *
      * - `graphics.FACE_TYPE_FRONT_AND_BACK`
      * @example
      * ```ts
@@ -838,19 +832,12 @@ declare global {
      * Function constants:
      *
      * - `graphics.COMPARE_FUNC_NEVER` (never passes)
-     *
      * - `graphics.COMPARE_FUNC_LESS` (passes if the incoming depth value is less than the stored value)
-     *
      * - `graphics.COMPARE_FUNC_LEQUAL` (passes if the incoming depth value is less than or equal to the stored value)
-     *
      * - `graphics.COMPARE_FUNC_GREATER` (passes if the incoming depth value is greater than the stored value)
-     *
      * - `graphics.COMPARE_FUNC_GEQUAL` (passes if the incoming depth value is greater than or equal to the stored value)
-     *
      * - `graphics.COMPARE_FUNC_EQUAL` (passes if the incoming depth value is equal to the stored value)
-     *
      * - `graphics.COMPARE_FUNC_NOTEQUAL` (passes if the incoming depth value is not equal to the stored value)
-     *
      * - `graphics.COMPARE_FUNC_ALWAYS` (always passes)
      *
      * The depth function is initially set to `graphics.COMPARE_FUNC_LESS`.
@@ -962,9 +949,7 @@ declare global {
      * A buffer type defined that doesn't exist in the render target is silently ignored.
      *
      * - `graphics.BUFFER_TYPE_COLOR0_BIT`
-     *
      * - `graphics.BUFFER_TYPE_DEPTH_BIT`
-     *
      * - `graphics.BUFFER_TYPE_STENCIL_BIT`
      * @example
      * How to set a render target and draw to it and then switch back to the default render target
@@ -1020,7 +1005,7 @@ declare global {
      * });
      * ```
      */
-    function set_render_target(render_target: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT, options?: { transient?: graphics.BufferType[] }): void;
+    function set_render_target(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT, options?: { transient?: graphics.BufferType[] }): void;
     /**
      * Sets the render target size for a render target created from
      * either a render script, or from a render target resource.
@@ -1061,19 +1046,12 @@ declare global {
      * Function constant:
      *
      * - `graphics.COMPARE_FUNC_NEVER` (never passes)
-     *
      * - `graphics.COMPARE_FUNC_LESS` (passes if (ref & mask) < (stencil & mask))
-     *
      * - `graphics.COMPARE_FUNC_LEQUAL` (passes if (ref & mask) <= (stencil & mask))
-     *
      * - `graphics.COMPARE_FUNC_GREATER` (passes if (ref & mask) > (stencil & mask))
-     *
      * - `graphics.COMPARE_FUNC_GEQUAL` (passes if (ref & mask) >= (stencil & mask))
-     *
      * - `graphics.COMPARE_FUNC_EQUAL` (passes if (ref & mask) = (stencil & mask))
-     *
      * - `graphics.COMPARE_FUNC_NOTEQUAL` (passes if (ref & mask) != (stencil & mask))
-     *
      * - `graphics.COMPARE_FUNC_ALWAYS` (always passes)
      *
      * @param func - stencil test function, see the description for available values
@@ -1114,19 +1092,12 @@ declare global {
      * Operator constants:
      *
      * - `graphics.STENCIL_OP_KEEP` (keeps the current value)
-     *
      * - `graphics.STENCIL_OP_ZERO` (sets the stencil buffer value to 0)
-     *
      * - `graphics.STENCIL_OP_REPLACE` (sets the stencil buffer value to `ref`, as specified by render.set_stencil_func)
-     *
      * - `graphics.STENCIL_OP_INCR` (increments the stencil buffer value and clamp to the maximum representable unsigned value)
-     *
      * - `graphics.STENCIL_OP_INCR_WRAP` (increments the stencil buffer value and wrap to zero when incrementing the maximum representable unsigned value)
-     *
      * - `graphics.STENCIL_OP_DECR` (decrements the current stencil buffer value and clamp to 0)
-     *
      * - `graphics.STENCIL_OP_DECR_WRAP` (decrements the current stencil buffer value and wrap to the maximum representable unsigned value when decrementing zero)
-     *
      * - `graphics.STENCIL_OP_INVERT` (bitwise inverts the current stencil buffer value)
      *
      * `dppass` and `dpfail` specify the stencil buffer actions depending on whether subsequent