rres

rres é um formato de arquivo simples e fácil de usar para empacotar recursos

rres foi projetado para empacotar recursos de jogos (imagens, fontes, texto, áudio, modelos...) em um formato simples e abrangente, fácil de ler e escrever, projetado para carregar dados de maneira rápida e eficiente.

rres é inspirado nos seguintes formatos de arquivo: XNB (usado por XNA/MonoGame), RIFF, PNG e ZIP.

Índice

1. Metas de projeto
2. Benefícios de uso
3. História do projeto
4. Estrutura de arquivo
5. Cabeçalho do arquivo: rresFileHeader
6. Pedaço de recursos: rresResourceChunk
   1. Informações do bloco de recursos: rresResourceChunkInfo
   2. Dados do bloco de recursos: rresResourceChunkData
   3. Tipo de dados do recurso: rresResourceDataType
   4. Bloco de recursos: Diretório Central: rresCentralDir
7. Implementação de mecanismo personalizado
8. Licença

---

Metas de projeto

• Simplicidade : a estrutura rres é simples, um cabeçalho de arquivo e vários recursos, um após o outro. Ainda assim, cada recurso possui um pequeno cabeçalho de informações do recurso (32 bytes) com várias opções disponíveis.

• Facilidade de uso : a biblioteca rres para ler arquivos .rres é pequena, com apenas as funções mínimas necessárias para ler dados de recursos de seu id. Ele usa apenas um pequeno conjunto de funções da biblioteca C padrão. Uma ferramenta rrespacker com GUI/CLI é fornecida para criar e visualizar facilmente arquivos .rres .

• Flexibilidade : o formato rres suporta qualquer tipo de arquivo de entrada; se os dados não forem classificados como um tipo de dados básico, eles podem ser compactados apenas como dados de arquivo brutos.

• Portabilidade : o formato de arquivo rres não está vinculado a um mecanismo específico, a biblioteca base apenas lê os dados do recurso conforme compactados e esses dados podem ser mapeados para qualquer estrutura do mecanismo. Um exemplo de uso foi fornecido com a biblioteca auxiliar rres-raylib.h que mapeia dados rres para estruturas raylib.

• Segurança : rres suporta compactação e criptografia por recurso, se necessário. Ainda assim, apesar do suporte fornecido pelo formato de arquivo cabe ao usuário implementá-lo na ferramenta rres packer e na biblioteca de mapeamento do motor. rres não força nenhum algoritmo específico de compactação/criptografia por design

• Extensibilidade : o formato de arquivo rres é extensível, suportando novos tipos de dados, novos recursos e dados personalizados, se necessário.

• Gratuito e de código aberto : rres é uma especificação aberta e uma biblioteca gratuita e de código aberto. Ele pode ser usado com a ferramenta fornecida ( rrespacker ) ou um empacotador/carregador personalizado pode ser implementado para qualquer mecanismo . A descrição do formato também pode ser usada como material de aprendizagem para qualquer pessoa disposta a criar seu próprio formato de arquivo de empacotamento de dados.

Benefícios de uso

Existem alguns motivos importantes para empacotar dados de ativos de jogos em um formato como rres . Aqui estão alguns bons motivos para fazê-lo.

• Organização : Evite milhares de arquivos distribuídos em centenas de diretórios na construção final do jogo. Todos os dados dos arquivos do jogo podem ser organizados em um único ou em alguns arquivos .rres . Mantém o diretório do jogo limpo e bem estruturado.

• Desempenho : Manter todos os arquivos necessários para um nível/mapa em um único arquivo .rres reduz a necessidade de identificadores de arquivo para acessar vários arquivos; identificadores de arquivo são um recurso do sistema operacional e o custo de abertura de um arquivo não é insignificante, podendo causar atrasos no jogo. Os tempos de acesso aos dados dentro do arquivo .rres também são importantes e dependendo de como os arquivos estão organizados também podem melhorar os tempos de carregamento.

