Главная страница>Связанные с программированием>Исходный код С#
Скачать
rres


rres — это простой и удобный в использовании формат файла для упаковки ресурсов.

rres был разработан для упаковки игровых ресурсов (изображений, шрифтов, текста, аудио, моделей...) в простой автономный комплексный формат, удобный для чтения и записи, предназначенный для быстрой и эффективной загрузки данных.

rres создан на основе следующих форматов файлов: XNB (используется XNA/MonoGame), RIFF, PNG и ZIP.



Индекс

  1. Цели дизайна
  2. Преимущества использования
  3. История дизайна
  4. Структура файла
  5. Заголовок файла: rresFileHeader
  6. Чанк ресурса: rresResourceChunk
    1. Информация о чане ресурса: rresResourceChunkInfo
    2. Данные фрагмента ресурса: rresResourceChunkData
    3. Тип данных ресурса: rresResourceDataType
    4. Чанк ресурса: Центральный каталог: rresCentralDir
  7. Реализация пользовательского движка
  8. Лицензия

Цели дизайна

  • Простота : структура rres проста: один заголовок файла и несколько ресурсов один за другим. Тем не менее, каждый ресурс имеет небольшой (32 байта) заголовок информации о ресурсе с несколькими доступными опциями.

  • Простота использования : библиотека rres для чтения файлов .rres небольшая и содержит только минимально необходимый набор функций для чтения данных ресурса по ее идентификатору. Он использует лишь небольшой набор функций из стандартной библиотеки C. Инструмент rrespacker с графическим интерфейсом пользователя/CLI позволяет легко создавать и просматривать файлы .rres .

  • Гибкость : формат rres поддерживает любой тип входного файла; если данные не классифицируются как базовый тип данных, их можно просто упаковать как необработанные данные файла.

  • Переносимость : формат файла rres не привязан к конкретному движку, базовая библиотека просто считывает данные ресурса как упакованные, и эти данные могут быть сопоставлены с любыми структурами движка. Пример использования предоставлен со вспомогательной библиотекой rres-raylib.h , которая сопоставляет данные rres со структурами raylib.

  • Безопасность : rres поддерживает сжатие и шифрование каждого ресурса, если это необходимо. Тем не менее, несмотря на поддержку, обеспечиваемую форматом файла, пользователь должен реализовать ее в инструменте упаковщика rres и библиотеке сопоставления движка. rres не требует какого-либо конкретного алгоритма сжатия/шифрования по своей конструкции

  • Расширяемость : формат файла rres является расширяемым, поддерживает новые типы данных, новые функции и пользовательские данные, если это необходимо.

  • Бесплатный и открытый исходный код : rres — это открытая спецификация и бесплатная библиотека с открытым исходным кодом. Его можно использовать с предоставленным инструментом ( rrespacker ) или можно реализовать собственный упаковщик/загрузчик для любого движка . Описание формата также можно использовать в качестве учебного материала для всех, кто хочет создать свой собственный формат файла упаковки данных.

Преимущества использования

Есть несколько важных причин упаковывать данные игровых ресурсов в такой формат, как rres , и вот несколько веских причин это сделать.

  • Организация : избегайте тысяч файлов, распределенных в сотнях каталогов в финальной сборке игры. Все данные игровых файлов могут быть организованы в один или несколько файлов .rres . Он сохраняет каталог игры чистым и хорошо структурированным.

  • Производительность : хранение всех необходимых файлов для уровня/карты в одном файле .rres снижает потребность в дескрипторах файлов для доступа к нескольким файлам; дескрипторы файлов являются ресурсом ОС и стоимость открытия файла немалая, это может привести к задержкам в игре. Время доступа к данным внутри файла .rres также важно, и в зависимости от того, как организованы файлы, это также может сократить время загрузки.

  • Безопасность : избегайте предоставления всех игровых ресурсов непосредственно пользователю для легкого копирования или изменения. Большинству пользователей будет сложнее извлечь и изменить данные, упакованные в файл .rres ; защитите свои игровые ресурсы, защищенные авторским правом. rres также поддерживает сжатие и шифрование данных для каждого ресурса, добавляя при необходимости дополнительный уровень безопасности.

  • Время загрузки . Если к данным необходимо получить доступ с сервера и загрузить их, ресурсы, упакованные в один или несколько файлов .rres , сокращают время загрузки по сравнению с загрузкой каждого файла по отдельности.

