Page d'accueil>Lié à la programmation>Code source C#
Télécharger
rres


rres est un format de fichier simple et facile à utiliser pour empaqueter des ressources

rres a été conçu pour regrouper les ressources du jeu (images, polices, texte, audio, modèles...) dans un format simple et complet, facile à lire et à écrire, conçu pour charger des données de manière rapide et efficace.

rres s'inspire des formats de fichiers suivants : XNB (utilisé par XNA/MonoGame), RIFF, PNG et ZIP.



Indice

  1. Objectifs de conception
  2. Avantages d'utilisation
  3. Histoire de la conception
  4. Structure du fichier
  5. En-tête du fichier : rresFileHeader
  6. Morceau de ressources : rresResourceChunk
    1. Informations sur les morceaux de ressources : rresResourceChunkInfo
    2. Données de fragment de ressources : rresResourceChunkData
    3. Type de données de ressource : rresResourceDataType
    4. Morceau de ressources : Répertoire central : rresCentralDir
  7. Implémentation d'un moteur personnalisé
  8. Licence

Objectifs de conception

  • Simplicité : la structure rres est simple, un en-tête de fichier et plusieurs ressources les unes après les autres. Néanmoins, chaque ressource possède un petit en-tête d'informations sur la ressource (32 octets) avec plusieurs options disponibles.

  • Facilité d'utilisation : la bibliothèque rres pour lire les fichiers .rres est petite avec seulement le minimum de fonctions requises pour lire les données de ressources à partir de son identifiant. Il n'utilise qu'un petit ensemble de fonctions de la bibliothèque C standard. Un outil rrespacker avec GUI/CLI est fourni pour créer et afficher facilement des fichiers .rres .

  • Flexibilité : le format rres prend en charge tout type de fichier d'entrée. Si les données ne sont pas classées comme type de données de base, elles peuvent simplement être compressées sous forme de données de fichier brutes.

  • Portabilité : le format de fichier rres n'est pas lié à un moteur spécifique, la bibliothèque de base lit simplement les données de ressources telles que compressées et ces données peuvent être mappées à n'importe quelle structure de moteur. Un exemple d'utilisation a été fourni avec la bibliothèque auxiliaire rres-raylib.h qui mappe les données rres aux structures raylib.

  • Sécurité : rres prend en charge la compression et le cryptage par ressource si nécessaire. Néanmoins, malgré la prise en charge fournie par le format de fichier, il appartient à l'utilisateur de l'implémenter dans l'outil rres packer et la bibliothèque de mappage du moteur. rres n'impose aucun algorithme de compression/chiffrement spécifique de par sa conception

  • Extensibilité : le format de fichier rres est extensible, prenant en charge de nouveaux types de données, de nouvelles fonctionnalités et des données personnalisées si nécessaire.

  • Gratuit et open source : rres est une spécification ouverte et une bibliothèque gratuite et open source. Il peut être utilisé avec l'outil fourni ( rrespacker ) ou un packer/chargeur personnalisé peut être implémenté pour n'importe quel moteur . La description du format peut également être utilisée comme matériel d'apprentissage pour toute personne souhaitant créer son propre format de fichier d'empaquetage de données.

Avantages d'utilisation

Il existe des raisons importantes de regrouper les données des actifs du jeu dans un format tel que rres , voici quelques bonnes raisons de le faire.

  • Organisation : Évitez les milliers de fichiers répartis dans des centaines de répertoires dans la version finale du jeu. Toutes les données des fichiers du jeu peuvent être organisées dans un ou plusieurs fichiers .rres . Il garde le répertoire du jeu propre et bien structuré.

  • Performances : conserver tous les fichiers requis pour un niveau/une carte dans un seul fichier .rres réduit le besoin de descripteurs de fichiers pour accéder à plusieurs fichiers ; les descripteurs de fichiers sont une ressource du système d'exploitation et le coût d'ouverture d'un fichier n'est pas négligeable, cela peut entraîner des retards dans le jeu. Les temps d'accès aux données dans le fichier .rres sont également importants et, selon la façon dont les fichiers sont organisés, cela pourrait également améliorer les temps de chargement.

  • Sécurité : évitez d'exposer tous les éléments du jeu directement à l'utilisateur pour une copie ou une modification facile. Les données emballées dans un fichier .rres seront plus difficiles à extraire et à modifier pour la plupart des utilisateurs ; protégez les actifs protégés par le droit d'auteur de votre jeu. rres prend également en charge la compression et le chiffrement des données par ressource, ajoutant un niveau de sécurité supplémentaire si nécessaire.

  • Temps de téléchargement : si les données doivent être accessibles à partir d'un serveur et téléchargées, les ressources regroupées dans un ou plusieurs fichiers .rres améliorent les temps de téléchargement, par rapport au téléchargement de chaque fichier individuellement.