• Segurança : Evite expor todos os ativos do jogo diretamente ao usuário para facilitar a cópia ou modificação. Os dados compactados em um arquivo .rres serão mais difíceis de extrair e modificar para a maioria dos usuários; proteja os ativos protegidos por direitos autorais do seu jogo. rres também suporta compactação e criptografia de dados por recurso, adicionando um nível extra de segurança quando necessário.

• Tempos de download : se os dados precisarem ser acessados ​​de um servidor e baixados, os ativos compactados em um único ou em alguns arquivos .rres melhoram os tempos de download, em comparação com o download de cada arquivo individualmente.

História do projeto

rres está em desenvolvimento desde 2014 . Comecei este projeto com o objetivo de criar um formato de arquivo de empacotamento semelhante ao XNB para raylib. Nos últimos 8 anos o projeto sofreu múltiplas reformulações e melhorias ao longo de um processo de aprendizagem de formatos de arquivos. Naquela época, implementei carregadores/gravadores para mais de 20 formatos de arquivo diferentes e também criei mais de 12 formatos de arquivo personalizados para várias ferramentas personalizadas de raylibtech.

O formato de arquivo rres passou por pelo menos quatro grandes reformulações :

• O primeiro design do formato limitou-se a empacotar um recurso após o outro, cada recurso consistia em um cabeçalho de informações do recurso seguido por um conjunto fixo de quatro parâmetros possíveis e os dados do recurso. Junto com o arquivo .rres , um arquivo de cabeçalho .h foi gerado com mapeamento que define o rresId com um nome de arquivo de recurso (geralmente o nome do arquivo original dos dados não processados). Este modelo era bastante simples e intuitivo, mas tinha algumas desvantagens importantes: não considerava dados complexos que poderiam exigir vários blocos e não havia como extrair/recuperar arquivos de origem originais (ou similares).

• O segundo projeto foi muito mais complexo e tentou resolver as deficiências do primeiro projeto. No segundo projeto, cada recurso poderia incluir vários blocos de dados em uma espécie de estrutura em árvore. Na verdade, esse design era semelhante ao formato de arquivo RIFF: cada pedaço poderia conter pedaços adicionais, cada um com seu cabeçalho e dados. Algumas opções de recursos adicionais também foram adicionadas, mas o formato tornou-se bastante complexo de entender e gerenciar. Por fim, a implementação de testes foi descartada e uma alternativa mais simples foi investigada.

• O terceiro design foi um retorno ao primeiro design: simplicidade, mas mantendo algumas das opções para os recursos individuais. O problema de múltiplos recursos gerados a partir de um único arquivo de entrada foi resolvido usando um simples campo de deslocamento no cabeçalho de informações do recurso apontando para o próximo recurso vinculado quando necessário. Os recursos foram carregados como uma série de blocos de recursos. Um pedaço de recurso opcional do Diretório Central foi adicionado para manter referências para os arquivos de entrada. O formato era bom, mas ainda exigia implementação e investigação adicional, precisava ser independente do mecanismo e ainda dependia de estruturas e funcionalidades do raylib.

• O quarto design foi feito ao longo da implementação, quase todas as estruturas e campos foram revisados ​​e renomeados para consistência e simplicidade. Uma biblioteca separada foi criada ( rres-raylib.h ) para mapear os dados de recursos carregados em tipos de dados de biblioteca/mecanismo personalizados, qualquer dependência do raylib foi removida, tornando-o um formato de arquivo completamente independente do mecanismo. Vários exemplos de uso para raylib foram implementados para ilustrar a conexão biblioteca-mecanismo do rres e vários tipos de carregamento de recursos foram implementados. A ferramenta rrespacker foi criada do zero para gerar arquivos rres , suporta uma interface GUI agradável com suporte para arrastar e soltar, mas também uma linha de comando poderosa para processamento em lote. A implementação de compactação e criptografia foi movida para a implementação da biblioteca do usuário para estar alinhada com a ferramenta de empacotamento e manter o formato de arquivo rres mais limpo e simples.

Foi um projeto de 8 anos , trabalhando nele intermitentemente, com muitas reformulações e revisões, mas pessoalmente estou muito feliz com o resultado final. rres é um formato de arquivo de empacotamento de recursos no nível de qualquer formato de pacote de mecanismo profissional , MAS gratuito e de código aberto , disponível para qualquer desenvolvedor de jogos que queira usá-lo, implementá-lo ou criar uma versão personalizada.

