SDL_libretro_serialize.h

Go to the documentation of this file.

 
#if defined(SDL_LIBRETRO_IMPLEMENTATION) && !defined(SDL_LIBRETRO_SERIALIZE_IMPL_ONCE)
#define SDL_LIBRETRO_SERIALIZE_IMPL_ONCE
 
#ifdef __DOXYGEN
#define SDL_LIBRETRO_ENABLE_REWIND_DELTA
#endif
 
 
#ifndef SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES
#define SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES ((size_t)256 * 1024 * 1024)
#endif
 
// Cheats
 
bool SDL_Libretro_SetCheat(SDL_Libretro* lr, unsigned index, bool enabled, const char* code) {
    if (!lr || !lr->core.gameLoaded) return false;
    lr->core.symbols.retro_cheat_set(index, enabled, code);
    return true;
}
 
void SDL_Libretro_ResetCheats(SDL_Libretro* lr) {
    if (!lr || !lr->core.gameLoaded) return;
    lr->core.symbols.retro_cheat_reset();
}
 
// Save States
 
size_t SDL_Libretro_GetStateSize(const SDL_Libretro* lr) {
    if (!lr || !lr->core.gameLoaded) return 0;
    return lr->core.symbols.retro_serialize_size();
}
 
bool SDL_Libretro_SaveState_IO(SDL_Libretro* lr, SDL_IOStream* dst, bool closeio) {
    bool ok = false;
    if (!lr || !lr->core.gameLoaded || !dst) {
        SDL_SetError("[SDL_Libretro] Invalid SaveState_IO arguments");
    } else {
        size_t size = lr->core.symbols.retro_serialize_size();
        if (size == 0) {
            SDL_SetError("[SDL_Libretro] Core does not support save states");
        } else {
            void* data = SDL_malloc(size);
            if (data) {
                if (lr->core.symbols.retro_serialize(data, size)) {
                    ok = (SDL_WriteIO(dst, data, size) == size);
                }
                SDL_free(data);
            }
        }
    }
    if (closeio && dst) SDL_CloseIO(dst);
    return ok;
}
 
bool SDL_Libretro_SaveState(SDL_Libretro* lr, const char* file) {
    if (!lr || !lr->core.gameLoaded || !file) {
        SDL_SetError("[SDL_Libretro] Invalid SaveState arguments");
        return false;
    }
 
    SDL_IOStream* io = SDL_IOFromFile(file, "wb");
    if (!io) return false;
    return SDL_Libretro_SaveState_IO(lr, io, true);
}
 
bool SDL_Libretro_LoadState_IO(SDL_Libretro* lr, SDL_IOStream* src, bool closeio) {
    if (!lr || !lr->core.gameLoaded || !src) {
        SDL_SetError("[SDL_Libretro] Invalid LoadState_IO arguments");
        if (closeio && src) SDL_CloseIO(src);
        return false;
    }
    size_t size = 0;
    void* data = SDL_LoadFile_IO(src, &size, closeio);
    if (!data) return false;
    bool ok = (size > 0) && lr->core.symbols.retro_unserialize(data, size);
    SDL_free(data);
    // A load is a timeline discontinuity: drop rewind history so a subsequent rewind can't walk back across it into the pre-load timeline.
    if (ok && lr->rewindEnabled) SDL_Libretro_ClearRewind(lr);
    return ok;
}
 
bool SDL_Libretro_LoadState(SDL_Libretro* lr, const char* file) {
    if (!lr || !lr->core.gameLoaded || !file) {
        SDL_SetError("[SDL_Libretro] Invalid LoadState arguments");
        return false;
    }
    SDL_IOStream* io = SDL_IOFromFile(file, "rb");
    if (!io) return false;
    return SDL_Libretro_LoadState_IO(lr, io, true);
}
 
// Memory
 
void* SDL_Libretro_GetMemoryData(const SDL_Libretro* lr, unsigned memoryType, size_t* size) {
    if (!lr || !lr->core.gameLoaded || !lr->core.symbols.retro_get_memory_data || !lr->core.symbols.retro_get_memory_size) {
        if (size) *size = 0;
        return NULL;
    }
    void* ptr = lr->core.symbols.retro_get_memory_data(memoryType);
    if (size) *size = lr->core.symbols.retro_get_memory_size(memoryType);
    return ptr;
}
 