История дизайна

rres находится в разработке с 2014 года . Я начал этот проект с целью создать формат файла упаковки, аналогичный XNB, для raylib. За последние 8 лет проект претерпел множество изменений и улучшений в процессе изучения форматов файлов. За это время я реализовал загрузчики/записатели для более чем 20 различных форматов файлов , а также создал +12 пользовательских форматов файлов для нескольких пользовательских инструментов raylibtech.

Формат файла rres претерпел как минимум 4 больших изменения :

  • Первый дизайн формата ограничивался упаковкой одного ресурса за другим, каждый ресурс состоял из одного информационного заголовка ресурса, за которым следовал фиксированный набор из четырех возможных параметров и данных ресурса. Вместе с файлом .rres был создан заголовочный файл .h , в котором определяется rresId с именем файла ресурса (обычно исходное имя файла необработанных данных). Эта модель была довольно простой и интуитивно понятной, но у нее есть несколько важных недостатков: она не учитывала сложные фрагменты данных, которые могли потребовать нескольких фрагментов, и не было возможности извлечь/получить исходные исходные файлы (или аналогичные).

  • Второй проект был намного сложнее и пытался устранить недостатки первого дизайна. Во втором варианте каждый ресурс может включать в себя несколько фрагментов данных в своего рода древовидной структуре. На самом деле этот дизайн был похож на формат файла RIFF: каждый фрагмент мог содержать дополнительные фрагменты, каждый со своим заголовком и данными. Также были добавлены некоторые дополнительные параметры ресурсов, но формат стал довольно сложным для понимания и управления. Наконец, от тестовой реализации отказались и начали исследовать более простую альтернативу.

  • Третий дизайн представлял собой возврат к первому дизайну: простота, но сохранение некоторых опций для отдельных ресурсов. Проблема создания нескольких ресурсов из одного входного файла была решена с помощью простого поля смещения в заголовке информации о ресурсе, указывающего при необходимости на следующий связанный ресурс. Ресурсы загружались как массив фрагментов ресурсов. Был добавлен дополнительный фрагмент ресурса Центрального каталога для хранения ссылок на входные файлы. Формат был хорош, но он по-прежнему требовал реализации и дальнейшего исследования, он должен был быть независимым от движка и по-прежнему зависеть от структур и функциональности raylib.

  • В ходе реализации был выполнен четвертый дизайн , почти все структуры и поля были пересмотрены и переименованы для обеспечения единообразия и простоты. Была создана отдельная библиотека ( rres-raylib.h ) для сопоставления данных загруженных ресурсов с пользовательскими типами данных библиотеки/движка. Любая зависимость от raylib была удалена, что сделало его полностью независимым от движка форматом файлов. Было реализовано несколько примеров использования raylib, чтобы проиллюстрировать соединение библиотеки с движком rres , а также реализовано несколько типов загрузки ресурсов. Инструмент rrespacker был создан с нуля для создания файлов rres . Он поддерживает приятный графический интерфейс с поддержкой перетаскивания, а также мощную командную строку для пакетной обработки. Реализация сжатия и шифрования была перенесена в реализацию пользовательской библиотеки, чтобы соответствовать инструменту упаковки и сделать формат файла rres более чистым и простым.

Это был 8-летний проект , над которым мы работали время от времени, со многими изменениями и изменениями, но лично я очень доволен конечным результатом. rres — это формат файла упаковки ресурсов на уровне любого формата пакета профессионального движка , НО бесплатный и с открытым исходным кодом , доступный любому разработчику игр, который хочет его использовать, реализовать или создать собственную версию.

