@defold-typescript/types 0.38.0 → 0.39.0

package/generated/render.d.ts

@@ -9,6 +9,7 @@ declare global {
     type constant_buffer = Opaque<"constant_buffer">;
     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;
     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" };
@@ -44,7 +45,7 @@ declare global {
      * render.clear(buffers);
      * ```
      */
-    function clear(buffers: LuaMap<number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }, number | Vector4>): void;
+    function clear(buffers: LuaMap<render.ClearBufferKey, number | Vector4>): void;
     /**
      * Constant buffers are used to set shader program variables and are optionally passed to the `render.draw()` function.
      * The buffer's constant elements can be indexed like an ordinary Lua table, but you can't iterate over them with pairs() or ipairs().
@@ -52,30 +53,38 @@ declare global {
      * @returns new constant buffer
      * @example
      * ```ts
-     * // 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);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
      *
-     * // 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);
+     *   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);
+     *   },
+     * });
      * ```
      */
     function constant_buffer(): Opaque<"constant_buffer">;
@@ -86,8 +95,16 @@ declare global {
      * @param render_target - render target to delete
      * @example
      * ```ts
-     * // How to delete a render target:
-     * render.delete_render_target(self.my_render_target);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_render_target: render.render_target("my_target", {}) };
+     *   },
+     *
+     *   final(self) {
+     *     // How to delete a render target:
+     *     render.delete_render_target(self.my_render_target);
+     *   },
+     * });
      * ```
      */
     function delete_render_target(render_target: Opaque<"render_target">): void;
@@ -98,10 +115,18 @@ declare global {
      *
      * @example
      * ```ts
-     * // Enable material named "glow", then draw my_pred with it.
-     * render.enable_material("glow");
-     * render.draw(self.my_pred);
-     * render.disable_material();
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable material named "glow", then draw my_pred with it.
+     *     render.enable_material("glow");
+     *     render.draw(self.my_pred);
+     *     render.disable_material();
+     *   },
+     * });
      * ```
      */
     function disable_material(): void;
@@ -123,19 +148,27 @@ declare global {
      * - `graphics.STATE_POLYGON_OFFSET_FILL`
      * @example
      * ```ts
-     * // Disable face culling when drawing the tile predicate:
-     * render.disable_state(graphics.STATE_CULL_FACE);
-     * render.draw(self.tile_pred);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { tile_pred: render.predicate([hash("tile")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Disable face culling when drawing the tile predicate:
+     *     render.disable_state(graphics.STATE_CULL_FACE);
+     *     render.draw(self.tile_pred);
+     *   },
+     * });
      * ```
      */
-    function disable_state(state: number & { readonly __brand: "graphics.STATE_DEPTH_TEST" } | number & { readonly __brand: "graphics.STATE_STENCIL_TEST" } | number & { readonly __brand: "graphics.STATE_BLEND" } | number & { readonly __brand: "graphics.STATE_ALPHA_TEST" } | number & { readonly __brand: "graphics.STATE_CULL_FACE" } | number & { readonly __brand: "graphics.STATE_POLYGON_OFFSET_FILL" }): void;
+    function disable_state(state: graphics.State): void;
     /**
      * Disables a texture that has previourly been enabled.
      *
      * @param binding - texture binding, either by texture unit, string or hash that should be disabled
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT);
      *     // draw a predicate with the render target available as texture 0 in the predicate
@@ -164,7 +197,7 @@ declare global {
      * constant_buffer optional constants to use while rendering
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     const color_params = {
      *       format: graphics.TEXTURE_FORMAT_RGBA,
@@ -216,7 +249,7 @@ declare global {
      * int How to sort draw order for world-ordered entries. Default uses the renderer's preferred world sorting (back-to-front).
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     // define a predicate matching anything with material tag "my_tag"
      *     return { my_pred: render.predicate([hash("my_tag")]) };
@@ -225,21 +258,21 @@ declare global {
      *   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 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 (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 });
+     *     // 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 });
+     *   },
+     * });
      * ```
      */
     function draw(predicate: number, options?: { frustum?: Matrix4; frustum_planes?: number; constants?: Opaque<"constant_buffer">; sort_order?: number }): void;
