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
 
// Save Files
 
static SDL_IOStream* SDL_Libretro_OpenSaveFile(const char* file, char* tempPath, size_t tempPathSize) {
    if ((size_t)SDL_snprintf(tempPath, tempPathSize, "%s.tmp", file) >= tempPathSize) {
        SDL_SetError("[SDL_Libretro] Save path is too long: %s", file);
        return NULL;
    }
    return SDL_IOFromFile(tempPath, "wb");
}
 
static bool SDL_Libretro_CommitSaveFile(SDL_IOStream* io, bool written, const char* tempPath, const char* file) {
    // Writers like SDL_IOprintf() don't all report failures, but the stream
    // remembers them; and closing flushes, so a full disk can fail there too.
    bool ok = written && SDL_GetIOStatus(io) != SDL_IO_STATUS_ERROR;
    ok = SDL_CloseIO(io) && ok;
    if (ok && !SDL_RenamePath(tempPath, file)) {
        ok = false;
    }
    if (!ok) {
        SDL_RemovePath(tempPath);
    }
    return ok;
}
 
// Disk Control
 
unsigned SDL_Libretro_GetDiskCount(const SDL_Libretro* lr) {
    if (!SDL_Libretro_IsGameReady(lr) || !lr->core.disk_control.get_num_images) return 0;
    return lr->core.disk_control.get_num_images();
}
 
unsigned SDL_Libretro_GetDiskIndex(const SDL_Libretro* lr) {
    if (!SDL_Libretro_IsGameReady(lr) || !lr->core.disk_control.get_image_index) return 0;
    return lr->core.disk_control.get_image_index();
}
 
bool SDL_Libretro_SetDiskIndex(SDL_Libretro* lr, unsigned index) {
    if (!SDL_Libretro_IsGameReady(lr) || !lr->core.disk_control.set_image_index) {
        SDL_SetError("[SDL_Libretro] Disk control not available");
        return false;
    }
    if (!lr->core.disk_control.get_eject_state || !lr->core.disk_control.get_eject_state()) {
        SDL_SetError("[SDL_Libretro] Disk tray must be ejected before changing index");
        return false;
    }
    return lr->core.disk_control.set_image_index(index);
}
 
bool SDL_Libretro_EjectDisk(SDL_Libretro* lr) {
    if (!SDL_Libretro_IsGameReady(lr) || !lr->core.disk_control.set_eject_state) {
        SDL_SetError("[SDL_Libretro] Disk control not available");
        return false;
    }
    return lr->core.disk_control.set_eject_state(true);
}
 
bool SDL_Libretro_InsertDisk(SDL_Libretro* lr) {
    if (!SDL_Libretro_IsGameReady(lr) || !lr->core.disk_control.set_eject_state) {
        SDL_SetError("[SDL_Libretro] Disk control not available");
        return false;
    }
    return lr->core.disk_control.set_eject_state(false);
}
 
static void SDL_Libretro_FreeDiskImages(SDL_Libretro* lr) {
    if (!lr) return;
    for (unsigned i = 0; i < lr->core.diskImageCount; i++) {
        SDL_LibretroDiskImage* image = &lr->core.diskImages[i];
        if (image->temp && image->path) {
            SDL_RemovePath(image->path);
        }
        SDL_free(image->path);
        SDL_free(image->data);
    }
    SDL_free(lr->core.diskImages);
    lr->core.diskImages = NULL;
    lr->core.diskImageCount = 0;
}
 
static bool SDL_Libretro_CanAddDiskImage(SDL_Libretro* lr) {
    if (!lr->core.disk_control.add_image_index || !lr->core.disk_control.replace_image_index || !lr->core.disk_control.get_num_images) {
        SDL_SetError("[SDL_Libretro] Disk control not available");
        return false;
    }
    if (!lr->core.disk_control.get_eject_state || !lr->core.disk_control.get_eject_state()) {
        SDL_SetError("[SDL_Libretro] Disk tray must be ejected before adding a disk image");
        return false;
    }
    return true;
}
 