Histoire de la conception

rres est en développement depuis 2014 . J'ai démarré ce projet dans le but de créer un format de fichier de packaging similaire à XNB pour Raylib. Au cours des 8 dernières années, le projet a subi de multiples refontes et améliorations tout au long d'un processus d'apprentissage des formats de fichiers. Au cours de cette période, j'ai implémenté des chargeurs/enregistreurs pour +20 formats de fichiers différents et j'ai également créé +12 formats de fichiers personnalisés pour plusieurs outils personnalisés raylibtech.

Le format de fichier rres a subi au moins 4 grandes refontes :

  • La première conception du format se limitait à empaqueter une ressource après l'autre, chaque ressource se composait d'un en-tête d'informations sur la ressource suivi d'un ensemble fixe de quatre paramètres possibles et des données de ressource. Parallèlement au fichier .rres , un fichier d'en-tête .h a été généré, définissant le rresId avec un nom de fichier de ressources (généralement le nom de fichier d'origine des données non traitées). Ce modèle était assez simple et intuitif, mais il présente quelques inconvénients importants : il ne prenait pas en compte les éléments de données complexes pouvant nécessiter plusieurs morceaux et il n'y avait aucun moyen d'extraire/récupérer les fichiers source d'origine (ou similaires).

  • La deuxième conception était beaucoup plus complexe et tentait de combler les lacunes de la première conception. Dans la deuxième conception, chaque ressource pourrait inclure plusieurs morceaux de données dans une sorte de structure arborescente. En fait, cette conception était similaire au format de fichier RIFF : chaque morceau pouvait contenir des morceaux supplémentaires, chacun avec son en-tête et ses données. Certaines options de ressources supplémentaires ont également été ajoutées, mais le format est devenu assez complexe à comprendre et à gérer. Finalement, l’implémentation des tests a été abandonnée et une alternative plus simple a été étudiée.

  • La troisième conception était un retour à la première conception : simplicité mais conservation de certaines options pour les ressources individuelles. Le problème des ressources multiples générées à partir d'un seul fichier d'entrée a été résolu en utilisant un simple champ de décalage dans l' en-tête d'informations sur la ressource pointant vers la ressource liée suivante lorsque cela est nécessaire. Les ressources ont été chargées sous forme de tableau de morceaux de ressources. Un bloc de ressources facultatif du répertoire central a été ajouté pour conserver les références des fichiers d'entrée. Le format était bon mais il nécessitait encore une mise en œuvre et une enquête plus approfondie, il devait être indépendant du moteur et il dépendait toujours des structures et des fonctionnalités de Raylib.

  • Une quatrième conception a été réalisée au cours de la mise en œuvre, presque toutes les structures et tous les champs ont été revus et renommés pour plus de cohérence et de simplicité. Une bibliothèque distincte a été créée ( rres-raylib.h ) pour mapper les données de ressources chargées dans des types de données de bibliothèque/moteur personnalisés, toute dépendance à raylib a été supprimée, ce qui en fait un format de fichier complètement indépendant du moteur. Plusieurs exemples d'utilisation de Raylib ont été implémentés pour illustrer la connexion bibliothèque-moteur de rres et plusieurs types de chargement de ressources ont été implémentés. L'outil rrespacker a été créé à partir de zéro pour générer des fichiers rres , il prend en charge une interface graphique agréable avec prise en charge du glisser-déposer mais également une ligne de commande puissante pour le traitement par lots. L'implémentation de la compression et du chiffrement a été déplacée vers l'implémentation de la bibliothèque utilisateur pour être alignée sur l'outil d'empaquetage et garder le format de fichier rres plus propre et plus simple.

Cela a été un projet de 8 ans , sur lequel j'ai travaillé par intermittence, avec de nombreuses refontes et révisions, mais je suis personnellement très satisfait du résultat final. rres est un format de fichier d'empaquetage de ressources au niveau de n'importe quel format de package de moteur professionnel MAIS gratuit et open source , disponible pour tout développeur de jeux qui souhaite l'utiliser, l'implémenter ou créer une version personnalisée.