@@ -258,7 +291,7 @@ declare global {
      * - render.FRUSTUM_PLANES_ALL : All sides of the frustum.
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     // draw debug visualization
      *     render.draw_debug3d();
@@ -276,10 +309,18 @@ declare global {
      * @param material_id - material id to enable
      * @example
      * ```ts
-     * // Enable material named "glow", then draw my_pred with it.
-     * render.enable_material("glow");
-     * render.draw(self.my_pred);
-     * render.disable_material();
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable material named "glow", then draw my_pred with it.
+     *     render.enable_material("glow");
+     *     render.draw(self.my_pred);
+     *     render.disable_material();
+     *   },
+     * });
      * ```
      */
     function enable_material(material_id: string | Hash): void;
@@ -301,13 +342,21 @@ declare global {
      * - `graphics.STATE_POLYGON_OFFSET_FILL`
      * @example
      * ```ts
-     * // Enable stencil test when drawing the gui predicate, then disable it:
-     * render.enable_state(graphics.STATE_STENCIL_TEST);
-     * render.draw(self.gui_pred);
-     * render.disable_state(graphics.STATE_STENCIL_TEST);
+     * export default defineRenderScript({
+     *   init() {
+     *     return { gui_pred: render.predicate([hash("gui")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable stencil test when drawing the gui predicate, then disable it:
+     *     render.enable_state(graphics.STATE_STENCIL_TEST);
+     *     render.draw(self.gui_pred);
+     *     render.disable_state(graphics.STATE_STENCIL_TEST);
+     *   },
+     * });
      * ```
      */
-    function enable_state(state: number & { readonly __brand: "graphics.STATE_DEPTH_TEST" } | number & { readonly __brand: "graphics.STATE_STENCIL_TEST" } | number & { readonly __brand: "graphics.STATE_BLEND" } | number & { readonly __brand: "graphics.STATE_ALPHA_TEST" } | number & { readonly __brand: "graphics.STATE_CULL_FACE" } | number & { readonly __brand: "graphics.STATE_POLYGON_OFFSET_FILL" }): void;
+    function enable_state(state: graphics.State): void;
     /**
      * Sets the specified texture handle for a render target attachment or a regular texture
      * that should be used for rendering. The texture can be bound to either a texture unit
@@ -345,7 +394,7 @@ declare global {
      * - `graphics.BUFFER_TYPE_COLOR3_BIT`
      * @example
      * ```ts
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     // enable target so all drawing is done to it
      *     render.set_render_target(self.my_render_target);
@@ -362,9 +411,11 @@ declare global {
      *     render.draw(self.my_pred);
      *   },
      * });
-     *
+     * ```
+     * @example
+     * ```ts
      * // Or enable a render target by resource id:
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     render.set_render_target("my_rt_resource");
      *     render.draw(self.my_pred);
@@ -376,9 +427,11 @@ declare global {
      *     render.draw(self.my_pred);
      *   },
      * });
-     *
+     * ```
+     * @example
+     * ```ts
      * // Or bind a texture handle directly:
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     // bind a texture to the texture unit 0
      *     render.enable_texture(0, self.my_texture_handle);
@@ -388,7 +441,7 @@ declare global {
      * });
      * ```
      */
-    function enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash, buffer_type?: number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR1_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR2_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR3_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }): void;
+    function enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash, buffer_type?: graphics.BufferType): void;
     /**
      * Returns the logical window height that is set in the "game.project" settings.
      * Note that the actual window pixel size can change, either by device constraints
@@ -416,13 +469,35 @@ declare global {
      * @returns the height of the render target buffer texture
      * @example
      * ```ts
-     * // get the height of the render target color buffer
-     * const h = render.get_render_target_height(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
-     * // get the height of a render target resource
-     * const w = render.get_render_target_height("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     * export default defineRenderScript({
+     *   init() {
+     *     // render target buffer parameters
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       width: render.get_window_width(),
+     *       height: render.get_window_height(),
+     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *     };
+     *     return {
+     *       target_right: render.render_target("right", {
+     *         [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
+     *       }),
+     *     };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // get the height of the render target color buffer
+     *     const h = render.get_render_target_height(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
+     *     // get the height of a render target resource
+     *     const w = render.get_render_target_height("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     *   },
+     * });
      * ```
      */