bool SDL_Libretro_SetMemoryData(SDL_Libretro* lr, unsigned memoryType, const void* data, size_t size) {
    if (!lr || !data) {
        SDL_SetError("[SDL_Libretro] Invalid SetMemoryData arguments");
        return false;
    }
    size_t capacity = 0;
    void* dst = SDL_Libretro_GetMemoryData(lr, memoryType, &capacity);
    if (!dst || capacity == 0) {
        SDL_SetError("[SDL_Libretro] Memory type %u unavailable", memoryType);
        return false;
    }
    size_t copySize = size < capacity ? size : capacity;
    SDL_memcpy(dst, data, copySize);
    return true;
}
 
static void SDL_Libretro_FreeMemoryMap(SDL_Libretro* lr) {
    if (lr->core.memoryMapDescriptors) {
        for (unsigned i = 0; i < lr->core.memoryMapDescriptorCount; i++) {
            SDL_free((void*)lr->core.memoryMapDescriptors[i].addrspace);
        }
        SDL_free(lr->core.memoryMapDescriptors);
        lr->core.memoryMapDescriptors = NULL;
    }
    lr->core.memoryMapDescriptorCount = 0;
}
 
unsigned SDL_Libretro_GetMemoryMapCount(const SDL_Libretro* lr) {
    return (lr && lr->core.gameLoaded) ? lr->core.memoryMapDescriptorCount : 0;
}
 
bool SDL_Libretro_GetMemoryMapDescriptor(const SDL_Libretro* lr, unsigned index,
    Uint64* flags, void** ptr, size_t* offset, size_t* start,
    size_t* select, size_t* disconnect, size_t* len, const char** addrspace) {
    if (!lr || !lr->core.gameLoaded || index >= lr->core.memoryMapDescriptorCount) {
        return false;
    }
    const struct retro_memory_descriptor* d = &lr->core.memoryMapDescriptors[index];
    if (flags) *flags = d->flags;
    if (ptr) *ptr = d->ptr;
    if (offset) *offset = d->offset;
    if (start) *start = d->start;
    if (select) *select = d->select;
    if (disconnect) *disconnect = d->disconnect;
    if (len) *len = d->len;
    if (addrspace) *addrspace = d->addrspace;
    return true;
}
 
void* SDL_Libretro_GetMapAddress(const SDL_Libretro* lr, size_t address, size_t* regionRemaining) {
    if (regionRemaining) *regionRemaining = 0;
    if (!lr || !lr->core.gameLoaded) return NULL;
 
    for (unsigned i = 0; i < lr->core.memoryMapDescriptorCount; i++) {
        const struct retro_memory_descriptor* d = &lr->core.memoryMapDescriptors[i];
        if (!d->ptr || d->len == 0) continue;
 
        // Does this descriptor's address space contain `address`?
        if (d->select != 0) {
            if (((address ^ d->start) & d->select) != 0) continue;
        } else if (address < d->start || (address - d->start) >= d->len) {
            continue;
        }
 
        // Fold out disconnected bits, then offset into the host buffer.
        size_t masked = address & ~d->disconnect;
        if (masked < d->start) continue;
        size_t within = masked - d->start;
        if (within >= d->len) continue;
 
        if (regionRemaining) *regionRemaining = d->len - within;
        return (Uint8*)d->ptr + d->offset + within;
    }
    return NULL;
}
 
static const char* SDL_Libretro_GetMemoryTypeName(unsigned memoryType) {
    switch (memoryType) {
        case RETRO_MEMORY_SAVE_RAM:   return "SRAM";
        case RETRO_MEMORY_RTC:        return "RTC";
        case RETRO_MEMORY_SYSTEM_RAM: return "system RAM";
        case RETRO_MEMORY_VIDEO_RAM:  return "video RAM";
        default:                      return "memory";
    }
}
 