Estrutura de arquivo

O formato de arquivo rres consiste em um cabeçalho de arquivo ( rresFileHeader ) seguido por vários pedaços de recursos ( rresResourceChunk ). Cada parte do recurso possui um cabeçalho de informações do recurso ( rresResourceChunkInfo ) que inclui um código de tipo de dados FOURCC e informações de dados do recurso. Os dados do recurso ( rresResourceChunkData ) contêm um pequeno conjunto de propriedades para identificar os dados, dependendo do tipo e podem conter alguns dados adicionais no final.

Fig 01. Estrutura do arquivo rres v1.0.

NOTA: rresResourceChunk(s) são gerados a partir de arquivos de entrada. É importante observar que os recursos não podem ser mapeados para arquivos 1:1, um arquivo de entrada pode gerar vários blocos de recursos. Por exemplo, um arquivo de entrada .ttf pode gerar um bloco de recursos de imagem (tipo RRES_DATA_IMAGE ) mais um bloco de recursos de informações de glifo de fonte (tipo 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
}

Cabeçalho do arquivo: rresFileHeader

A seguinte estrutura C define o 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 ;

Campo	Descrição
id	Identificador de assinatura do arquivo, deve ter os quatro caracteres: r , r , e , s .
version	Define a versão e subversão do formato.
chunkCount	Número de pedaços de recursos presentes no arquivo. Observe que pode ser maior que o número de arquivos de entrada processados.
cdOffset	Deslocamento absoluto do Diretório Central dentro do arquivo, observe que CDIR é apenas outro tipo de bloco de recurso, o Diretório Central pode estar presente no arquivo ou não . É recomendado ser colocado como o último pedaço do arquivo se um empacotador rres personalizado for implementado. Verifique a seção rresCentralDir para obter mais detalhes.
reserved	Este campo está reservado para adições futuras, se necessário.

Tabela 01. Descrição e detalhes dos campos rresFileHeader

Considerações:

• Os arquivos rres são limitados por design a um máximo de 65.535 blocos de recursos ; caso mais recursos precisem ser compactados, é recomendável criar vários arquivos rres .
• Os arquivos rres usam deslocamentos de 32 bits para endereçar os diferentes blocos de recursos, conseqüentemente, não mais do que ~ 4 GB de dados podem ser endereçados , mantenha os arquivos rres menores que 4 GB . Caso seja necessário mais espaço para empacotar recursos, crie vários arquivos rres .

Pedaço de recursos: rresResourceChunk

O arquivo rres contém vários blocos de recursos. Cada pedaço de recurso representa um pacote independente de dados. Pedaços de recursos são gerados a partir de arquivos de entrada na criação do arquivo rres pela ferramenta rres packer; dependendo da extensão do arquivo, a ferramenta rres packer extrai os dados necessários do arquivo e gera um ou mais blocos de recursos. Por exemplo, para um arquivo de imagem, um pedaço de recurso do type RRES_DATA_IMAGE é gerado contendo apenas os dados de pixel da imagem e as propriedades necessárias para ler esses dados do arquivo de recurso.

É importante observar que um arquivo de entrada pode gerar vários blocos de recursos quando o arquivo rres é criado. Por exemplo, um arquivo de entrada .ttf poderia gerar um bloco de recursos RRES_DATA_IMAGE mais um bloco de recursos RRES_DATA_FONT_GLYPHS ; também é possível compactar o arquivo apenas como um tipo de bloco de recurso RRES_DATA_RAW simples; nesse caso, o arquivo de entrada não é processado, apenas compactado como dados brutos.

Na criação rres , o empacotador rres poderia criar um pedaço de recurso adicional do tipo RRES_DATA_DIRECTORY contendo dados sobre os arquivos de entrada processados. Pode ser útil em alguns casos, por exemplo, relacionar o nome do arquivo de entrada diretamente ao ID do(s) recurso(s) gerado(s) e também extrair os dados em uma estrutura de arquivo semelhante à de entrada original.