static bool SDL_Libretro_AppendDiskImage(SDL_Libretro* lr, const struct retro_game_info* info) {
    unsigned before = lr->core.disk_control.get_num_images();
    if (!lr->core.disk_control.add_image_index()) {
        SDL_SetError("[SDL_Libretro] Core rejected add_image_index");
        return false;
    }
    unsigned count = lr->core.disk_control.get_num_images();
    if (count == 0 || count <= before) {
        SDL_SetError("[SDL_Libretro] Core reported no new disk image after add");
        return false;
    }
    if (!lr->core.disk_control.replace_image_index(count - 1, info)) {
        lr->core.disk_control.replace_image_index(count - 1, NULL);
        SDL_SetError("[SDL_Libretro] Core rejected the disk image");
        return false;
    }
    return true;
}
 
bool SDL_Libretro_AddDiskImage(SDL_Libretro* lr, const char* path) {
    if (!SDL_Libretro_IsGameReady(lr) || !path) {
        SDL_SetError("[SDL_Libretro] Invalid AddDiskImage arguments");
        return false;
    }
    if (!SDL_Libretro_CanAddDiskImage(lr)) {
        return false;
    }
    if (!SDL_Libretro_ContentNeedsFullpath(lr, SDL_Libretro_GetExtension(path))) {
        // The core wants the bytes; the stream loader reads and keeps them.
        SDL_IOStream* src = SDL_IOFromFile(path, "rb");
        if (!src) {
            SDL_SetError("[SDL_Libretro] Failed to open disk image '%s'", path);
            return false;
        }
        return SDL_Libretro_AddDiskImage_IO(lr, src, path, true);
    }
    struct retro_game_info info;
    SDL_memset(&info, 0, sizeof(info));
    info.path = path;
    return SDL_Libretro_AppendDiskImage(lr, &info);
}
 
bool SDL_Libretro_AddDiskImage_IO(SDL_Libretro* lr, SDL_IOStream* src, const char* path, bool closeio) {
    if (!SDL_Libretro_IsGameReady(lr) || !src || !path) {
        SDL_SetError("[SDL_Libretro] Invalid AddDiskImage_IO arguments");
        if (closeio && src) SDL_CloseIO(src);
        return false;
    }
    if (!SDL_Libretro_CanAddDiskImage(lr)) {
        if (closeio) SDL_CloseIO(src);
        return false;
    }
 
    // Make room to keep the image alive until the game unloads.
    SDL_LibretroDiskImage* images = (SDL_LibretroDiskImage*)SDL_realloc(lr->core.diskImages, (lr->core.diskImageCount + 1) * sizeof(SDL_LibretroDiskImage));
    if (!images) {
        if (closeio) SDL_CloseIO(src);
        return false;
    }
    lr->core.diskImages = images;
    SDL_LibretroDiskImage image = {0};
    struct retro_game_info info;
    SDL_memset(&info, 0, sizeof(info));
 
    // Read or spill the image before mutating the core's disk list, so a
    // failed read does not leave an empty slot behind.
    if (SDL_Libretro_ContentNeedsFullpath(lr, SDL_Libretro_GetExtension(path))) {
        char tempPath[SDL_LIBRETRO_MAX_PATH];
        if (!SDL_Libretro_SpillToTempFile(lr, src, path, closeio, tempPath, sizeof(tempPath))) {
            return false;
        }
        image.temp = true;
        image.path = SDL_strdup(tempPath);
        if (!image.path) {
            SDL_RemovePath(tempPath);
            return false;
        }
    }
    else {
        image.data = SDL_LoadFile_IO(src, &info.size, closeio);
        if (!image.data) return false;
        image.path = SDL_strdup(path);
        if (!image.path) {
            SDL_free(image.data);
            return false;
        }
    }
    info.path = image.path;
    info.data = image.data;
 
    if (!SDL_Libretro_AppendDiskImage(lr, &info)) {
        if (image.temp) SDL_RemovePath(image.path);
        SDL_free(image.path);
        SDL_free(image.data);
        return false;
    }
    lr->core.diskImages[lr->core.diskImageCount++] = image;
    return true;
}
 