bool SDL_Libretro_SaveMemory_IO(SDL_Libretro* lr, unsigned memoryType, SDL_IOStream* dst, bool closeio) {
    bool ok = false;
    if (!lr || !lr->core.gameLoaded || !dst) {
        SDL_SetError("[SDL_Libretro] Invalid SaveMemory_IO arguments");
    } else {
        size_t size = 0;
        void* mem = SDL_Libretro_GetMemoryData(lr, memoryType, &size);
        if (!mem || size == 0) {
            ok = true; // core has no such memory; nothing to save
        } else {
            ok = (SDL_WriteIO(dst, mem, size) == size);
        }
    }
    if (closeio && dst) SDL_CloseIO(dst);
    return ok;
}
 
bool SDL_Libretro_SaveMemory(SDL_Libretro* lr, unsigned memoryType, const char* file) {
    if (!lr || !lr->core.gameLoaded || !file) {
        SDL_SetError("[SDL_Libretro] Invalid SaveMemory arguments");
        return false;
    }
 
    size_t size = 0;
    void* mem = SDL_Libretro_GetMemoryData(lr, memoryType, &size);
    // Nothing to save, so don't create an empty file.
    if (!mem || size == 0) return true;
 
    SDL_IOStream* io = SDL_IOFromFile(file, "wb");
    if (!io) return false;
    bool ok = SDL_Libretro_SaveMemory_IO(lr, memoryType, io, true);
    if (ok) {
        SDL_Log("[SDL_Libretro] %s saved to %s (%zu bytes)",
            SDL_Libretro_GetMemoryTypeName(memoryType), file, size);
    }
    return ok;
}
 
bool SDL_Libretro_LoadMemory_IO(SDL_Libretro* lr, unsigned memoryType, SDL_IOStream* src, bool closeio) {
    if (!lr || !lr->core.gameLoaded || !src) {
        SDL_SetError("[SDL_Libretro] Invalid LoadMemory_IO arguments");
        if (closeio && src) SDL_CloseIO(src);
        return false;
    }
 
    // Bail before reading the stream when there's nowhere to put the data.
    size_t capacity = 0;
    if (!SDL_Libretro_GetMemoryData(lr, memoryType, &capacity) || capacity == 0) {
        SDL_SetError("[SDL_Libretro] Core has no %s", SDL_Libretro_GetMemoryTypeName(memoryType));
        if (closeio) SDL_CloseIO(src);
        return false;
    }
 
    size_t fileSize = 0;
    void* data = SDL_LoadFile_IO(src, &fileSize, closeio);
    if (!data) return false;
 
    // A size mismatch is the usual cause of a save that loads only partially.
    if (fileSize != capacity) {
        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION,
            "[SDL_Libretro] %s size mismatch (file %zu bytes, region %zu bytes); loading %zu",
            SDL_Libretro_GetMemoryTypeName(memoryType), fileSize, capacity,
            fileSize < capacity ? fileSize : capacity);
    }
 
    // SetMemoryData clamps to the region capacity.
    bool ok = SDL_Libretro_SetMemoryData(lr, memoryType, data, fileSize);
    SDL_free(data);
    return ok;
}
 
bool SDL_Libretro_LoadMemory(SDL_Libretro* lr, unsigned memoryType, const char* file) {
    if (!lr || !lr->core.gameLoaded || !file) {
        SDL_SetError("[SDL_Libretro] Invalid LoadMemory arguments");
        return false;
    }
    SDL_IOStream* io = SDL_IOFromFile(file, "rb");
    if (!io) return false;
    bool ok = SDL_Libretro_LoadMemory_IO(lr, memoryType, io, true);
    if (ok) {
        SDL_Log("[SDL_Libretro] %s loaded from %s",
            SDL_Libretro_GetMemoryTypeName(memoryType), file);
    }
    return ok;
}
 
// SRAM convenience wrappers (RETRO_MEMORY_SAVE_RAM)
 
bool SDL_Libretro_SaveSRAM_IO(SDL_Libretro* lr, SDL_IOStream* dst, bool closeio) {
    return SDL_Libretro_SaveMemory_IO(lr, RETRO_MEMORY_SAVE_RAM, dst, closeio);
}
 
bool SDL_Libretro_SaveSRAM(SDL_Libretro* lr, const char* file) {
    return SDL_Libretro_SaveMemory(lr, RETRO_MEMORY_SAVE_RAM, file);
}
 