Structure du fichier

Le format de fichier rres se compose d'un en-tête de fichier ( rresFileHeader ) suivi d'un certain nombre de morceaux de ressources ( rresResourceChunk ). Chaque bloc de ressources possède un en-tête d'informations sur les ressources ( rresResourceChunkInfo ) qui comprend un code de type de données FOURCC et des informations sur les données de ressources. Les données de ressource ( rresResourceChunkData ) contiennent un petit ensemble de propriétés pour identifier les données, selon le type et peuvent contenir des données supplémentaires à la fin.

Figure 01. Structure du fichier rres v1.0.

REMARQUE : les rresResourceChunk sont générés à partir des fichiers d'entrée. Il est important de noter que les ressources ne peuvent pas être mappées sur des fichiers 1:1, un fichier d'entrée peut générer plusieurs morceaux de ressources. Par exemple, un fichier d'entrée .ttf peut générer un bloc de ressources d'image (type RRES_DATA_IMAGE ) plus un bloc de ressources d'informations sur les glyphes de police (type 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
}

En-tête du fichier : rresFileHeader

La structure C suivante définit le 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 ;
Champ Description
id Identifiant de signature de fichier, il doit s'agir des quatre caractères : r , r , e , s .
version Définit la version et la subversion du format.
chunkCount Nombre de morceaux de ressources présents dans le fichier. Notez qu'il peut être supérieur au nombre de fichiers d'entrée traités.
cdOffset Décalage absolu du répertoire central dans le fichier, notez que CDIR n'est qu'un autre type de bloc de ressources, le répertoire central peut être présent dans le fichier ou non . Il est recommandé de le placer comme dernier morceau du fichier si un packer rres personnalisé est implémenté. Consultez la section rresCentralDir pour plus de détails.
reserved Ce champ est réservé pour des ajouts futurs si nécessaire.

Tableau 01. Description et détails des champs rresFileHeader

Considérations :

  • Les fichiers rres sont limités par conception à un maximum de 65 535 morceaux de ressources . Au cas où davantage de ressources devraient être compressées, il est recommandé de créer plusieurs fichiers rres .
  • Les fichiers rres utilisent des décalages de 32 bits pour traiter les différents morceaux de ressources. Par conséquent, pas plus de ~ 4 Go de données peuvent être adressés . Veuillez conserver les fichiers rres inférieurs à 4 Go . Si plus d'espace est requis pour empaqueter les ressources, créez plusieurs fichiers rres .

Morceau de ressources : rresResourceChunk

Le fichier rres contient un certain nombre de morceaux de ressources. Chaque bloc de ressources représente un pack de données autonome. Les morceaux de ressources sont générés à partir des fichiers d'entrée lors de la création du fichier rres par l'outil rres packer ; en fonction de l'extension du fichier, l'outil rres packer extrait les données requises du fichier et génère un ou plusieurs morceaux de ressources. Par exemple, pour un fichier image, un bloc de ressources de type RRES_DATA_IMAGE est généré, contenant uniquement les données de pixels de l'image et les propriétés requises pour relire ces données à partir du fichier de ressources.

Il est important de noter qu'un fichier d'entrée peut générer plusieurs morceaux de ressources lors de la création du fichier rres . Par exemple, un fichier d'entrée .ttf pourrait générer un bloc de ressources RRES_DATA_IMAGE plus un bloc de ressources RRES_DATA_FONT_GLYPHS ; il est également possible de simplement compresser le fichier sous la forme d'un simple type de bloc de ressources RRES_DATA_RAW , dans ce cas, le fichier d'entrée n'est pas traité, simplement compressé sous forme de données brutes.

Lors de la création rres , le packer rres peut créer un morceau de ressources supplémentaire de type RRES_DATA_DIRECTORY contenant des données sur les fichiers d'entrée traités. Cela pourrait être utile dans certains cas, par exemple pour relier le nom du fichier d'entrée directement à l'identifiant de la ou des ressources générées et également pour extraire les données dans une structure de fichier similaire à celle d'entrée d'origine.

Chaque bloc de ressources est divisé en deux parties : rresResourceChunkInfo + rresResourceData .

Informations sur les morceaux de ressources : rresResourceChunkInfo