Cada pedaço de recurso é dividido em duas partes: rresResourceChunkInfo + rresResourceData .

Informações do bloco de recursos: rresResourceChunkInfo

A seguinte estrutura C define o 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 ;

Campo	Descrição
type	Um código FourCC que identifica o tipo de dados de recursos contidos no rresResourceChunkData . Enum rresResourceDataType define vários tipos de dados, novos podem ser adicionados se necessário.
id	Um identificador de recurso global, é gerado a partir do nome do arquivo de entrada usando um hash CRC32 e não é exclusivo. Um arquivo de entrada pode gerar vários blocos de recursos, todos os blocos gerados compartilham o mesmo identificador e são carregados juntos quando o recurso é carregado. Por exemplo, uma entrada .ttf poderia gerar dois pedaços de recursos ( RRES_DATA_IMAGE + RRES_DATA_FONT_GLYPHS ) com o mesmo identificador que serão carregados juntos quando seu identificador for solicitado. Cabe ao usuário decidir o que fazer com os dados carregados.
compType	Define o algoritmo de compactação usado para os dados do bloco de recursos. A compactação depende da biblioteca intermediária entre rres e o mecanismo, rres.h apenas define alguns valores de algoritmo úteis a serem usados ​​no caso de implementação de compactação. A compactação sempre deve ser aplicada antes da criptografia e compacta o rresResourceData completo ( Property Count + Properties[] + Data ). Se nenhuma criptografia de dados for aplicada, packedSize definirá o tamanho dos dados compactados.
cipherType	Define o algoritmo de criptografia usado para os dados do bloco de recursos. Assim como a compactação, a criptografia depende da biblioteca intermediária entre o rres e o mecanismo, rres.h apenas define alguns valores de algoritmo úteis a serem usados ​​no caso de implementação da criptografia. A criptografia deve ser aplicada após a compactação. Dependendo do algoritmo de criptografia e do modo de criptografia, pode ser necessário anexar algum dado extra aos dados do recurso (ou seja, MAC de criptografia), isso depende da implementação e a ferramenta rres packer / biblioteca intermediária rres para os mecanismos é responsável por gerenciar isso dados extras. Recomenda-se que seja apenas anexado aos dados do recurso e considerado packedSize .
flags	Reservado para sinalizadores adicionais, caso sejam exigidos pela implementação.
packedSize	Define o tamanho compactado (compactado/criptografado + dados adicionais do usuário) de rresResourceChunkData . Os dados empacotados podem conter dados do usuário anexados no final, após os dados compactados/criptografados, por exemplo, o nonce/MAC para os dados criptografados, mas dependem da implementação, gerenciados pela ferramenta rres packer e pela biblioteca do usuário para carregar os dados dos pedaços. estruturas do motor alvo.
baseSize	Define o tamanho base (descompactado/não criptografado) de rresResourceChunkData .
nextOffset	Define o endereço de posição global do arquivo para o próximo pedaço de recurso relacionado . É útil para arquivos de entrada que geram vários recursos, como fontes ou malhas.
reserved	Este campo está reservado para adições futuras, se necessário.
crc32	Calculado sobre o pedaço rresResourceData completo ( packedSize ) e destina-se a detectar erros de corrupção de dados.

Tabela 02. Descrição e detalhes dos campos rresResourceChunkInfo

Dados do bloco de recursos: rresResourceChunkData

rresResourceChunkData contém os seguintes dados:

• Property Count : número de propriedades contidas, depende do type recurso
• Properties[] : propriedades obrigatórias dos dados do recurso, dependem do type de recurso
• Data : dados brutos de recursos, dependem do type de recurso

NOTA: rresResourceChunkData pode conter dados adicionais do usuário; nesses casos, o tamanho adicional dos dados deve ser considerado packedSize .

Tipo de dados do recurso: rresResourceDataType

O type de recurso especificado em rresResourceChunkInfo define o tipo de dados e o número de propriedades contidas na parte do recurso.