bool SDL_Libretro_LoadSRAM_IO(SDL_Libretro* lr, SDL_IOStream* src, bool closeio) {
    return SDL_Libretro_LoadMemory_IO(lr, RETRO_MEMORY_SAVE_RAM, src, closeio);
}
 
bool SDL_Libretro_LoadSRAM(SDL_Libretro* lr, const char* file) {
    return SDL_Libretro_LoadMemory(lr, RETRO_MEMORY_SAVE_RAM, file);
}
 
// Rewind
 
#ifdef SDL_LIBRETRO_ENABLE_REWIND_DELTA
 
static size_t SDL_Libretro_RewindMaxEncodedSize(size_t len) {
    return len + (len / 128) + 1;
}
 
static size_t SDL_Libretro_RewindMatchRun(const unsigned char* a, const unsigned char* b, size_t max) {
    size_t i = 0;
    for (; i + sizeof(size_t) <= max; i += sizeof(size_t)) {
        size_t wa, wb;
        SDL_memcpy(&wa, a + i, sizeof(size_t));
        SDL_memcpy(&wb, b + i, sizeof(size_t));
        if (wa != wb) break;
    }
    while (i < max && a[i] == b[i]) i++;
    return i;
}
 
static size_t SDL_Libretro_RewindEncodeDelta(const unsigned char* cur, const unsigned char* ref, size_t len, unsigned char* out, size_t outCap) {
    // A matching gap shorter than this is cheaper to fold into a literal than to emit as a skip. A skip also forces a new literal header afterwards.
    const size_t kMinSkip = 3;
 
    size_t op = 0, i = 0;
    while (i < len) {
        if (cur[i] == ref[i]) {
            size_t run = SDL_Libretro_RewindMatchRun(cur + i, ref + i, len - i);
            i += run;
            while (run > 0) {
                if (run <= 127) {
                    if (out) { if (op >= outCap) return 0; out[op] = (unsigned char)run; }
                    op++;
                    run = 0;
                } else if (run < 255) {
                    // Two short skips (2 bytes) beat one extended skip (3)
                    if (out) { if (op >= outCap) return 0; out[op] = 127; }
                    op++;
                    run -= 127;
                } else {
                    size_t chunk = run > 65535 ? 65535 : run;
                    if (out) {
                        if (op + 3 > outCap) return 0;
                        out[op]     = 0x00;
                        out[op + 1] = (unsigned char)(chunk & 0xFF);
                        out[op + 2] = (unsigned char)(chunk >> 8);
                    }
                    op += 3;
                    run -= chunk;
                }
            }
        } else {
            // Literal segment: a span of differing bytes that absorbs any matching gaps shorter than kMinSkip (folded as zero XOR bytes).
            size_t segStart = i;
            size_t segEnd = i;
            size_t j = i;
            for (;;) {
                while (j < len && cur[j] != ref[j]) j++;
                segEnd = j;
                if (j >= len) break;
                size_t gapStart = j;
                j += SDL_Libretro_RewindMatchRun(cur + j, ref + j, len - j);
                if ((j - gapStart) >= kMinSkip || j >= len) break;
            }
            i = segEnd;
            for (size_t pos = segStart; pos < segEnd; ) {
                size_t chunk = segEnd - pos;
                if (chunk > 128) chunk = 128;
                if (out) {
                    if (op + 1 + chunk > outCap) return 0;
                    out[op] = (unsigned char)(0x80 | (chunk - 1));
                }
                op++;
                for (size_t k = pos; k < pos + chunk; k++) {
                    if (out) out[op] = cur[k] ^ ref[k];
                    op++;
                }
                pos += chunk;
            }
        }
    }
    return op;
}
 
static bool SDL_Libretro_RewindDecodeDelta(const unsigned char* delta, size_t deltaLen, unsigned char* state, size_t stateLen) {
    size_t dp = 0, sp = 0;
    while (dp < deltaLen && sp < stateLen) {
        unsigned char tag = delta[dp++];
        if (tag == 0x00) {
            if (dp + 2 > deltaLen) return false;
            size_t skip = delta[dp] | ((size_t)delta[dp + 1] << 8);
            dp += 2;
            sp += skip;
        } else if (tag <= 0x7F) {
            sp += tag;
        } else {
            size_t count = (tag & 0x7F) + 1;
            if (dp + count > deltaLen || sp + count > stateLen) return false;
            for (size_t j = 0; j < count; j++)
                state[sp++] ^= delta[dp++];
        }
    }
    return (sp <= stateLen);
}
 