La structure C suivante définit le 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 ;
Champ Description
type Un code FourCC et identifie le type de données de ressource contenues dans le rresResourceChunkData . L'énumération rresResourceDataType définit plusieurs types de données, de nouveaux peuvent être ajoutés si nécessaire.
id Identificateur de ressource global, il est généré à partir du nom de fichier d'entrée à l'aide d'un hachage CRC32 et il n'est pas unique. Un fichier d'entrée peut générer plusieurs morceaux de ressources, tous les morceaux générés partagent le même identifiant et ils sont chargés ensemble lorsque la ressource est chargée. Par exemple, une entrée .ttf pourrait générer deux morceaux de ressources ( RRES_DATA_IMAGE + RRES_DATA_FONT_GLYPHS ) avec le même identifiant qui seront chargés ensemble lorsque leur identifiant est demandé. C'est à l'utilisateur de décider quoi faire avec les données chargées.
compType Définit l'algorithme de compression utilisé pour les données du bloc de ressources. La compression dépend de la bibliothèque intermédiaire entre rres et le moteur, rres.h définit simplement quelques valeurs d'algorithme utiles à utiliser en cas d'implémentation de la compression. La compression doit toujours être appliquée avant le chiffrement et compresse le rresResourceData complet ( Property Count + Properties[] + Data ). Si aucun cryptage des données n'est appliqué, packedSize définit la taille des données compressées.
cipherType Définit l'algorithme de chiffrement utilisé pour les données du bloc de ressources. Comme la compression, le chiffrement dépend de la bibliothèque intermédiaire entre rres et le moteur, rres.h définit simplement quelques valeurs d'algorithme utiles à utiliser en cas d'implémentation du chiffrement. Le cryptage doit être appliqué après la compression. En fonction de l'algorithme de chiffrement et du mode de chiffrement, il peut être nécessaire d'attacher des données supplémentaires aux données de ressource (c'est-à-dire le chiffrement MAC), cela dépend de l'implémentation et l'outil de compression rres / la bibliothèque intermédiaire rres pour les moteurs sont responsables de gérer cela. données supplémentaires. Il est recommandé de simplement l'ajouter aux données de ressources et de le prendre en compte dans packedSize .
flags Réservé aux indicateurs supplémentaires, au cas où ils seraient requis par l'implémentation.
packedSize Définit la taille compressée (compressée/chiffrée + données utilisateur supplémentaires) de rresResourceChunkData . Les données empaquetées peuvent contenir des données utilisateur ajoutées à la fin, après les données compressées/chiffrées, par exemple le nom occasionnel/MAC pour les données chiffrées, mais cela dépend de l'implémentation, géré par l'outil rres packer et la bibliothèque utilisateur pour charger les fragments de données dans structures de moteur cibles.
baseSize Définit la taille de base (non compressée/non chiffrée) de rresResourceChunkData .
nextOffset Définit l'adresse de position globale du fichier pour le prochain bloc de ressources associé . Elle est utile pour les fichiers d'entrée qui génèrent plusieurs ressources, comme des polices ou des maillages.
reserved Ce champ est réservé pour des ajouts futurs si nécessaire.
crc32 Calculé sur le bloc rresResourceData complet ( packedSize ) et destiné à détecter les erreurs de corruption de données.

Tableau 02. Description et détails des champs rresResourceChunkInfo

Données de fragment de ressources : rresResourceChunkData

rresResourceChunkData contient les données suivantes :

  • Property Count : nombre de propriétés contenues, dépend du type de ressource
  • Properties[] : propriétés requises des données de ressource, dépendent du type de ressource
  • Data : données brutes sur les ressources, dépendent du type de ressource

REMARQUE : rresResourceChunkData peut contenir des données utilisateur supplémentaires, dans ces cas, une taille de données supplémentaire doit être prise en compte dans packedSize .

Type de données de ressource : rresResourceDataType

Le type de ressource spécifié dans rresResourceChunkInfo définit le type de données et le nombre de propriétés contenues dans le bloc de ressources.

Ici, ce sont les types de données actuellement définis. Veuillez noter que certains fichiers d'entrée peuvent générer plusieurs morceaux de ressources de plusieurs types. Des types de ressources supplémentaires pourraient être ajoutés si nécessaire. 

 // 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 ;

Les types de données actuellement définis comprennent les propriétés et données suivantes :