bool SDL_Libretro_GetDiskLabel(const SDL_Libretro* lr, unsigned index, char* label, size_t len) {
    if (!SDL_Libretro_IsGameReady(lr) || !label || len == 0) {
        SDL_SetError("[SDL_Libretro] Invalid GetDiskLabel arguments");
        return false;
    }
    if (!lr->core.disk_control.get_image_label) {
        SDL_SetError("[SDL_Libretro] Disk labels not available");
        return false;
    }
    label[0] = '\0';
    return lr->core.disk_control.get_image_label(index, label, len);
}
 
bool SDL_Libretro_SetInitialDisk(SDL_Libretro* lr, unsigned index, const char* path) {
    if (!lr || !path) {
        SDL_SetError("[SDL_Libretro] Invalid SetInitialDisk arguments");
        return false;
    }
    if (!lr->core.disk_control.set_initial_image) {
        SDL_SetError("[SDL_Libretro] Disk control not available");
        return false;
    }
    return lr->core.disk_control.set_initial_image(index, path);
}
 
// Cheats
 
bool SDL_Libretro_SetCheat(SDL_Libretro* lr, unsigned index, bool enabled, const char* code) {
    if (!SDL_Libretro_IsGameReady(lr) || !code) {
        SDL_SetError("[SDL_Libretro] Invalid SetCheat arguments");
        return false;
    }
    lr->core.symbols.retro_cheat_set(index, enabled, code);
    return true;
}
 
void SDL_Libretro_ResetCheats(SDL_Libretro* lr) {
    if (!SDL_Libretro_IsGameReady(lr)) return;
    lr->core.symbols.retro_cheat_reset();
}
 
// Save States
 
size_t SDL_Libretro_GetStateSize(const SDL_Libretro* lr) {
    if (!SDL_Libretro_IsGameReady(lr)) 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 (!SDL_Libretro_IsGameReady(lr) || !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) {
                SDL_SetError("[SDL_Libretro] Failed to allocate save state buffer");
            }
            else {
                if (lr->core.symbols.retro_serialize(data, size)) {
                    // On a short write, SDL_WriteIO sets its own error.
                    ok = (SDL_WriteIO(dst, data, size) == size);
                }
                else {
                    SDL_SetError("[SDL_Libretro] Core failed to serialize state");
                }
                SDL_free(data);
            }
        }
    }
    if (closeio && dst) SDL_CloseIO(dst);
    return ok;
}
 
bool SDL_Libretro_SaveState(SDL_Libretro* lr, const char* file) {
    if (!SDL_Libretro_IsGameReady(lr) || !file) {
        SDL_SetError("[SDL_Libretro] Invalid SaveState arguments");
        return false;
    }
 
    char tempPath[SDL_LIBRETRO_MAX_PATH];
    SDL_IOStream* io = SDL_Libretro_OpenSaveFile(file, tempPath, sizeof(tempPath));
    if (!io) return false;
    return SDL_Libretro_CommitSaveFile(io, SDL_Libretro_SaveState_IO(lr, io, false), tempPath, file);
}
 