Aqui estão os tipos de dados atualmente definidos. Observe que alguns arquivos de entrada podem gerar vários blocos de recursos de vários tipos. Tipos de recursos adicionais podem ser adicionados, se necessário.

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

Os types de dados definidos atualmente consistem nas seguintes propriedades e dados:

tipo de recurso	QuatroCC	adereçosCount	adereços	dados
RRES_DATA_NULL	NULL	0	-	-
RRES_DATA_RAW	RAWD	4	props[0] : tamanho props[1] : extension01 props[2] : extension02 props[3] : reservado	bytes de arquivo bruto
RRES_DATA_TEXT	TEXT	4	props[0] : tamanho props[1] : rresTextEncoding props[2] : rresCodeLang props[3] :cultureCode	dados de texto
RRES_DATA_IMAGE	IMGE	4	props[0] : largura props[1] :altura props[2] : rresPixelFormat props[3] :mipmaps	dados de pixels
RRES_DATA_WAVE	WAVE	4	props[0] :frameCount props[1] : taxa de amostra props[2] :sampleSize props[3] :canais	dados de amostras de áudio
RRES_DATA_VERTEX	VRTX	4	props[0] :vertexCount props[1] : rresVertexAttribute props[2] :componentCount props[3] : rresVertexFormat	dados de vértice
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] : tamanho	dados do caminho do arquivo
RRES_DATA_DIRECTORY	CDIR	1	props[0] :entryCount	rresDirEntry[0..entryCount]

Tabela 03. Valores e detalhes definidos rresResourceDataType

NOTA: RRES_DATA_RAW contém a extensão do arquivo empacotado como parte de suas propriedades, a extensão char é convertida em um valor unsigned int de 4 bytes, começando com um ponto. ou seja, ".png" => 0x2e706e67 . Caso a extensão não fosse relevante, a implementação do usuário poderia decidir definir essas propriedades como 0 .

rres.h define os seguintes enums por conveniência para atribuir algumas das propriedades:

• rresTextEncoding : Define várias codificações de texto possíveis, o valor padrão é 0 (UTF-8)
• rresCodeLang : Define diversas linguagens de programação, úteis no caso de incorporação de arquivos de código ou scripts
• rresPixelFormat : Define vários valores de formato de pixel para dados de pixel de imagem
• rresVertexAttribute : Define vários tipos de atributos de vértice por conveniência
• rresVertexFormat : Define vários formatos de dados para dados de vértice
• rresFontStyle : Define vários estilos de fonte (Regular, Negrito, Itálico...), o valor padrão é 0 ( RRES_FONT_STYLE_DEFAULT )

Bloco de recursos: Diretório Central: rresCentralDir

O bloco de recursos Central Directory é um bloco especial que pode estar presente ou não no arquivo rres , ele armazena informações sobre os arquivos de entrada processados ​​para gerar os vários blocos de recursos e pode ser útil para:

• Faça referência aos recursos pelo nome de arquivo original. Isso é muito útil em termos de implementação para minimizar as alterações de código necessárias se o empacotamento rres for feito em um projeto existente ou no final do desenvolvimento de um projeto, se o carregamento de todos os arquivos tiver sido feito usando os nomes dos arquivos diretamente.

• Extraia alguns dos recursos para um arquivo de entrada semelhante. Isso só será possível se o arquivo de entrada não tiver sido processado de forma destrutiva. Por exemplo, se um arquivo.ttf tiver sido processado para gerar um atlas de imagens de glifos + informações de dados de glifos, não será possível recuperar o arquivo .ttf original.

rres fornece algumas estruturas úteis para lidar com dados de blocos de recursos 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 ;

NOTA: As entradas de nome de arquivo do Diretório Central são alinhadas ao preenchimento de 4 bytes para melhorar o tempo de acesso aos arquivos.

rres.h fornece uma função para carregar o Central Directory do arquivo rres quando disponível: rresLoadCentralDirectory() e também uma função para obter identificadores de recurso de seu nome de arquivo original: rresGetIdFromFileName() .