type de ressource FourCC nombre d'accessoires accessoires données
RRES_DATA_NULL NULL 0 - -
RRES_DATA_RAW RAWD 4 props[0] :taille
props[1] : extension01
props[2] : extension02
props[3] : réservé		 octets du fichier brut
RRES_DATA_TEXT TEXT 4 props[0] :taille
props[1] : rresTextEncoding
props[2] : rresCodeLang
props[3] :cultureCode		 données texte
RRES_DATA_IMAGE IMGE 4 props[0] : largeur
props[1] : hauteur
props[2] : rresPixelFormat
props[3] :mipmaps		 données de pixels
RRES_DATA_WAVE WAVE 4 props[0] :frameCount
props[1] : sampleRate
props[2] : sampleSize
props[3] : canaux		 données d'échantillons audio
RRES_DATA_VERTEX VRTX 4 props[0] : vertexCount
props[1] : rresVertexAttribute
props[2] :componentCount
props[3] : rresVertexFormat		 données de sommet
RRES_DATA_FONT_GLYPHS FNTG 4 props[0] : taille de base
props[1] :glyphCount
props[2] :glyphPadding
props[3] : rresFontStyle		 rresFontGlyphInfo[0..glyphCount]
RRES_DATA_LINK LINK 1 props[0] :taille données de chemin de fichier
RRES_DATA_DIRECTORY CDIR 1 props[0] : entryCount rresDirEntry[0..entryCount]

Tableau 03. Valeurs et détails définis rresResourceDataType

REMARQUE : RRES_DATA_RAW contient l'extension de fichier packagée dans le cadre de ses propriétés, l'extension char est convertie en une valeur big-endian unsigned int 4 octets, commençant par un point. c'est-à-dire ".png" => 0x2e706e67 . Dans le cas où l'extension n'était pas pertinente, l'implémentation utilisateur pourrait décider de définir ces propriétés sur 0 .

rres.h définit les enums suivantes pour faciliter l'attribution de certaines propriétés :

  • rresTextEncoding : Définit plusieurs encodages de texte possibles, la valeur par défaut est 0 (UTF-8)
  • rresCodeLang : Définit plusieurs langages de programmation, utiles en cas d'intégration de fichiers de code ou de scripts
  • rresPixelFormat : définit plusieurs valeurs de format de pixel pour les données de pixels d'image
  • rresVertexAttribute : définit plusieurs types d'attributs de sommet pour plus de commodité
  • rresVertexFormat : définit plusieurs formats de données pour les données de sommet
  • rresFontStyle : Définit plusieurs styles de police (Regular, Bold, Italic...), la valeur par défaut est 0 ( RRES_FONT_STYLE_DEFAULT )

Morceau de ressources : Répertoire central : rresCentralDir

Le fragment de ressources Central Directory est un fragment spécial qui peut être présent ou non dans le fichier rres . Il stocke des informations sur les fichiers d'entrée traités pour générer les multiples fragments de ressources et peut être utile pour :

  • Référencez les ressources par leur nom de fichier d'origine. Ceci est très utile en termes d'implémentation pour minimiser les modifications de code requises si le packaging rres est effectué sur un projet existant ou à la fin du développement d'un projet, si le chargement de tous les fichiers a été effectué en utilisant directement les noms de fichiers.

  • Extrayez certaines des ressources dans un fichier d’entrée similaire. Cela ne sera possible que si le fichier d'entrée n'a pas été traité de manière destructrice. Par exemple, si un fichier .ttf a été traité pour générer un atlas d'images de glyphes + des informations sur les données de glyphes, il ne sera pas possible de récupérer le fichier .ttf d'origine.

rres fournit des structures utiles pour gérer les données des fragments de ressources 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 ;

REMARQUE : les entrées de nom de fichier du répertoire central sont alignées sur un remplissage de 4 octets pour améliorer les temps d'accès aux fichiers.

rres.h fournit une fonction pour charger Central Directory à partir du fichier rres lorsqu'il est disponible : rresLoadCentralDirectory() et également une fonction pour obtenir les identifiants d'une ressource à partir de son nom de fichier d'origine : rresGetIdFromFileName() .

Dans le cas où un fichier rres est généré sans Central Directory , un fichier d'en-tête secondaire ( .h ) doit être fourni avec les références d'identifiant pour toutes les ressources, à utiliser dans le code utilisateur.