-    function get_render_target_height(render_target: Opaque<"render_target">, buffer_type: number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR1_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR2_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR3_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }): number;
+    function get_render_target_height(render_target: Opaque<"render_target">, buffer_type: graphics.BufferType): number;
     /**
      * Returns the specified buffer width from a render target.
      *
@@ -439,13 +514,35 @@ declare global {
      * @returns the width of the render target buffer texture
      * @example
      * ```ts
-     * // get the width of the render target color buffer
-     * const w = render.get_render_target_width(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
-     * // get the width of a render target resource
-     * const w2 = render.get_render_target_width("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     * export default defineRenderScript({
+     *   init() {
+     *     // render target buffer parameters
+     *     const color_params = {
+     *       format: graphics.TEXTURE_FORMAT_RGBA,
+     *       width: render.get_window_width(),
+     *       height: render.get_window_height(),
+     *       min_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       mag_filter: graphics.TEXTURE_FILTER_LINEAR,
+     *       u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *       v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
+     *     };
+     *     return {
+     *       target_right: render.render_target("right", {
+     *         [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
+     *       }),
+     *     };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // get the width of the render target color buffer
+     *     const w = render.get_render_target_width(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
+     *     // get the width of a render target resource
+     *     const w2 = render.get_render_target_width("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
+     *   },
+     * });
      * ```
      */
-    function get_render_target_width(render_target: Opaque<"render_target">, buffer_type: number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR0_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR1_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR2_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_COLOR3_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_DEPTH_BIT" } | number & { readonly __brand: "graphics.BUFFER_TYPE_STENCIL_BIT" }): number;
+    function get_render_target_width(render_target: Opaque<"render_target">, buffer_type: graphics.BufferType): number;
     /**
      * Returns the logical window width that is set in the "game.project" settings.
      * Note that the actual window pixel size can change, either by device constraints
@@ -629,17 +726,25 @@ declare global {
      * boolean If true, the renderer will use the cameras view-projection matrix for frustum culling (default: false)
      * @example
      * ```ts
-     * // 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();
+     * 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 set_camera(camera?: Url | number, options?: { use_frustum?: boolean }): void;
@@ -666,11 +771,19 @@ declare global {
      * @param compute - compute id to use, or nil to disable
      * @example
      * ```ts
-     * // Enable compute program named "fractals", then dispatch it.
-     * render.set_compute("fractals");
-     * render.enable_texture(0, self.backing_texture);
-     * render.dispatch_compute(128, 128, 1);
-     * render.set_compute();
+     * export default defineRenderScript({
+     *   init() {
+     *     return { backing_texture: "my_texture_resource" };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Enable compute program named "fractals", then dispatch it.
+     *     render.set_compute("fractals");
+     *     render.enable_texture(0, self.backing_texture);
+     *     render.dispatch_compute(128, 128, 1);
+     *     render.set_compute();
+     *   },
+     * });
      * ```
      */
     function set_compute(compute?: string | Hash): void;
@@ -760,7 +873,7 @@ declare global {
      * ```ts
      * // Set listener and handle render context events.
      * // custom.render_script
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     render.set_listener((self, event_type) => {
      *       if (event_type === render.CONTEXT_EVENT_CONTEXT_LOST) {
@@ -833,10 +946,12 @@ declare global {
      *
      * - `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
+     * The render target defines the depth/stencil buffers as transient, when set_render_target is called the next time the buffers may be invalidated and allow for optimisations depending on driver support
      * ```ts
      * // How to set a render target and draw to it and then switch back to the default render target
      * // The render target defines the depth/stencil buffers as transient, when set_render_target is called the next time the buffers may be invalidated and allow for optimisations depending on driver support
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     // set render target so all drawing is done to it
      *     render.set_render_target(self.my_render_target, {
@@ -851,9 +966,11 @@ declare global {
      *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
      *   },
      * });
-     *
+     * ```
+     * @example
+     * ```ts
      * // Or set the render target by a render target resource identifier:
-     * export default defineScript({
+     * export default defineRenderScript({
      *   update(self, dt) {
      *     render.set_render_target("my_rt_resource");
      *
@@ -876,9 +993,17 @@ declare global {
      * @param height - new render target height
      * @example
      * ```ts
-     * // Resize render targets to the current window size:
-     * render.set_render_target_size(self.my_render_target, render.get_window_width(), render.get_window_height());
-     * render.set_render_target_size("my_rt_resource", render.get_window_width(), render.get_window_height());
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_render_target: render.render_target("my_target", {}) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // Resize render targets to the current window size:
+     *     render.set_render_target_size(self.my_render_target, render.get_window_width(), render.get_window_height());
+     *     render.set_render_target_size("my_rt_resource", render.get_window_width(), render.get_window_height());
+     *   },
+     * });
      * ```
      */
     function set_render_target_size(render_target: Opaque<"render_target">, width: number, height: number): void;
@@ -992,7 +1117,7 @@ declare global {
      * ```ts
      * // How to set the view and projection matrices according to
      * // the values supplied by a camera.
-     * export default defineScript({
+     * export default defineRenderScript({
      *   init() {
      *     return {
      *       view: vmath.matrix4(),