#endif /* SDL_LIBRETRO_ENABLE_REWIND_DELTA */
 
bool SDL_Libretro_SetRewindEnabled(SDL_Libretro* lr, bool enabled, unsigned bufferFrames, unsigned captureInterval) {
    if (!lr) return false;
 
    SDL_Libretro_RewindFree(lr);
 
    if (!enabled) {
        lr->rewindEnabled = false;
        return true;
    }
 
    // Sane defaults.
    if (bufferFrames == 0) bufferFrames = 300;
    if (captureInterval == 0) captureInterval = 1;
 
    // Allow enabling rewind, when a core isn't loaded.
    if (!lr->core.loaded) {
        lr->rewindEnabled = true;
        lr->rewindCapacity = bufferFrames;
        lr->rewindCaptureInterval = captureInterval;
        return true;
    }
 
    // Figure out how large the state needs to be.
    size_t slotSize = lr->core.symbols.retro_serialize_size();
    if (slotSize == 0) {
        SDL_SetError("[SDL_Libretro] Core does not support serialization");
        lr->rewindEnabled = false;
        return false;
    }
 
    // Cores that flag their state as incomplete warn the frontend not to rely on it for frame-sensitive features (netplay, rerecording).
    if (lr->core.serializationQuirks & RETRO_SERIALIZATION_QUIRK_INCOMPLETE) {
        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION,
            "[SDL_Libretro] Core reports incomplete serialization, so rewind may be unreliable");
    }
 
    // Initialize the rewind slots.
    unsigned char* ref = (unsigned char*)SDL_calloc(1, slotSize);
    unsigned char* scratch = (unsigned char*)SDL_malloc(slotSize);
    SDL_LibretroRewindDelta* entries = (SDL_LibretroRewindDelta*)SDL_calloc(bufferFrames, sizeof(*entries));
    unsigned char* encScratch = NULL;
    bool ok = (ref && scratch && entries);
#ifdef SDL_LIBRETRO_ENABLE_REWIND_DELTA
    // Delta mode keeps a reusable worst-case-sized buffer for single-pass encoding. Full-state mode stores raw snapshots and needs none.
    encScratch = (unsigned char*)SDL_malloc(SDL_Libretro_RewindMaxEncodedSize(slotSize));
    ok = ok && (encScratch != NULL);
#endif
    if (!ok) {
        SDL_free(ref);
        SDL_free(scratch);
        SDL_free(encScratch);
        SDL_free(entries);
        SDL_SetError("[SDL_Libretro] Failed to allocate rewind buffers");
        lr->rewindEnabled = false;
        return false;
    }
 
    // Set the initial state.
    lr->rewindReference = ref;
    lr->rewindScratch = scratch;
    lr->rewindEncodeScratch = encScratch; // NULL in full-state mode
    lr->rewindEntries = entries;
    lr->rewindSlotSize = slotSize;
    lr->rewindBytes = 0;
    lr->rewindCapacity = bufferFrames;
    lr->rewindCaptureInterval = captureInterval;
    lr->rewindHead = 0;
    lr->rewindCount = 0;
    lr->rewindFrameCounter = 0;
    lr->rewindEnabled = true;
    lr->rewindHasReference = false;
    lr->rewindActive = false;
    return true;
}
 
bool SDL_Libretro_GetRewindEnabled(const SDL_Libretro* lr) {
    return lr && lr->rewindEnabled;
}
 
double SDL_Libretro_GetRewindRemaining(const SDL_Libretro* lr) {
    if (!lr || !lr->rewindEnabled || lr->rewindCount == 0) return 0.0;
    double fps = lr->core.fps > 0.0 ? lr->core.fps : 60.0;
    return (double)lr->rewindCount * (double)lr->rewindCaptureInterval / fps;
}
 
size_t SDL_Libretro_GetRewindMemoryUsage(const SDL_Libretro* lr) {
    if (!lr || !lr->rewindEnabled) return 0;
    size_t total = lr->rewindBytes;
    if (lr->rewindReference) total += lr->rewindSlotSize;
    if (lr->rewindScratch) total += lr->rewindSlotSize;
    total += (size_t)lr->rewindCapacity * sizeof(SDL_LibretroRewindDelta);
    return total;
}
 