Структура файла

Формат файла rres состоит из заголовка файла ( rresFileHeader ), за которым следует несколько фрагментов ресурсов ( rresResourceChunk ). Каждый фрагмент ресурса имеет заголовок информации о ресурсе ( rresResourceChunkInfo ), который включает в себя код типа данных FOURCC и информацию о данных ресурса. Данные ресурса ( rresResourceChunkData ) содержат небольшой набор свойств для идентификации данных в зависимости от типа и могут содержать некоторые дополнительные данные в конце.

Рис. 01. Файловая структура rres v1.0.

ПРИМЕЧАНИЕ. rresResourceChunk(ы) генерируются из входных файлов. Важно отметить, что ресурсы не могут быть сопоставлены с файлами 1:1, один входной файл может генерировать несколько фрагментов ресурсов. Например, входной файл .ttf может генерировать фрагмент ресурса изображения (тип RRES_DATA_IMAGE ) плюс фрагмент информационного ресурса глифа шрифта (тип RRES_DATA_FONT_GLYPHS ). 

 rresFileHeader               ( 16 bytes )
    Signature Id              ( 4 bytes )     // File signature id: 'rres'
    Version                   ( 2 bytes )     // Format version
    Resource Count            ( 2 bytes )     // Number of resource chunks contained
    CD Offset                 ( 4 bytes )     // Central Directory offset (if available)
    Reserved                  ( 4 bytes )     // 

rresResourceChunk []
{
    rresResourceChunkInfo    ( 32 bytes )
        Type                  ( 4 bytes )     // Resource type (FourCC)
        Id                    ( 4 bytes )     // Resource identifier (CRC32 filename hash or custom)
        Compressor            ( 1 byte )      // Data compression algorithm
        Cipher                ( 1 byte )      // Data encryption algorithm
        Flags                 ( 2 bytes )     // Data flags (if required)
        Packed data Size      ( 4 bytes )     // Packed data size (compressed/encrypted + custom data appended)
        Base data Size        ( 4 bytes )     // Base data size (uncompressed/unencrypted)
        Next Offset           ( 4 bytes )     // Next resource chunk offset (if required)
        Reserved              ( 4 bytes )     // 
        CRC32                 ( 4 bytes )     // Resource Chunk Data CRC32
                             
    rresResourceChunkData     ( n bytes )     // Packed data
        Property Count        ( 4 bytes )     // Number of properties contained
        Properties []          ( 4 * i bytes )   // Resource data required properties, depend on Type
        Data                  ( m bytes )     // Resource data
}

Заголовок файла: rresFileHeader

Следующая структура C определяет rresFileHeader : 

 // rres file header (16 bytes)
typedef struct rresFileHeader {
    unsigned char id [ 4 ];            // File identifier: rres
    unsigned short version ;         // File version: 100 for version 1.0
    unsigned short chunkCount ;      // Number of resource chunks in the file (MAX: 65535)
    unsigned int cdOffset ;          // Central Directory offset in file (0 if not available)
    unsigned int reserved ;          // 
} rresFileHeader ;
Поле Описание
id Идентификатор подписи файла, он должен состоять из четырех символов: r , r , e , s .
version Определяет версию и подверсию формата.
chunkCount Количество блоков ресурсов, присутствующих в файле. Обратите внимание, что оно может превышать количество обработанных входных файлов.
cdOffset Абсолютное смещение центрального каталога внутри файла. Обратите внимание, что CDIR — это просто еще один тип фрагмента ресурса, центральный каталог может присутствовать в файле или нет . Рекомендуется размещать его в качестве последнего фрагмента файла, если реализован собственный упаковщик rres . Более подробную информацию можно найти в разделе rresCentralDir .
reserved Это поле зарезервировано для будущих дополнений, если потребуется.

Таблица 01. Описание и подробности полей rresFileHeader