bool SDL_Libretro_LoadState_IO(SDL_Libretro* lr, SDL_IOStream* src, bool closeio) {
    if (!SDL_Libretro_IsGameReady(lr) || !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 = false;
    if (size == 0) {
        SDL_SetError("[SDL_Libretro] Save state is empty");
    }
    else if (!lr->core.symbols.retro_unserialize(data, size)) {
        SDL_SetError("[SDL_Libretro] Core rejected save state");
    }
    else {
        ok = true;
    }
    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 (!SDL_Libretro_IsGameReady(lr) || !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 (!SDL_Libretro_IsGameReady(lr) || !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) return;
    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 SDL_Libretro_IsGameReady(lr) ? 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 (!SDL_Libretro_IsGameReady(lr) || 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 (!SDL_Libretro_IsGameReady(lr)) 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;
 
    char tempPath[SDL_LIBRETRO_MAX_PATH];
    SDL_IOStream* io = SDL_Libretro_OpenSaveFile(file, tempPath, sizeof(tempPath));
    if (!io) return false;
    bool ok = SDL_Libretro_CommitSaveFile(io, SDL_Libretro_SaveMemory_IO(lr, memoryType, io, false), tempPath, file);
    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)
 
void SDL_Libretro_SetSRAMAutoSave(SDL_Libretro* lr, bool enabled) {
    if (lr) lr->sramAutoSave = enabled;
}
 
bool SDL_Libretro_GetSRAMAutoSave(const SDL_Libretro* lr) {
    return lr && lr->sramAutoSave;
}
 
static void SDL_Libretro_AutoLoadSRAM(SDL_Libretro* lr) {
    char path[SDL_LIBRETRO_MAX_PATH];
    if (!lr->sramAutoSave || SDL_Libretro_GetSavePath(lr, ".srm", path, sizeof(path)) == 0 || !SDL_GetPathInfo(path, NULL)) return;
    if (!SDL_Libretro_LoadSRAM(lr, path)) {
        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[SDL_Libretro] Failed to load SRAM: %s", SDL_GetError());
    }
}
 
static void SDL_Libretro_AutoSaveSRAM(SDL_Libretro* lr) {
    char path[SDL_LIBRETRO_MAX_PATH];
    if (!lr->sramAutoSave || !lr->core.gameLoaded || SDL_Libretro_GetSavePath(lr, ".srm", path, sizeof(path)) == 0) return;
    if (!SDL_Libretro_SaveSRAM(lr, path)) {
        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[SDL_Libretro] Failed to save SRAM: %s", SDL_GetError());
    }
}
 
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 */
 
static bool SDL_Libretro_RewindAllocate(SDL_Libretro* lr) {
    size_t slotSize = lr->core.symbols.retro_serialize_size();
    if (slotSize == 0) {
        SDL_SetError("[SDL_Libretro] Core does not support serialization");
        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(lr->rewindCapacity, 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");
        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->rewindHead = 0;
    lr->rewindCount = 0;
    lr->rewindFrameCounter = 0;
    lr->rewindHasReference = false;
    lr->rewindActive = false;
    return true;
}
 
bool SDL_Libretro_SetRewindEnabled(SDL_Libretro* lr, bool enabled, unsigned bufferFrames, unsigned captureInterval) {
    if (!lr) {
        return SDL_InvalidParamError("lr");
    }
 
    SDL_Libretro_RewindFree(lr);
 
    if (!enabled) {
        lr->rewindEnabled = false;
        // Without rewind a negative speed would leave the game stuck.
        if (lr->core.speed < 0.0f) {
            SDL_Libretro_SetSpeed(lr, 1.0f);
        }
        return true;
    }
 
    // Sane defaults.
    if (bufferFrames == 0) bufferFrames = 300;
    if (captureInterval == 0) captureInterval = 1;
 
    lr->rewindEnabled = true;
    lr->rewindCapacity = bufferFrames;
    lr->rewindCaptureInterval = captureInterval;
 
    // The serialize size is only defined while a game is loaded, so the
    // buffer waits for one.
    if (!SDL_Libretro_IsGameReady(lr)) {
        return true;
    }
    return SDL_Libretro_RewindAllocate(lr);
}
 
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 SDL_InvalidParamError("lr");
    }
    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 && SDL_Libretro_IsCoreReady(lr) && 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) return;
 
    // Some cores report no state size until they've run a frame
    // (RETRO_SERIALIZATION_QUIRK_MUST_INITIALIZE), so allocate once they do.
    if (!lr->rewindReference) {
        if (lr->core.symbols.retro_serialize_size() == 0 || !SDL_Libretro_RewindAllocate(lr)) 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 (!SDL_Libretro_IsGameReady(lr) || !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 */