tiny.gif.EncodeStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []align(capacity_mod.storage_alignment) u8,5    keys: []u32,6    codes: []u16,7    compressed: []u8,8    output: []u8,9    in_use: bool = false,1011    pub const Limits: type = capacity_mod.Limits;12    pub const Capacity: type = capacity_mod.Capacity;13    pub const Exhaustion: type = model.Exhaustion;14    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;15    pub const AcquireError: type = plan_mod.Error;1617    pub const claim: alloc_phase.capacity.Declaration = .{18        .source = .{19            .id = "gif.encode_storage",20            .kind = .phase_static,21            .limit_source = .caller,22            .storage = .{23                .covered = &.{24                    .{25                        .id = "global_palette_and_exact_encoding_plan",26                        .lifetime = .steady,27                        .detail = "global palette and exact encoding plan",28                    },29                    .{30                        .id = "lzw_dictionary_and_compressed_frame_scratch",31                        .lifetime = .steady,32                        .detail = "LZW dictionary and compressed-frame scratch",33                    },34                    .{35                        .id = "encoded_gif_output_bytes",36                        .lifetime = .steady,37                        .detail = "encoded GIF output bytes",38                    },39                },40                .excluded = &.{41                    "caller-owned animation frame bytes and frame views",42                    "filesystem and downstream decoder storage",43                },44            },45            .capacity = .{46                .inputs = &.{47                    alloc_phase.capacity.bindInput(Limits, "animation_frames", "animation.frames"),48                    alloc_phase.capacity.bindInput(Limits, "bounds_canvas_pixels", "bounds.canvas_pixels"),49                    alloc_phase.capacity.bindInput(Limits, "bounds_frames", "bounds.frames"),50                },51                .type_selectors = &.{},52                .nodes = &.{53                    .{ .constant = 49152 },54                    .{ .input = 1 },55                    .{ .input = 2 },56                    .{ .add = .{ .left = 0, .right = 1 } },57                    .{ .add = .{ .left = 3, .right = 2 } },58                },59                .assertions = &.{.{60                    .scope = .closure_total,61                    .measure = .retained,62                    .relation = .upper_bound,63                    .expression = 4,64                }},65            },66            .overload = .{67                .kind = .reject_before_mutation,68                .detail = "Bounds, input mismatch, and concurrent use reject before output mutation.",69            },70            .risks = .{71                .transitive = .{72                    .status = .witnessed,73                    .detail = "Palette lookup, LZW coding, GIF framing, and output writing use fixed regions.",74                },75                .foreign = .{76                    .status = .excluded,77                    .detail = "input ownership and output consumption remain caller effects",78                },79            },80            .obligations = &.{81                .{ .key = "gif_encode_capacity", .role = .capacity_model },82                .{ .key = "gif_encode_acquisition", .role = .custom },83                .{ .key = "gif_encode_oom", .role = .custom },84                .{ .key = "gif_encode_boundaries", .role = .overload },85                .{ .key = "gif_encode_reuse", .role = .overload },86                .{ .key = "gif_encode_sealed", .role = .transitive_risk },87                .{ .key = "gif_encode_root", .role = .custom },88                .{ .key = "gif_encode_consumer", .role = .foreign_risk },89            },90        },91        .bindings = .{92            .owner = @This(),93            .seal = .{94                .family = alloc_phase.capacity.selector(@This().activate),95                .premise = .{96                    .class = .checked_semantic_fact,97                    .authority = .checker,98                },99            },100            .teardown = .{101                .family = alloc_phase.capacity.selector(@This().deinit),102                .premise = .{103                    .class = .checked_semantic_fact,104                    .authority = .checker,105                },106            },107        },108    };109110    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {111        const capacity = try Capacity.derive(limits);112        const bytes = try allocator.alignedAlloc(113            u8,114            .fromByteUnits(capacity_mod.storage_alignment),115            capacity.storage_bytes,116        );117        const compressed_bytes = capacity.plan.max_compressed_bytes;118        const compressed = bytes[capacity.compressed_offset..][0..compressed_bytes];119        return .{120            .phase = .initialization,121            .capacity = capacity,122            .bytes = bytes,123            .keys = typedSlice(u32, bytes, capacity.key_offset, lzw.dictionary_slots),124            .codes = typedSlice(u16, bytes, capacity.code_offset, lzw.dictionary_slots),125            .compressed = compressed,126            .output = bytes[capacity.output_offset..][0..capacity.plan.output_bytes],127        };128    }129130    pub fn activate(self: *Storage) void {131        std.debug.assert(self.phase == .initialization);132        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);133        self.phase = .steady;134    }135136    pub fn acquire(self: *Storage, animation: model.AnimationView) AcquireError!Regions {137        std.debug.assert(self.phase == .steady);138        if (self.in_use) return error.EncodeStorageInUse;139        const dictionary = lzw.Dictionary.init(self.keys, self.codes);140        const actual = try plan_mod.Plan.inspectDictionary(141            animation,142            self.capacity.plan.bounds,143            dictionary,144        );145        if (!std.meta.eql(actual, self.capacity.plan)) return error.EncodeInputMismatch;146        self.in_use = true;147        return .{148            .dictionary = dictionary,149            .compressed = self.compressed,150            .output = self.output,151        };152    }153154    pub fn reset(self: *Storage) void {155        std.debug.assert(self.phase == .steady);156        std.debug.assert(self.in_use);157        self.in_use = false;158    }159160    pub fn status(self: *const Storage) Status {161        return .{162            .phase = self.phase,163            .in_use = self.in_use,164            .storage_bytes = self.capacity.storage_bytes,165            .canvas_pixels = self.capacity.plan.canvas_pixels,166            .frames = self.capacity.plan.frames,167            .palette_entries = self.capacity.plan.palette_entries,168            .compressed_bytes = self.capacity.plan.max_compressed_bytes,169            .output_bytes = self.capacity.plan.output_bytes,170        };171    }172173    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {174        std.debug.assert(self.phase != .teardown);175        std.debug.assert(!self.in_use);176        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);177        self.phase = .teardown;178        allocator.free(self.bytes);179        self.bytes = &.{};180        self.keys = &.{};181        self.codes = &.{};182        self.compressed = &.{};183        self.output = &.{};184    }185};

1pub const EncodeStorage = encode.Storage;