Соображения:

  • Файлы rres по своей конструкции ограничены максимум 65535 фрагментами ресурсов . В случае необходимости упаковки большего количества ресурсов рекомендуется создать несколько файлов rres .
  • Файлы rres используют 32-битные смещения для адресации различных фрагментов ресурсов, следовательно, можно адресовать не более ~ 4 ГБ данных , пожалуйста, сохраняйте файлы rres меньше 4 ГБ . Если для упаковки ресурсов требуется больше места, создайте несколько файлов rres .

Чанк ресурса: rresResourceChunk

Файл rres содержит несколько фрагментов ресурсов. Каждый фрагмент ресурса представляет собой автономный пакет данных. Фрагменты ресурсов генерируются из входных файлов при создании файла rres с помощью инструмента упаковщика rres ; В зависимости от расширения файла инструмент упаковщика rres извлекает необходимые данные из файла и генерирует один или несколько фрагментов ресурсов. Например, для файла изображения создается фрагмент ресурса type RRES_DATA_IMAGE содержащий только данные пикселей изображения и необходимые свойства для чтения этих данных обратно из файла ресурсов.

Важно отметить, что один входной файл может генерировать несколько фрагментов ресурсов при создании файла rres . Например, входной файл .ttf может генерировать фрагмент ресурса RRES_DATA_IMAGE плюс фрагмент ресурса RRES_DATA_FONT_GLYPHS ; также возможно просто упаковать файл как обычный тип фрагмента ресурса RRES_DATA_RAW , в этом случае входной файл не обрабатывается, а просто упаковывается как необработанные данные.

При создании rres упаковщик rres может создать дополнительный фрагмент ресурса типа RRES_DATA_DIRECTORY содержащий данные об обработанных входных файлах. В некоторых случаях это может быть полезно, например, чтобы связать имя входного файла непосредственно с идентификатором сгенерированного ресурса (ресурсов), а также извлечь данные в файловую структуру, аналогичную исходной входной.

Каждый фрагмент ресурса разделен на две части: rresResourceChunkInfo + rresResourceData .

Информация о чане ресурса: rresResourceChunkInfo

Следующая структура C определяет rresResourceChunkInfo : 

 // rres resource chunk info header (32 bytes)
typedef struct rresResourceChunkInfo {
    unsigned char type [ 4 ];          // Resource chunk type (FourCC)
    unsigned int id ;                // Resource chunk identifier (generated from filename CRC32 hash)
    unsigned char compType ;         // Data compression algorithm
    unsigned char cipherType ;       // Data encription algorithm
    unsigned short flags ;           // Data flags (if required)
    unsigned int packedSize ;        // Data chunk size (compressed/encrypted + custom data appended)
    unsigned int baseSize ;          // Data base size (uncompressed/unencrypted)
    unsigned int nextOffset ;        // Next resource chunk global offset (if resource has multiple chunks)
    unsigned int reserved ;          // 
    unsigned int crc32 ;             // Data chunk CRC32 (propCount + props[] + data)
} rresResourceChunkInfo ;
Поле Описание
type Код FourCC , идентифицирующий тип данных ресурса, содержащихся в rresResourceChunkData . Enum rresResourceDataType определяет несколько типов данных, при необходимости можно добавить новые.
id Глобальный идентификатор ресурса. Он генерируется из входного имени файла с использованием хеша CRC32 и не уникален. Один входной файл может генерировать несколько фрагментов ресурсов, все сгенерированные фрагменты имеют один и тот же идентификатор и загружаются вместе при загрузке ресурса. Например, входной .ttf может генерировать два фрагмента ресурса ( RRES_DATA_IMAGE + RRES_DATA_FONT_GLYPHS ) с одним и тем же идентификатором, которые будут загружены вместе при запросе их идентификатора. Пользователь сам решает, что делать с загруженными данными.
compType Определяет алгоритм сжатия, используемый для данных фрагмента ресурса. Сжатие зависит от промежуточной библиотеки между rres и движком, rres.h просто определяет некоторые полезные значения алгоритма, которые будут использоваться в случае реализации сжатия. Сжатие всегда должно применяться перед шифрованием, и оно сжимает полный rresResourceData ( Property Count + Properties[] + Data ). Если шифрование данных не применяется, packedSize определяет размер сжатых данных.
cipherType Определяет алгоритм шифрования, используемый для данных фрагмента ресурса. Как и сжатие, шифрование зависит от промежуточной библиотеки между rres и движком, rres.h просто определяет некоторые полезные значения алгоритма, которые будут использоваться в случае реализации шифрования. Шифрование должно применяться после сжатия. В зависимости от алгоритма шифрования и режима шифрования может потребоваться присоединение к данным ресурса какой-то дополнительной части данных (например, MAC-адрес шифрования), это зависит от реализации, и за это отвечает инструмент упаковщика rres / промежуточная библиотека rres для механизмов. дополнительные данные. Рекомендуется просто добавить его к данным ресурса и учесть в packedSize .
flags Зарезервировано для дополнительных флагов, если они необходимы для реализации.
packedSize Определяет упакованный размер (сжатый/зашифрованный + дополнительные пользовательские данные) rresResourceChunkData . Упакованные данные могут содержать добавленные пользовательские данные в конце после сжатых/зашифрованных данных, например nonce/MAC для зашифрованных данных, но это зависит от реализации, управляется инструментом упаковщика rres и пользовательской библиотекой для загрузки фрагментов данных в целевые структуры двигателя.
baseSize Определяет базовый размер (несжатый/незашифрованный) rresResourceChunkData .
nextOffset Определяет глобальный адрес позиции файла для следующего связанного фрагмента ресурса. Это полезно для входных файлов, которые генерируют несколько ресурсов, таких как шрифты или сетки.
reserved Это поле зарезервировано для будущих дополнений, если потребуется.
crc32 Рассчитывается по всему фрагменту rresResourceData ( packedSize ) и предназначено для обнаружения ошибок повреждения данных.