void SDL_Libretro_SetRewindMemoryLimit(SDL_Libretro* lr, size_t maxBytes) {
    if (!lr) return;
    lr->rewindMaxBytes = maxBytes;
    SDL_Libretro_RewindEvictToBudget(lr);
}
 
size_t SDL_Libretro_GetRewindMemoryLimit(const SDL_Libretro* lr) {
    return lr ? lr->rewindMaxBytes : 0;
}
 
bool SDL_Libretro_SetRewindMemoryDuration(SDL_Libretro* lr, double seconds) {
    if (!lr) return false;
    if (!(seconds > 0.0)) {
        SDL_SetError("[SDL_Libretro] Rewind duration must be positive");
        return false;
    }
 
    // Per-snapshot worst-case size. Prefer the size the rewind buffer is already
    // using; otherwise query the core directly so this works before rewind is enabled.
    size_t slotSize = lr->rewindSlotSize;
    if (slotSize == 0 && lr->core.loaded && lr->core.symbols.retro_serialize_size) {
        slotSize = lr->core.symbols.retro_serialize_size();
    }
    if (slotSize == 0) {
        SDL_SetError("[SDL_Libretro] Rewind state size unknown; load a serializable core first");
        return false;
    }
 
    double fps = (lr->core.fps > 0.0) ? lr->core.fps : 60.0;
    unsigned interval = (lr->rewindCaptureInterval > 0) ? lr->rewindCaptureInterval : 1;
 
    // Number of snapshots that cover the requested span, rounded up so the budget
    // never falls short of the duration.
    double snapshots = (seconds * fps) / (double)interval;
    if (snapshots < 1.0) snapshots = 1.0;
    size_t snaps = (size_t)snapshots;
    if ((double)snaps < snapshots) snaps++;
 
    SDL_Libretro_SetRewindMemoryLimit(lr, snaps * slotSize);
    return true;
}
 
