Enforce order of 2d api calls

This issue has been created since 2021-11-04.

Problem

The 2D API design has some limitations with order.
Example of status quo

const std = @import("std");

const glfw = @import("glfw");
const zlm = @import("zlm");

const render = @import("render/render.zig");
const render2d = @import("render2d/render2d.zig");

pub fn main() anyerror!void {
    // create a gpa with default configuration
    var alloc = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = &alloc.allocator;
    
    // Initialize the library *
    try glfw.init();
    defer glfw.terminate();

    if (!try glfw.vulkanSupported()) {
        std.debug.panic("vulkan not supported on device (glfw)", .{});
    }

    // Tell glfw that we are planning to use a custom API (not opengl)
    try glfw.Window.hint(glfw.Window.Hint.client_api, glfw.no_api);

    // Create a windowed mode window 
    var window = try glfw.Window.create(800, 800, "sprite test", null, null);
    defer window.destroy();

    const ctx = try render.Context.init(allocator, "sprite test", &window, null);
    defer ctx.deinit();
    
    // ORDER DEPENDENT
    try render2d.init(allocator, ctx, 1);
    // ORDER DEPENDENT: changes internal behavior based on api state
    defer render2d.deinit();
    
    // ORDER DEPENDENT: you can load a texture after init, but not after prepare to draw 
    // easy mistake, will panic if this is not followed :( 
    const my_texture = try render2d.loadTexture("../assets/images/grasstop.png"[0..]); 
    
    const window_size = try window.getSize();
    const windowf = @intToFloat(f32, window_size.height);  
    // ORDER DEPENDENT: you can load a sprite after init, but not after prepare to draw 
    // easy mistake, will panic if this is not followed :( 
    const my_sprite = try render2d.createSprite(
        my_texture, 
        zlm.Vec2.new(0, 0),            // position
        0,                             // rotation 
        zlm.Vec2.new(windowf, windowf) // scale
    );

    // ORDER DEPENDENT:  you need to prepare to draw in order to draw
    try render2d.prepareDraw();

    // ORDER DEPENDENT: camera can only be created after library is prepared to draw
    var camera = render2d.createCamera(500, 2);

    // Loop until the user closes the window
    while (!window.shouldClose()) {
       
        my_sprite.setPosition(zlm.Vec2.new(0, 0));
        my_sprite.setRotation(10);
        camera.zoomIn(0);
        
        // ORDER DEPENDENT: draw can only be called after prepare to draw
        try render2d.draw();
        
        // Poll for and process events
        try glfw.pollEvents();
    }
}

Solution

What we can do is to gradually expose certain functions when calling state changing functions i.e init and prepareDraw by making them return the new API. This should also invalidate previous API structs.

Solution limitations

The error of using an invalidated struct will sadly still be a runtime specific error

Example:

const init_stage = try render2d.init(allocator, ctx, 1);
// code ...
const prepare_stage = init_stage.prepareDraw();
init_stage.someFunc(); //  <-- Runtime panic or error :(

There is also some design changes required when it comes to deinit behavior. Naturally you should call deinit on the returned initialized struct, not the API. It would be logical to think you can deinit the init struct without loosing data in your prepareDraw struct for example. This makes the API harder to multithread if state is shared between them in any way.

More Details About Repo
Owner Name Avokadoen
Repo Name zig_vulkan
Full Name Avokadoen/zig_vulkan
Language Zig
Created Date 2021-06-14
Updated Date 2022-01-06
Star Count 5
Watcher Count 1
Fork Count 0
Issue Count 51

YOU MAY BE INTERESTED