Таблица 02. Описание и подробности полей rresResourceChunkInfo

Данные фрагмента ресурса: rresResourceChunkData

rresResourceChunkData содержит следующие данные:

  • Property Count : количество содержащихся свойств зависит от type ресурса.
  • Properties[] : обязательные свойства данных ресурса, зависят от type ресурса.
  • Data : необработанные данные ресурса, зависят от type ресурса.

ПРИМЕЧАНИЕ. rresResourceChunkData может содержать дополнительные пользовательские данные, в этих случаях дополнительный размер данных должен учитываться в packedSize .

Тип данных ресурса: rresResourceDataType

type ресурса, указанный в rresResourceChunkInfo определяет тип данных и количество свойств, содержащихся в фрагменте ресурса.

Здесь указаны определенные в настоящее время типы данных. Обратите внимание, что некоторые входные файлы могут генерировать несколько фрагментов ресурсов разных типов. При необходимости могут быть добавлены дополнительные типы ресурсов. 

 // rres resource chunk data type
// NOTE 1: Data type determines the properties and the data included in every chunk
// NOTE 2: This enum defines the basic resource data types, some input files could generate multiple resource chunks
typedef enum rresResourceDataType {

    RRES_DATA_NULL         = 0 ,     // FourCC: NULL - Reserved for empty chunks, no props/data
    RRES_DATA_RAW          = 1 ,     // FourCC: RAWD - Raw file data, input file is not processed, just packed as is
    RRES_DATA_TEXT         = 2 ,     // FourCC: TEXT - Text file data, byte data extracted from text file
    RRES_DATA_IMAGE        = 3 ,     // FourCC: IMGE - Image file data, pixel data extracted from image file
    RRES_DATA_WAVE         = 4 ,     // FourCC: WAVE - Audio file data, samples data extracted from audio file
    RRES_DATA_VERTEX       = 5 ,     // FourCC: VRTX - Vertex file data, extracted from a mesh file
    RRES_DATA_FONT_GLYPHS  = 6 ,     // FourCC: FNTG - Font glyphs info, generated from an input font file
    RRES_DATA_LINK         = 99 ,    // FourCC: LINK - External linked file, filepath as provided on file input
    RRES_DATA_DIRECTORY    = 100 ,   // FourCC: CDIR - Central directory for input files relation to resource chunks
    
    // TODO: Add additional data types if required
    
} rresResourceDataType ;