Caso um arquivo rres seja gerado sem Central Directory , um arquivo de cabeçalho secundário ( .h ) deverá ser fornecido com as referências de id de todos os recursos, para ser utilizado no código do usuário.

Implementação de mecanismo personalizado

rres foi projetado como um formato de arquivo independente de mecanismo que pode ser usado com qualquer mecanismo de jogo. Os desenvolvedores que adotam rres podem implementar uma biblioteca customizada e uma abstração customizada para mapear dados genéricos rres para suas próprias estruturas de dados de mecanismos e também ferramentas de empacotamento rres customizadas .

O diagrama a seguir mostra um exemplo de implementação de rres para a biblioteca raylib .

Fig 02. Exemplo de implementação do rres: bibliotecas e ferramentas de mecanismo customizadas.

A implementação rres consiste em várias partes:

• Biblioteca base: rres.h
• Biblioteca de mapeamento do mecanismo: rres-raylib.h
• Ferramenta de embalagem: rrespacker

Biblioteca base: rres.h

A biblioteca base rres é responsável por ler pedaços de recursos de arquivos rres em uma estrutura de recurso genérica, retornada ao usuário. A estrutura de recursos exposta pelo usuário rresResourceChunk segue a estrutura de especificações rres ( rresResourceChunkInfo + rresResourceChunkData ). As seguintes estruturas são fornecidas:

• rresResourceChunk contém um único bloco com informações e dados exigidos pelo usuário: rresResourceChunkInfo + rresResourceChunkData
• rresresourceChunkInfo contém as informações sobre o bloco de recursos carregado
• rresResourceChunkData contém os dados reais do recurso: as propriedades necessárias e os dados brutos. É importante observar que caso os dados tenham sido compactados/criptografados, cabe à biblioteca do usuário ( rres-raylib.h ) processar esses dados; nesses casos, chunk.data.raw contém os dados compactados/criptografados e chunk.data.propCount = 0 e chunk.data.props = NULL ; cabe à biblioteca do usuário preencher as propriedades após a descompactação/descriptografia.
• rresResourceMulti contém vários rresResourceChunks para um arquivo de entrada processado

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

Um único rresResourceChunk pode ser carregado do arquivo .rres com a função fornecida: rresLoadResourceChunk() e descarregado com rresUnloadResourceChunk() .

Um rresResourceMulti completo pode ser carregado do arquivo .rres com a função fornecida: rresLoadResourceMulti() e descarregado com rresUnloadResourceMulti() .

Biblioteca de mapeamento do mecanismo: rres-raylib.h

A biblioteca de mapeamento inclui rres.h e fornece funcionalidade para mapear os dados dos blocos de recursos carregados do arquivo rres em estruturas raylib . A API fornecida é simples e intuitiva, seguindo as convenções 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

Observe que a descompactação/descriptografia de dados é implementada nesta biblioteca personalizada, UnpackResourceChunk() é fornecida para os usuários. rresResourceChunk contém valores de identificador de compressor/cifra por conveniência. O suporte a compressores e cifras depende da implementação do usuário e deve estar alinhado com a ferramenta de empacotamento ( rrespacker ).

O formato de arquivo rres é independente do mecanismo, bibliotecas e ferramentas podem ser criadas para qualquer mecanismo/estrutura em qualquer linguagem de programação.

Ferramenta de embalagem: rrespacker

rrespacker é a ferramenta de empacotamento rres responsável por processar todos os arquivos de entrada e criar o arquivo rres , seguindo a especificação. Caso alguns algoritmos de compressão/criptografia sejam suportados, eles deverão ser implementados por esta ferramenta e os mesmos algoritmos deverão ser suportados pela biblioteca de mapeamento, no nosso caso rres-raylib.h .

Fig 03. Ferramenta rrespacker, interface GUI, também suporta CLI para processamento em lote.

rrespacker pode ser usado online (ou baixado) em itch.io.

Versões

• rres v1.0 (12 de maio de 2022) – Primeira versão da especificação.

Licença

As especificações de formato de arquivo rres , a biblioteca rres.h e a biblioteca rres-raylib.h são licenciadas sob licença MIT. Verifique LICENÇA para mais detalhes.

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