static void SDL_Libretro_RewindCapture(SDL_Libretro* lr) {
    if (!lr->rewindEnabled || !lr->rewindReference) return;
 
    lr->rewindFrameCounter++;
    if (lr->rewindFrameCounter < lr->rewindCaptureInterval) return;
    lr->rewindFrameCounter = 0;
 
    // A core may change its serialize size mid-session
    // (RETRO_SERIALIZATION_QUIRK_CORE_VARIABLE_SIZE). The reference/scratch
    // buffers and every stored delta are sized to the old state, so resize the
    // working buffers and drop the now-incompatible history before continuing.
    // Without this, retro_serialize() into an undersized scratch fails and rewind
    // silently stops recording.
    size_t curSize = lr->core.symbols.retro_serialize_size();
    if (curSize == 0) return;
    if (curSize != lr->rewindSlotSize) {
        unsigned char* nref = (unsigned char*)SDL_calloc(1, curSize);
        unsigned char* nscr = (unsigned char*)SDL_malloc(curSize);
        unsigned char* nenc = NULL;
        bool ok = (nref && nscr);
#ifdef SDL_LIBRETRO_ENABLE_REWIND_DELTA
        nenc = (unsigned char*)SDL_malloc(SDL_Libretro_RewindMaxEncodedSize(curSize));
        ok = ok && (nenc != NULL);
#endif
        if (!ok) {
            SDL_free(nref);
            SDL_free(nscr);
            SDL_free(nenc);
            return;
        }
        SDL_free(lr->rewindReference);
        SDL_free(lr->rewindScratch);
        SDL_free(lr->rewindEncodeScratch);
        lr->rewindReference = nref;
        lr->rewindScratch = nscr;
        lr->rewindEncodeScratch = nenc; // NULL in full-state mode
        lr->rewindSlotSize = curSize;
        SDL_Libretro_ClearRewind(lr);
    }
 
    if (!lr->core.symbols.retro_serialize(lr->rewindScratch, lr->rewindSlotSize)) return;
 
    if (!lr->rewindHasReference) {
        SDL_memcpy(lr->rewindReference, lr->rewindScratch, lr->rewindSlotSize);
        lr->rewindHasReference = true;
        return;
    }
 
    // Store the step needed to walk back to the previous state. Both modes keep
    // `reference` holding the newest state and the slot holding the previous one,
    // so the head always represents "now" and step-back semantics are identical.
    SDL_LibretroRewindDelta* slot = &lr->rewindEntries[lr->rewindHead];
#ifdef SDL_LIBRETRO_ENABLE_REWIND_DELTA
    // Delta mode: encode the change between the new state (scratch) and the
    // previous one (reference) once into the reusable worst-case-sized buffer,
    // then copy just the produced bytes into the slot. The old approach ran the
    // encoder twice (a NULL pass to size, then a real pass), scanning the whole
    // state both times; for multi-megabyte states (e.g. PSX) that second pass
    // dominated capture cost. The copy here is only of the compressed delta.
    size_t storeSize = SDL_Libretro_RewindEncodeDelta(
        lr->rewindScratch, lr->rewindReference, lr->rewindSlotSize,
        lr->rewindEncodeScratch, SDL_Libretro_RewindMaxEncodedSize(lr->rewindSlotSize));
    if (storeSize == 0) return;
 
    // Reuse the slot's existing allocation when it's already big enough; only (re)allocate when the snapshot needs more room. At steady state this stops allocating entirely, avoiding a malloc/free on every captured frame.
    //
    // rewindBytes tracks allocated snapshot memory (capacity), so it stays accurate whether or not a slot is overwritten in place.
    if (slot->capacity < storeSize) {
        unsigned char* data = (unsigned char*)SDL_realloc(slot->data, storeSize);
        if (!data) return;
        lr->rewindBytes += storeSize - slot->capacity;
        slot->data = data;
        slot->capacity = storeSize;
    }
    SDL_memcpy(slot->data, lr->rewindEncodeScratch, storeSize);
    slot->length = storeSize;
 
    // Ping-pong: the freshly serialized state in `scratch` becomes the new reference, and the now-stale reference buffer is recycled as next frame's scratch (overwritten by the next retro_serialize). Swapping pointers avoids a full state-sized memcpy on every captured frame.
    unsigned char* swap = lr->rewindReference;
    lr->rewindReference = lr->rewindScratch;
    lr->rewindScratch = swap;
#else
    // Full-state mode. The slot must hold the previous state verbatim, which is exactly what `reference` already contains. Rather than memcpy a multi-MB state into the slot every frame, donate the reference buffer to the slot and recycle the slot's old (evicted) buffer as the next scratch, a few pointer assignments instead of a full state-sized copy. The new state in `scratch` becomes the reference. Both buffers are sized to slotSize, so in steady state no allocation happens at all.
    unsigned char* recycled = slot->data; // old state being evicted from this slot (NULL until first wrap)
    size_t recycledCap = slot->capacity;
    if (recycledCap < lr->rewindSlotSize) {
        // Slot's buffer can't serve as a full-state scratch; grow it before mutating anything so a failure leaves the ring and buffers untouched.
        unsigned char* grown = (unsigned char*)SDL_realloc(recycled, lr->rewindSlotSize);
        if (!grown) return;
        recycled = grown;
        recycledCap = lr->rewindSlotSize;
    }
 
    lr->rewindBytes += lr->rewindSlotSize - slot->capacity;
    slot->data = lr->rewindReference; // holds the previous state
    slot->length = lr->rewindSlotSize;
    slot->capacity = lr->rewindSlotSize;
    lr->rewindReference = lr->rewindScratch; // holds the new state
    lr->rewindScratch = recycled;
#endif
 
    lr->rewindHead = (lr->rewindHead + 1) % lr->rewindCapacity;
    if (lr->rewindCount < lr->rewindCapacity) {
        lr->rewindCount++;
    }
 
    // Keep total delta memory under the configured budget by dropping the oldest snapshots; this bounds worst-case memory for large/incompressible states.
    SDL_Libretro_RewindEvictToBudget(lr);
}
 
static void SDL_Libretro_RewindFreeEntry(SDL_Libretro* lr, SDL_LibretroRewindDelta* entry) {
    lr->rewindBytes -= entry->capacity;
    SDL_free(entry->data);
    entry->data = NULL;
    entry->length = 0;
    entry->capacity = 0;
}
 