Определенные в настоящее время types данных состоят из следующих свойств и данных:

тип ресурса ЧетыреCC реквизитCount реквизит данные
RRES_DATA_NULL NULL 0 - -
RRES_DATA_RAW RAWD 4 props[0] :размер
props[1] : extension01
props[2] : extension02
props[3] : зарезервировано		 необработанные байты файла
RRES_DATA_TEXT TEXT 4 props[0] :размер
props[1] : rresTextEncoding
props[2] : rresCodeLang
props[3] :culturalCode		 текстовые данные
RRES_DATA_IMAGE IMGE 4 props[0] : ширина
props[1] :высота
props[2] : rresPixelFormat
props[3] :mipmaps		 данные пикселей
RRES_DATA_WAVE WAVE 4 props[0] :frameCount
props[1] :sampleRate
props[2] :sampleSize
props[3] :каналы		 данные аудиосэмплов
RRES_DATA_VERTEX VRTX 4 props[0] :vertexCount
props[1] : rresVertexAttribute
props[2] :comComponentCount
props[3] : rresVertexFormat		 данные вершин
RRES_DATA_FONT_GLYPHS FNTG 4 props[0] :baseSize
props[1] :glyphCount
props[2] :glyphPadding
props[3] : rresFontStyle		 rresFontGlyphInfo[0..glyphCount]
RRES_DATA_LINK LINK 1 props[0] :размер данные пути к файлу
RRES_DATA_DIRECTORY CDIR 1 props[0] :entryCount rresDirEntry[0..entryCount]

Таблица 03. Определенные значения и сведения rresResourceDataType

ПРИМЕЧАНИЕ. RRES_DATA_RAW содержит расширение упакованного файла как часть своих свойств, расширение char преобразуется в 4-байтовое значение unsigned int с прямым порядком байтов, начинающееся с точки. т.е. ".png" => 0x2e706e67 . Если расширение не имеет значения, пользовательская реализация может решить установить для этих свойств значение 0 .

rres.h определяет следующие enums для удобства назначения некоторых свойств:

  • rresTextEncoding : определяет несколько возможных кодировок текста, значение по умолчанию — 0 (UTF-8).
  • rresCodeLang : определяет несколько языков программирования, что полезно в случае встраивания файлов кода или скриптов.
  • rresPixelFormat : определяет несколько значений формата пикселей для данных пикселей изображения.
  • rresVertexAttribute : для удобства определяет несколько типов атрибутов вершин.
  • rresVertexFormat : определяет несколько форматов данных вершин.
  • rresFontStyle : определяет несколько стилей шрифта (обычный, жирный, курсив...), значение по умолчанию — 0 ( RRES_FONT_STYLE_DEFAULT ).

Чанк ресурса: Центральный каталог: rresCentralDir

Блок ресурсов Central Directory — это специальный фрагмент, который может присутствовать или отсутствовать в файле rres . Он хранит информацию о входных файлах, обработанных для создания нескольких фрагментов ресурсов, и может быть полезен для:

  • Ссылайтесь на ресурсы по исходному имени файла. Это очень полезно с точки зрения реализации, чтобы свести к минимуму необходимые изменения кода, если упаковка rres выполняется поверх существующего проекта или в конце разработки проекта, если загрузка всех файлов выполнялась напрямую с использованием имен файлов.

  • Извлеките некоторые ресурсы в аналогичный входной файл. Это будет возможно только в том случае, если входной файл не был обработан деструктивным способом. Например, если файл .ttf был обработан для создания атласа изображения глифов + информации о данных глифов, получить исходный файл .ttf будет невозможно.

rres предоставляет несколько полезных структур для работы с данными фрагментов ресурсов Central Directory : 

 // rres central directory entry