Issue Title Created Date Comment Count Updated Date
Optional dependency Colour causes implicit conflict with colour-science 0 2022-09-12 2022-09-23
I need access to old Nuget packages 1 2021-04-16 2022-09-20
Template 10 ellipsis collapsed error 0 2022-02-18 2022-07-21
Update to reference latest version of Newtonsoft.Json library 2 2021-08-04 2022-04-05
Exception handling in SettingsService 3 2020-06-27 2022-08-19
Any news about future? 1 2021-01-02 2022-07-28
Max98357a (purple pcb one)dac is not working 3 2022-07-12 2022-09-12
Creating a pip/conda package 1 2022-01-17 2022-09-22
Reciprocal edges in directed graph generators 4 2021-10-22 2022-08-31
Liquid error: Could not find asset snippets/style-bundle.liquid 4 2021-03-11 2022-09-18
Support for Intune 4 2019-11-08 2022-01-13
shared memory allocation integer overflow 14 2022-01-25 2022-09-11
Loosen dependency on dotty 2 2022-01-05 2022-09-22
build error 0 2021-01-09 2022-01-02
满足微信隐私政策要求,使用webpack.IgnorePlugin排除冗余微信api引入,出现Error:Cannot find module './api' error 2 2021-12-02 2022-09-18
How to deploy to production (ssl certificate)? 4 2021-03-31 2022-09-22
parseFromUrl does not resolve relative references 2 2022-03-25 2022-08-18
🔥 connect/connect-mapr-sink 23 2021-11-07 2022-07-19
Remove deprecated in-tree code 1 2021-06-14 2022-07-30
Documentation about how to construct a circuit? 1 2020-12-31 2022-09-21
package ‘thesisdown’ is not available (for R version 4.0.2) 6 2020-07-02 2022-09-20
PUT `/v2/blog/{blog-identifier}/posts` doesn't accept `state: "queued"` 2 2021-09-19 2022-09-29
[Erekir] Enemy base sectors have shifted 8 2022-05-08 2022-09-25
Website deploy script needs fixing 0 2021-02-06 2022-08-26
Is K-fold training supported?? 3 2021-12-09 2022-09-25
Remove all rounded Corners or remove firefox pointy corners 2 2022-02-27 2022-09-17
Segmentation fault due to Doctrine issue 2 2021-05-06 2022-09-15
[Feature]: Need a way to Pin apps on the Top 0 2022-06-22 2022-09-11
remove "Using password from environment variable MINA_PRIVKEY_PASS" error from helper processes 1 2022-05-05 2022-09-12
Add a button when using pip mode to come back to the regular video viewing mode 1 2021-10-13 2022-08-10
Typed value storage with Go hooks 0 2021-04-05 2022-09-09
add function zetteldeft--insert-link 3 2021-05-13 2021-10-26
Permission Boundary by environment example 1 2022-02-14 2022-09-23
[Yocto] Build failure with GCC 12.1.0 9 2022-05-11 2022-07-21
Warning: `NaN` is an invalid value for the `height` css style property. 0 2022-07-11 2022-08-27
KMSAN doesn't work with CONFIG_UNWINDER_ORC 3 2018-11-29 2022-09-22
Account recovery request 0 2022-06-09 2022-09-18
BUG: Wrong error message 1 2022-08-02 2022-09-26
Left nav refreshes after accessing a table 0 2022-06-15 2022-09-06
Forget Watch on Watches screen does nothing 1 2021-02-27 2022-07-16
[bug] react-scripts doesn't not terminate on shutdown or Crtl-C interrupt for `npm run tauri dev` 1 2022-03-01 2022-09-18
Add foldable devices and support for DisplayFeature 0 2022-09-09 2022-09-28
syncing with the upstream? 0 2021-09-02 2022-09-22
Update text dependency 1 2014-01-02 2022-02-01
Variable Explorer is missing. 6 2021-09-16 2022-09-02
Add custom login page in unattended script instead in the OVA/AMI build process 3 2021-10-22 2022-09-27
Here Traveltime blocking startup (bootstrap) 6 2022-06-17 2022-09-18
Result of sha256 (and other hash functions) should not be sensitive 2 2022-08-05 2022-09-19
[Feature Request]全局样式 1 2021-07-21 2022-08-22
Still no bulk update with EF Core 7 RC? 3 2022-09-15 2022-09-22