Implémentation d'un moteur personnalisé

rres est conçu comme un format de fichier indépendant du moteur qui peut être utilisé avec n'importe quel moteur de jeu. Les développeurs qui adoptent rres peuvent implémenter une bibliothèque personnalisée et une abstraction personnalisée pour mapper les données génériques rres aux structures de données de leurs propres moteurs ainsi qu'aux outils d'empaquetage rres personnalisés .

Le diagramme suivant montre un exemple d'implémentation de rres pour la bibliothèque raylib .

Fig 02. Exemple d'implémentation de rres : bibliothèques et outils de moteur personnalisés.

La mise en œuvre rres se compose de plusieurs parties :

  • Bibliothèque de base : rres.h
  • Bibliothèque de mappage du moteur : rres-raylib.h
  • Outil de packaging : rrespacker

Bibliothèque de base : rres.h

La bibliothèque de base rres est chargée de lire les morceaux de ressources des fichiers rres dans une structure de ressources générique, renvoyée à l'utilisateur. La structure des ressources exposées par l'utilisateur rresResourceChunk suit la structure des spécifications rres ( rresResourceChunkInfo + rresResourceChunkData ). Les structures suivantes sont proposées :

  • rresResourceChunk contient un seul morceau avec les informations et données requises par l'utilisateur : rresResourceChunkInfo + rresResourceChunkData
  • rresresourceChunkInfo contient les informations sur le bloc de ressources chargé
  • rresResourceChunkData contient les données réelles de la ressource : les propriétés requises et les données brutes. Il est important de noter que dans le cas où les données ont été compressées/chiffrées, c'est à la bibliothèque utilisateur ( rres-raylib.h ) de traiter ces données ; dans ces cas, chunk.data.raw contient les données compressées/chiffrées et chunk.data.propCount = 0 et chunk.data.props = NULL ; c'est à la bibliothèque utilisateur de remplir les propriétés après décompression/déchiffrement.
  • rresResourceMulti contient plusieurs rresResourceChunks pour un fichier d'entrée traité 
 // 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 ;

Un seul rresResourceChunk peut être chargé à partir du fichier .rres avec la fonction fournie : rresLoadResourceChunk() et déchargé avec rresUnloadResourceChunk() .

Un rresResourceMulti complet peut être chargé à partir du fichier .rres avec la fonction fournie : rresLoadResourceMulti() et déchargé avec rresUnloadResourceMulti() .

Bibliothèque de mappage du moteur : rres-raylib.h

La bibliothèque de mappage inclut rres.h et fournit des fonctionnalités permettant de mapper les données des fragments de ressources chargées à partir du fichier rres dans les structures raylib . L'API fournie est simple et intuitive, suivant les conventions 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

Notez que la décompression/déchiffrement des données est implémentée dans cette bibliothèque personnalisée, UnpackResourceChunk() est fournie aux utilisateurs. rresResourceChunk contient des valeurs d'identifiant de compresseur/chiffrement pour plus de commodité. La prise en charge des compresseurs et des chiffrements dépend de l'implémentation de l'utilisateur et doit être alignée sur l'outil de packaging ( rrespacker ).

Le format de fichier rres est indépendant du moteur, des bibliothèques et des outils peuvent être créés pour n'importe quel moteur/framework dans n'importe quel langage de programmation.

Outil de packaging : rrespacker

rrespacker est l'outil d'empaquetage rres chargé de traiter tous les fichiers d'entrée et de créer le fichier rres , suivant la spécification. Dans le cas où certains algorithmes de compression/chiffrement sont pris en charge, ils doivent être implémentés par cet outil et les mêmes algorithmes doivent être pris en charge par la bibliothèque de mappage, dans notre cas rres-raylib.h .

Fig 03. Outil rrespacker, interface GUI, il prend également en charge CLI pour le traitement par lots.

rrespacker peut être utilisé en ligne (ou téléchargé) depuis itch.io.

Versions

  • rres v1.0 (12 mai 2022) - Première version de la spécification.

Licence

Les spécifications de format de fichier rres , la bibliothèque rres.h et la bibliothèque rres-raylib.h sont sous licence MIT. Vérifiez LICENCE pour plus de détails.

Copyright (c) 2014-2024 Ramon Santamaria (@raysan5)

Développer
Informations supplémentaires
Applications connexes
Recommandé pour vous
Actualités connexes Tout