typedef struct rresDirEntry {
    unsigned int id ;                // Resource id
    unsigned int offset ;            // Resource global offset in file
    unsigned int reserved ;          // reserved
    unsigned int fileNameSize ;      // Resource fileName size (NULL terminator and 4-byte alignment padding considered)
    char fileName [ RRES_MAX_CDIR_FILENAME_LENGTH ];  // Resource original fileName (NULL terminated and padded to 4-byte alignment)
} rresDirEntry ;

// rres central directory
// NOTE: This data represents the rresResourceChunkData
typedef struct rresCentralDir {
    unsigned int count ;             // Central directory entries count
    rresDirEntry * entries ;          // Central directory entries
} rresCentralDir ;

ПРИМЕЧАНИЕ. Записи имен файлов Центрального каталога выравниваются по 4-байтовому заполнению, чтобы сократить время доступа к файлам.

rres.h предоставляет функцию для загрузки Central Directory из файла rres , если он доступен: rresLoadCentralDirectory() , а также функцию для получения идентификаторов ресурса из его исходного имени файла: rresGetIdFromFileName() .

В случае, если файл rres создается без Central Directory , необходимо предоставить вторичный файл заголовка ( .h ) со ссылками на идентификаторы для всех ресурсов, которые будут использоваться в пользовательском коде.

Реализация пользовательского движка

rres разработан как независимый от движка формат файла , который можно использовать с любым игровым движком. Разработчики, использующие rres могут реализовать специальную библиотеку и пользовательскую абстракцию для сопоставления общих данных rres с собственными структурами данных механизмов , а также с пользовательскими инструментами упаковки rres .

На следующей диаграмме показан пример реализации rres для библиотеки raylib .

Рис. 02. Пример реализации rres: пользовательские библиотеки движка и инструмент.

Реализация rres состоит из нескольких частей:

  • Базовая библиотека: rres.h
  • Библиотека сопоставления движка: rres-raylib.h
  • Инструмент для упаковки: rrespacker

Базовая библиотека: rres.h

Базовая библиотека rres отвечает за чтение фрагментов ресурсов файлов rres в общую структуру ресурсов, возвращаемую пользователю. Структура ресурсов, предоставляемая пользователю, rresResourceChunk соответствует структуре спецификаций rres ( rresResourceChunkInfo + rresResourceChunkData ). Предусмотрены следующие структуры:

  • rresResourceChunk содержит один фрагмент с необходимой пользователю информацией и данными: rresResourceChunkInfo + rresResourceChunkData
  • rresresourceChunkInfo содержит информацию о загруженном фрагменте ресурса.
  • rresResourceChunkData содержит фактические данные о ресурсе: необходимые свойства и необработанные данные. Важно отметить, что в случае, если данные были сжаты/зашифрованы, обработка этих данных должна осуществляться пользовательской библиотекой ( rres-raylib.h ); в этих случаях chunk.data.raw содержит сжатые/зашифрованные данные и chunk.data.propCount = 0 и chunk.data.props = NULL ; пользовательская библиотека должна заполнять свойства после распаковки/дешифрования.
  • rresResourceMulti содержит несколько rresResourceChunks для обработанного входного файла. 
 // rres resource chunk
typedef struct rresResourceChunk {
    rresResourceChunkInfo info ;     // Resource chunk info
    rresResourceChunkData data ;     // Resource chunk packed data, contains propCount, props[] and raw data
} rresResourceChunk ;

// rres resource chunk info header (32 bytes)
typedef struct rresResourceChunkInfo {
    unsigned char type [ 4 ];          // Resource chunk type (FourCC)
    unsigned int id ;                // Resource chunk identifier (generated from filename CRC32 hash)
    unsigned char compType ;         // Data compression algorithm
    unsigned char cipherType ;       // Data encription algorithm
    unsigned short flags ;           // Data flags (if required)
    unsigned int packedSize ;        // Data chunk size (compressed/encrypted + custom data appended)
    unsigned int baseSize ;          // Data base size (uncompressed/unencrypted)
    unsigned int nextOffset ;        // Next resource chunk global offset (if resource has multiple chunks)
    unsigned int reserved ;          // 
    unsigned int crc32 ;             // Data chunk CRC32 (propCount + props[] + data)
} rresResourceChunkInfo ;