static bool SDL_Libretro_RewindStepState(SDL_Libretro* lr) {
    if (!lr->rewindEnabled || !lr->rewindReference || lr->rewindCount == 0) return false;
 
    lr->rewindHead = (lr->rewindHead == 0) ? (lr->rewindCapacity - 1) : (lr->rewindHead - 1);
    lr->rewindCount--;
 
    SDL_LibretroRewindDelta* entry = &lr->rewindEntries[lr->rewindHead];
    if (!entry->data || entry->length == 0) return false;
 
#ifdef SDL_LIBRETRO_ENABLE_REWIND_DELTA
    bool reconstructed = SDL_Libretro_RewindDecodeDelta(entry->data, entry->length,
        lr->rewindReference, lr->rewindSlotSize);
#else
    // Full-state mode: the entry is the previous state verbatim.
    bool reconstructed = (entry->length == lr->rewindSlotSize);
    if (reconstructed) SDL_memcpy(lr->rewindReference, entry->data, lr->rewindSlotSize);
#endif
 
    SDL_Libretro_RewindFreeEntry(lr, entry);
 
    // A failed reconstruction (a malformed or partial XOR decode) or a rejected
    // unserialize leaves `reference` out of sync with the state the core still
    // holds, and the remaining deltas are anchored to a reference we can no
    // longer rebuild. Discard the now-untrustworthy history so the next forward
    // capture re-seeds from a clean serialize instead of encoding the next delta
    // against a corrupt base.
    if (!reconstructed || !lr->core.symbols.retro_unserialize(lr->rewindReference, lr->rewindSlotSize)) {
        SDL_Libretro_ClearRewind(lr);
        return false;
    }
    return true;
}
 
static bool SDL_Libretro_RewindStep(SDL_Libretro* lr) {
    if (!lr || !lr->core.gameLoaded || !lr->rewindEnabled) {
        SDL_SetError("[SDL_Libretro] Rewind is not enabled");
        return false;
    }
    if (!SDL_Libretro_RewindStepState(lr)) return false;
 
    lr->rewindActive = true;
    lr->core.symbols.retro_run();
    lr->rewindActive = false;
    return true;
}
 
static void SDL_Libretro_RewindEvictToBudget(SDL_Libretro* lr) {
    if (!lr->rewindEnabled || lr->rewindMaxBytes == 0 || !lr->rewindEntries) return;
 
    while (lr->rewindBytes > lr->rewindMaxBytes && lr->rewindCount > 1) {
        unsigned tail = (lr->rewindHead + lr->rewindCapacity - lr->rewindCount) % lr->rewindCapacity;
        SDL_Libretro_RewindFreeEntry(lr, &lr->rewindEntries[tail]);
        lr->rewindCount--;
    }
}
 
static void SDL_Libretro_ClearRewind(SDL_Libretro* lr) {
    if (!lr) return;
    if (lr->rewindEntries) {
        for (unsigned i = 0; i < lr->rewindCapacity; i++) {
            SDL_free(lr->rewindEntries[i].data);
            lr->rewindEntries[i].data = NULL;
            lr->rewindEntries[i].length = 0;
            lr->rewindEntries[i].capacity = 0;
        }
    }
    lr->rewindBytes = 0;
    lr->rewindHead = 0;
    lr->rewindCount = 0;
    lr->rewindFrameCounter = 0;
    lr->rewindHasReference = false;
}
 
static void SDL_Libretro_RewindFree(SDL_Libretro* lr) {
    // Clear the rewind data.
    SDL_Libretro_ClearRewind(lr);
 
    // Free all of the allocated memory.
    SDL_free(lr->rewindEntries);
    lr->rewindEntries = NULL;
    SDL_free(lr->rewindReference);
    lr->rewindReference = NULL;
    SDL_free(lr->rewindScratch);
    lr->rewindScratch = NULL;
    SDL_free(lr->rewindEncodeScratch);
    lr->rewindEncodeScratch = NULL;
    lr->rewindSlotSize = 0;
    lr->rewindActive = false;
}
 
#endif /* SDL_LIBRETRO_SERIALIZE_IMPL_ONCE */