@defold-typescript/types 0.51.0 → 0.53.0

package/generated/render.d.ts

@@ -9,17 +9,17 @@ declare global {
     /**
      * Render-camera options
      */
-    interface camera_options {
+    interface CameraOptions {
       /**
        * Use the camera view-projection matrix for frustum culling. The default is false.
        */
       use_frustum?: boolean;
     }
-    type constant_buffer = Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> };
+    type ConstantBuffer = Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> };
     /**
      * Debug-draw options
      */
-    interface debug_draw_options {
+    interface DebugDrawOptions {
       /**
        * Frustum matrix used for culling renderable items.
        */
@@ -27,12 +27,12 @@ declare global {
       /**
        * Frustum planes used for culling. The default is render.FRUSTUM_PLANES_SIDES.
        */
-      frustum_planes?: render.FRUSTUM_PLANES;
+      frustum_planes?: render.FrustumPlanes;
     }
     /**
      * Compute-dispatch options
      */
-    interface dispatch_options {
+    interface DispatchOptions {
       /**
        * Constants used by the compute program. The values are copied when `render.dispatch_compute()` is called.
        */
@@ -41,7 +41,7 @@ declare global {
     /**
      * Render draw options
      */
-    interface draw_options {
+    interface DrawOptions {
       /**
        * Frustum matrix used for culling renderable items.
        */
@@ -49,7 +49,7 @@ declare global {
       /**
        * Frustum planes used for culling. The default is render.FRUSTUM_PLANES_SIDES.
        */
-      frustum_planes?: render.FRUSTUM_PLANES;
+      frustum_planes?: render.FrustumPlanes;
       /**
        * Constants used while rendering. The values are copied when `render.draw()` is called.
        */
@@ -57,18 +57,18 @@ declare global {
       /**
        * World-entry sort order. The default is the renderer's preferred back-to-front order.
        */
-      sort_order?: render.SORT;
+      sort_order?: render.Sort;
     }
-    type render_predicate = number;
-    type render_target = Opaque<"render_target">;
+    type RenderPredicate = Opaque<"render_predicate">;
+    type RenderTarget = Opaque<"render_target">;
     /**
      * Render-target attachment parameters
      */
-    interface render_target_buffer_params {
+    interface RenderTargetBufferParams {
       /**
        * Attachment texture format.
        */
-      format: graphics.TEXTURE_FORMAT;
+      format: graphics.TextureFormat;
       /**
        * Attachment width.
        */
@@ -80,49 +80,49 @@ declare global {
       /**
        * Minification filter.
        */
-      min_filter?: graphics.TEXTURE_FILTER;
+      min_filter?: graphics.TextureFilter;
       /**
        * Magnification filter.
        */
-      mag_filter?: graphics.TEXTURE_FILTER;
+      mag_filter?: graphics.TextureFilter;
       /**
        * Horizontal wrap mode.
        */
-      u_wrap?: graphics.TEXTURE_WRAP;
+      u_wrap?: graphics.TextureWrap;
       /**
        * Vertical wrap mode.
        */
-      v_wrap?: graphics.TEXTURE_WRAP;
+      v_wrap?: graphics.TextureWrap;
       /**
        * Depth wrap mode.
        */
-      w_wrap?: graphics.TEXTURE_WRAP;
+      w_wrap?: graphics.TextureWrap;
       /**
        * Attachment creation flags, applicable only to depth and stencil buffers.
        */
-      flags?: render.RENDER_TARGET_FLAG | number;
+      flags?: render.RenderTargetFlag | number;
     }
-    type render_target_params = { type?: graphics.TEXTURE_TYPE; sample_count?: number } & { [key: number]: render.render_target_buffer_params };
+    type RenderTargetParams = { type?: render.RenderTargetTextureType; sample_count?: number } & { [key: number]: render.RenderTargetBufferParams };
     /**
      * Render-target activation options
      */
-    interface set_render_target_options {
+    interface SetRenderTargetOptions {
       /**
        * Buffers whose contents become undefined after the target is deactivated. Missing buffers are ignored; combined depth-stencil buffers remain non-transient unless both are selected.
        */
-      transient?: graphics.BUFFER_TYPE[];
+      transient?: graphics.BufferType[];
       /**
        * Cubemap face selected for rendering. Valid only for cubemap render targets.
        */
-      face?: graphics.CUBEMAP_FACE;
+      face?: graphics.CubemapFace;
     }
-    type texture = Opaque<"texture">;
+    type Texture = Opaque<"texture">;
     type ClearBufferKey = typeof graphics.BUFFER_TYPE_COLOR0_BIT | typeof graphics.BUFFER_TYPE_DEPTH_BIT | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
-    type RenderTargetParams = render.render_target_params;
-    type CONTEXT_EVENT = typeof render.CONTEXT_EVENT_CONTEXT_LOST | typeof render.CONTEXT_EVENT_CONTEXT_RESTORED;
-    type FRUSTUM_PLANES = typeof render.FRUSTUM_PLANES_ALL | typeof render.FRUSTUM_PLANES_SIDES;
-    type RENDER_TARGET_FLAG = typeof render.TEXTURE_BIT;
-    type SORT = typeof render.SORT_BACK_TO_FRONT | typeof render.SORT_FRONT_TO_BACK | typeof render.SORT_NONE;
+    type RenderTargetTextureType = typeof graphics.TEXTURE_TYPE_2D | typeof graphics.TEXTURE_TYPE_CUBE_MAP;
+    type ContextEvent = typeof render.CONTEXT_EVENT_CONTEXT_LOST | typeof render.CONTEXT_EVENT_CONTEXT_RESTORED;
+    type FrustumPlanes = typeof render.FRUSTUM_PLANES_ALL | typeof render.FRUSTUM_PLANES_SIDES;
+    type RenderTargetFlag = typeof render.TEXTURE_BIT;
+    type Sort = typeof render.SORT_BACK_TO_FRONT | typeof render.SORT_FRONT_TO_BACK | typeof render.SORT_NONE;
     /**
      * rendering context was lost; rendering pauses and graphics resources become invalid
      */
@@ -295,7 +295,7 @@ declare global {
      * });
      * ```
      */
-    function disable_state(state: graphics.STATE): void;
+    function disable_state(state: Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>): void;
     /**
      * Disables a texture that has previourly been enabled.
      *
@@ -330,7 +330,7 @@ declare global {
      * });
      * ```
      */
-    function disable_texture(binding: Opaque<"texture"> | string | Hash | number): void;
+    function disable_texture(binding: string | Hash | number): void;
     /**
      * Dispatches the currently enabled compute program. The dispatch call takes three arguments x,y,z which constitutes
      * the 'global working group' of the compute dispatch. Together with the 'local working group' specified in the compute shader
@@ -378,7 +378,7 @@ declare global {
      * render.dispatch_compute(32, 32, 32, { constants });
      * ```
      */
-    function dispatch_compute(x: number, y: number, z: number, options?: render.dispatch_options): void;
+    function dispatch_compute(x: number, y: number, z: number, options?: render.DispatchOptions): void;
     /**
      * Draws all objects that match a specified predicate. An optional constant buffer can be
      * provided to override the default constants. If no constants buffer is provided, a default
@@ -427,7 +427,56 @@ declare global {
      * }
      * ```
      */
-    function draw(predicate: Opaque<"render_predicate">, options?: render.draw_options): void;
+    function draw(predicate: Opaque<"render_predicate">): void;
+    /**
+     * Draws all objects that match a specified predicate. An optional constant buffer can be
+     * provided to override the default constants. If no constants buffer is provided, a default
+     * system constants buffer is used containing constants as defined in materials and set through
+     * go.set (or particlefx.set_constant) on visual components.
+     *
+     * @param predicate - predicate to draw for
+     * @param options - optional draw options
+     * @example
+     * ```ts
+     * export default defineRenderScript({
+     *   init() {
+     *     // 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);
+     *   },
+     * });
+     * ```
+     * @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: Opaque<"render_predicate">, options: render.DrawOptions): void;
     /**
      * Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.
      *
@@ -442,7 +491,7 @@ declare global {
      * });
      * ```
      */
-    function draw_debug3d(options?: render.debug_draw_options): void;
+    function draw_debug3d(options?: render.DebugDrawOptions): void;
     /**
      * If another material was already enabled, it will be automatically disabled
      * and the specified material is used instead.
@@ -494,7 +543,7 @@ declare global {
      * });
      * ```
      */
-    function enable_state(state: graphics.STATE): void;
+    function enable_state(state: Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>): 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
@@ -583,7 +632,7 @@ declare global {
      * });
      * ```
      */
-    function enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash | Opaque<"render_target"> | number, buffer_type?: graphics.BUFFER_TYPE): void;
+    function enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash | Opaque<"render_target"> | number, 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
@@ -636,7 +685,7 @@ declare global {
      * });
      * ```
      */
-    function get_render_target_height(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BUFFER_TYPE): number;
+    function get_render_target_height(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BufferType): number;
     /**
      * Returns the specified buffer width from a render target.
      *
@@ -677,7 +726,7 @@ declare global {
      * });
      * ```
      */
-    function get_render_target_width(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BUFFER_TYPE): number;
+    function get_render_target_width(render_target: Opaque<"render_target"> | string | Hash, 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
@@ -744,7 +793,7 @@ declare global {
      * render.set_blend_equation_separate(graphics.BLEND_EQUATION_ADD, graphics.BLEND_EQUATION_REVERSE_SUBTRACT);
      * ```
      */
-    function set_blend_equation_separate(equation_color: graphics.BLEND_EQUATION, equation_alpha: graphics.BLEND_EQUATION): void;
+    function set_blend_equation_separate(equation_color: graphics.BlendEquation, equation_alpha: graphics.BlendEquation): void;
     /**
      * 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
@@ -778,7 +827,7 @@ declare global {
      * render.set_blend_func(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA);
      * ```
      */
-    function set_blend_func(source_factor: graphics.BLEND_FACTOR, destination_factor: graphics.BLEND_FACTOR): void;
+    function set_blend_func(source_factor: graphics.BlendFactor, destination_factor: graphics.BlendFactor): void;
     /**
      * Sets the blend function with separate blend factors for the color and alpha channels.
      *
@@ -791,7 +840,7 @@ declare global {
      * render.set_blend_func_separate(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA, graphics.BLEND_FACTOR_ONE, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA);
      * ```
      */
-    function set_blend_func_separate(source_factor_color: number, destination_factor_color: number, source_factor_alpha: number, destination_factor_alpha: number): void;
+    function set_blend_func_separate(source_factor_color: graphics.BlendFactor, destination_factor_color: graphics.BlendFactor, source_factor_alpha: graphics.BlendFactor, destination_factor_alpha: graphics.BlendFactor): void;
     /**
      * Sets the current render camera to be used for rendering. If a render camera
      * has been set by the render script, the renderer will be using its projection and view matrix
@@ -824,7 +873,7 @@ declare global {
      * }
      * ```
      */
-    function set_camera(camera?: Url | number | string | Hash, options?: render.camera_options): void;
+    function set_camera(camera?: Url | number | string | Hash, options?: render.CameraOptions): 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`.
@@ -879,7 +928,7 @@ declare global {
      * render.set_cull_face(graphics.FACE_TYPE_FRONT);
      * ```
      */
-    function set_cull_face(face_type: graphics.FACE_TYPE): void;
+    function set_cull_face(face_type: graphics.FaceType): void;
     /**
      * Specifies the function that should be used to compare each incoming pixel
      * depth value with the value present in the depth buffer.
@@ -895,7 +944,7 @@ declare global {
      * render.set_depth_func(graphics.COMPARE_FUNC_NOTEQUAL);
      * ```
      */
-    function set_depth_func(func: graphics.COMPARE_FUNC): void;
+    function set_depth_func(func: graphics.CompareFunc): void;
     /**
      * Specifies whether the depth buffer is enabled for writing. The supplied mask governs
      * if depth buffer writing is enabled (`true`) or disabled (`false`).
@@ -931,7 +980,7 @@ declare global {
      * });
      * ```
      */
-    function set_listener(callback?: (self: unknown, event_type: render.CONTEXT_EVENT) => void): void;
+    function set_listener(callback?: (self: unknown, event_type: render.ContextEvent) => void): void;
     /**
      * Sets the scale and units used to calculate depth values.
      * If `graphics.STATE_POLYGON_OFFSET_FILL` is enabled, each fragment's depth value
@@ -1047,7 +1096,83 @@ declare global {
      * });
      * ```
      */
-    function set_render_target(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT, options?: render.set_render_target_options): void;
+    function set_render_target(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT): void;
+    /**
+     * Sets a render target. Subsequent draw operations will be to the
+     * render target until it is replaced by a subsequent call to set_render_target.
+     * This function supports render targets created by a render script, or a render target resource.
+     *
+     * @param render_target - render target to set. Omit it, pass `nil`, or use render.RENDER_TARGET_DEFAULT to set the default render target
+     * @param options - optional render-target activation options
+     *
+     * `face`
+     * number Cubemap face selected for rendering. This option is valid only for cubemap render targets and defaults to `graphics.CUBEMAP_FACE_POSITIVE_X`.
+     *
+     * - `graphics.CUBEMAP_FACE_POSITIVE_X`
+     * - `graphics.CUBEMAP_FACE_NEGATIVE_X`
+     * - `graphics.CUBEMAP_FACE_POSITIVE_Y`
+     * - `graphics.CUBEMAP_FACE_NEGATIVE_Y`
+     * - `graphics.CUBEMAP_FACE_POSITIVE_Z`
+     * - `graphics.CUBEMAP_FACE_NEGATIVE_Z`
+     * @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 defineRenderScript({
+     *   init() {
+     *     // the engine registers a texture format only when the driver supports it
+     *     const format = graphics.TEXTURE_FORMAT_RGBA;
+     *     if (format === undefined) return undefined;
+     *     const color_params = {
+     *       format,
+     *       width: render.get_window_width(),
+     *       height: render.get_window_height(),
+     *     };
+     *     return {
+     *       my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
+     *       my_pred: render.predicate([hash("my_tag")]),
+     *     };
+     *   },
+     *
+     *   update(self, dt) {
+     *     if (self === undefined) return;
+     *     // set render target so all drawing is done to it
+     *     render.set_render_target(self.my_render_target, {
+     *       transient: [graphics.BUFFER_TYPE_DEPTH_BIT, graphics.BUFFER_TYPE_STENCIL_BIT],
+     *     });
+     *
+     *     // draw a predicate to the render target
+     *     render.draw(self.my_pred);
+     *
+     *     // set default render target. This also invalidates the depth and stencil buffers of the current target (self.my_render_target)
+     *     //  which can be an optimisation on some hardware
+     *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
+     *   },
+     * });
+     * ```
+     * @example
+     * ```ts
+     * export default defineRenderScript({
+     *   init() {
+     *     return { my_pred: render.predicate([hash("my_tag")]) };
+     *   },
+     *
+     *   update(self, dt) {
+     *     // set render target by a render target resource identifier
+     *     render.set_render_target("my_rt_resource");
+     *
+     *     // draw a predicate to the render target
+     *     render.draw(self.my_pred);
+     *
+     *     // reset the render target to the default backbuffer
+     *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
+     *   },
+     * });
+     * ```
+     */
+    function set_render_target(render_target: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT | undefined, options: render.SetRenderTargetOptions): void;
     /**
      * Sets the render target size for a render target created from
      * either a render script, or from a render target resource.
@@ -1096,7 +1221,7 @@ declare global {
      * render.set_stencil_func(graphics.COMPARE_FUNC_EQUAL, 0, 1);
      * ```
      */
-    function set_stencil_func(func: graphics.COMPARE_FUNC, ref: number, mask: number): void;
+    function set_stencil_func(func: graphics.CompareFunc, ref: number, mask: number): void;
     /**
      * The stencil mask controls the writing of individual bits in the stencil buffer.
      * The least significant `n` bits of the parameter `mask`, where `n` is the number of
@@ -1138,7 +1263,7 @@ declare global {
      * render.set_stencil_op(graphics.STENCIL_OP_REPLACE, graphics.STENCIL_OP_KEEP, graphics.STENCIL_OP_KEEP);
      * ```
      */
-    function set_stencil_op(sfail: graphics.STENCIL_OP, dpfail: graphics.STENCIL_OP, dppass: graphics.STENCIL_OP): void;
+    function set_stencil_op(sfail: graphics.StencilOp, dpfail: graphics.StencilOp, dppass: graphics.StencilOp): void;
     /**
      * Sets the view matrix to use when rendering.
      *