// rres resource chunk data
typedef struct rresResourceChunkData {
    unsigned int propCount ;         // Resource chunk properties count
    unsigned int * props ;            // Resource chunk properties
    void * raw ;                      // Resource chunk raw data
} rresResourceChunkData ;

// rres resource multi
// NOTE: It supports multiple resource chunks
typedef struct rresResourceMulti {
    unsigned int count ;             // Resource chunks count
    rresResourceChunk * chunks ;      // Resource chunks
} rresResourceMulti ;

Один rresResourceChunk можно загрузить из файла .rres с помощью предоставленной функции: rresLoadResourceChunk() и выгрузить с помощью rresUnloadResourceChunk() .

Полный rresResourceMulti можно загрузить из файла .rres с помощью предоставленной функции: rresLoadResourceMulti() и выгрузить с помощью rresUnloadResourceMulti() .

Библиотека сопоставления движка: rres-raylib.h

Библиотека сопоставления включает rres.h и предоставляет функциональные возможности для сопоставления данных фрагментов ресурсов, загруженных из файла rres , в структуры raylib . Предоставляемый API прост и интуитивно понятен и соответствует соглашениям raylib : 

 RLAPI void * LoadDataFromResource ( rresResourceChunk chunk , int * size );   // Load raw data from rres resource chunk
RLAPI char * LoadTextFromResource ( rresResourceChunk chunk );              // Load text data from rres resource chunk
RLAPI Image LoadImageFromResource ( rresResourceChunk chunk );             // Load Image data from rres resource chunk
RLAPI Wave LoadWaveFromResource ( rresResourceChunk chunk );               // Load Wave data from rres resource chunk
RLAPI Font LoadFontFromResource ( rresResourceMulti multi );               // Load Font data from rres resource multiple chunks
RLAPI Mesh LoadMeshFromResource ( rresResourceMulti multi );               // Load Mesh data from rres resource multiple chunks

RLAPI int UnpackResourceChunk ( rresResourceChunk * chunk );                // Unpack resource chunk data (decompres/decrypt data)
RLAPI void SetBaseDirectory ( const char * baseDir );                       // Set base directory for externally linked data

Обратите внимание, что в этой пользовательской библиотеке реализована распаковка/дешифрование данных, пользователям предоставляется UnpackResourceChunk() . Для удобства rresResourceChunk содержит значения идентификаторов компрессора/шифра. Поддержка компрессоров и шифров зависит от пользовательской реализации и должна быть согласована с инструментом упаковки ( rrespacker ).

Формат файла rres не зависит от движка, библиотеки и инструменты могут быть созданы для любого движка/фреймворка на любом языке программирования.

Инструмент для упаковки: rrespacker

rrespacker — это инструмент упаковки rres , отвечающий за обработку всех входных файлов и создание файла rres в соответствии со спецификацией. Если поддерживаются некоторые алгоритмы сжатия/шифрования, они должны быть реализованы этим инструментом, и те же алгоритмы должны поддерживаться библиотекой сопоставления, в нашем случае rres-raylib.h .

Рис. 03. Инструмент rrespacker, графический интерфейс, он также поддерживает CLI для пакетной обработки.

rrespacker можно использовать онлайн (или загрузить) с itch.io.

Версии

  • rres v1.0 (12 мая 2022 г.) — первый выпуск спецификации.

Лицензия

Спецификации формата файла rres , библиотека rres.h и библиотека rres-raylib.h лицензируются по лицензии MIT. Проверьте ЛИЦЕНЗИЮ для получения более подробной информации.

Copyright (c) 2014-2024 Рамон Сантамария (@raysan5)

Расширять
Дополнительная информация
Связанные приложения
Рекомендуем вам
Связанные новости Все