ホーム>プログラミング関連>C# ソースコード
ダウンロード
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構造はシンプルで、1 つのファイル ヘッダーと複数のリソースが次々に続きます。それでも、すべてのリソースには、複数のオプションを使用できる小さな (32 バイト) リソース情報ヘッダーがあります。

  • 使いやすさ: .rresファイルを読み取るためのrresライブラリは小さく、その ID からリソース データを読み取るために必要な最小限の関数のみを備えています。標準 C ライブラリの少数の関数セットのみを使用します。 .rresファイルを簡単に作成および表示できるように、GUI/CLI を備えたrrespackerツールが提供されています。

  • 柔軟性: rres形式はあらゆる種類の入力ファイルをサポートします。データが基本データ型として分類されていない場合は、そのまま生ファイル データとしてパックできます。

  • 移植性: rresファイル形式は特定のエンジンに関連付けられておらず、ベース ライブラリはリソース データをパックされた状態で読み取るだけであり、そのデータは任意のエンジン構造にマッピングできます。使用例は、rres データを raylib 構造にマップする補助ライブラリrres-raylib.hで提供されています。

  • セキュリティ: rres必要に応じてリソースごとの圧縮と暗号化をサポートします。ファイル形式によってサポートが提供されているにもかかわらず、それをrresパッカー ツールとエンジン マッピング ライブラリに実装するかどうかはユーザー次第です。 rres設計上、特定の圧縮/暗号化アルゴリズムを強制しません。

  • 拡張性: rresファイル形式は拡張可能で、必要に応じて新しいデータ型、新機能、カスタム データをサポートします。

  • 無料でオープン ソース: rresオープン仕様であり、無料でオープン ソース ライブラリです。提供されたツール ( rrespacker ) と一緒に使用することも、カスタム パッカー/ローダーを任意のエンジンに実装することもできます。形式の説明は、独自のデータ パッケージ ファイル形式を作成したい人のための学習教材としても使用できます。

利用特典

ゲーム アセット データをrresのような形式にパッケージ化する重要な理由がいくつかあります。ここでは、そうする正当な理由をいくつか示します。

  • 編成: 最終的なゲーム ビルドでは、数百のディレクトリに数千のファイルが分散されるのを避けます。すべてのゲーム ファイル データは、1 つまたはいくつかの.rresファイルに編成できます。これにより、ゲーム ディレクトリがクリーンで適切な構造に保たれます。

  • パフォーマンス: レベル/マップに必要なすべてのファイルを 1 つの.rresファイルに保存すると、複数のファイルにアクセスするためのファイル ハンドルの必要性が減ります。ファイル ハンドルは OS のリソースであり、ファイルを開くコストは少なからずあり、ゲームの遅延を引き起こす可能性があります。 .rresファイル内のデータ アクセス時間も重要であり、ファイルの編成方法によっては読み込み時間も短縮される可能性があります。

  • セキュリティ: 簡単にコピーまたは変更できるように、すべてのゲーム アセットをユーザーに直接公開することは避けてください。 .rresファイルにパックされたデータは、ほとんどのユーザーにとって抽出および変更がより困難になります。ゲームの著作権で保護された資産を保護します。 rresリソースごとのデータ圧縮と暗号化もサポートしており、必要に応じてセキュリティのレベルをさらに高めます。

  • ダウンロード時間: データをサーバーからアクセスしてダウンロードする必要がある場合、アセットを 1 つまたはいくつかの.rresファイルにパックすると、各ファイルを個別にダウンロードする場合と比較して、ダウンロード時間が短縮されます。

設計の歴史

rres 2014 年から開発されています。私は、raylib 用の XNB に似たパッケージング ファイル形式を作成することを目的として、このプロジェクトを開始しました。過去8 年間、プロジェクトはファイル形式の学習プロセスに沿って複数回の再設計と改善を繰り返してきました。その間に、 +20 種類の異なるファイル形式用のローダー/ライターを実装し、複数の raylibtech カスタム ツール用に+12 種類のカスタム ファイル形式も作成しました。

rresファイル形式は、少なくとも4 つの大きな再設計を経ています。

  • フォーマットの最初の設計は、リソースを 1 つずつパッケージ化することに限定されており、すべてのリソースは 1 つのリソース情報ヘッダーと、その後に続く 4 つの可能なパラメーターの固定セットとリソース データで構成されていました。 .rresファイルに沿って、リソース ファイル名 (通常は未処理データの元のファイル名) を使用してrresId定義するマッピングの.hヘッダー ファイルが生成されました。このモデルは非常にシンプルで直感的でしたが、いくつかの重要な欠点がありました。複数のチャンクを必要とする可能性のある複雑なデータ部分が考慮されておらず、元のソース ファイル (または類似のソース ファイル) を抽出/取得する方法がありませんでした。

  • 2 番目の設計はより複雑で、最初の設計の欠点を解決しようとしました。 2 番目の設計では、すべてのリソースに、一種のツリー構造の複数のデータ チャンクを含めることができます。実際、その設計は RIFF ファイル形式に似ていました。すべてのチャンクに追加のチャンクを含めることができ、それぞれにヘッダーとデータが含まれていました。追加のリソース オプションもいくつか追加されましたが、形式の理解と管理が非常に複雑になりました。最後に、テスト実装は破棄され、より単純な代替案が検討されました。

  • 3 番目の設計は最初の設計に戻り、シンプルですが、個々のリソースのオプションの一部を保持しています。単一の入力ファイルから生成された複数のリソースの問題は、必要に応じて次のリンクされたリソースを指すリソース情報ヘッダーの単純なオフセット フィールドを使用して解決されました。リソースはリソース チャンクの配列としてロードされました。入力ファイルの参照を保持するために、オプションの中央ディレクトリ リソース チャンクが追加されました。フォーマットは良好でしたが、それでも実装とさらなる調査が必要で、エンジンに依存しない必要があり、依然として raylib の構造と機能に依存していました。

  • 4 番目の設計は実装に沿って行われ、ほぼすべての構造とフィールドが見直され、一貫性と簡素化のために名前が変更されました。ロードされたリソース データをカスタム ライブラリ/エンジン データ型にマップするために別のライブラリ ( rres-raylib.h ) が作成され、raylib への依存関係が削除され、完全にエンジンに依存しないファイル形式になりました。 rresのライブラリとエンジンの接続を示すために、raylib のいくつかの使用例が実装されており、複数のタイプのリソース読み込みが実装されています。 rrespackerツールは、 rresファイルを生成するために最初から作成されており、ドラッグ アンド ドロップをサポートする優れた GUI インターフェイスだけでなく、バ​​ッチ処理用の強力なコマンド ラインもサポートしています。圧縮と暗号化の実装は、パッケージ化ツールと連携してrresファイル形式をよりクリーンかつシンプルに保つためにユーザー ライブラリの実装に移動されました。

これは8 年間のプロジェクトであり、何度も再設計と修正を繰り返しながら作業を続けてきましたが、個人的には最終結果に非常に満足しています。 rres 、プロフェッショナルなエンジン パッケージ形式のレベルにあるリソース パッケージング ファイル形式ですが、無料でオープンソースであり、使用、実装、またはカスタム バージョンの作成を希望するゲーム開発者が利用できます。

ファイル構造

rres ファイル形式は、ファイル ヘッダー ( rresFileHeader ) とそれに続く多数のリソース チャンク ( rresResourceChunk ) で構成されます。すべてのリソース チャンクには、 FOURCCデータ型コードとリソース データ情報を含むリソース情報ヘッダー ( rresResourceChunkInfo ) があります。リソース データ ( rresResourceChunkData ) には、タイプに応じてデータを識別するための小さなプロパティ セットが含まれており、最後に追加データが含まれる場合があります。

図 01. rres v1.0 ファイル構造。

注: rresResourceChunk は入力ファイルから生成されます。リソースはファイルに 1 対 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 4 文字である必要があります。
versionフォーマットのバージョンとサブバージョンを定義します。
chunkCountファイル内に存在するリソース チャンクの数。処理される入力ファイルの数よりも大きくなる可能性があることに注意してください。
cdOffsetファイル内の中央ディレクトリの絶対オフセットCDIRは単なるリソース チャンク タイプであり、中央ディレクトリはファイル内に存在する場合も存在しない場合もあります。カスタムrresパッカーが実装されている場合は、ファイル内の最後のチャンクとして配置することをお勧めします。詳細については、 rresCentralDirセクションを確認してください。
reservedこのフィールドは、必要に応じて将来の追加のために予約されています。

表 01. rresFileHeaderフィールドの説明と詳細

考慮事項:

  • rresファイルは設計により最大 65535 リソース チャンクに制限されており、より多くのリソースをパックする必要がある場合に備えて、複数のrresファイルを作成することをお勧めします。
  • rresファイルは、さまざまなリソース チャンクrresアドレス指定するために 32 ビット オフセットを使用するため、最大 4GB を超えるデータをアドレス指定できません。rres ファイルは4GB未満にしてください。リソースをパッケージ化するためにさらに多くのスペースが必要な場合は、複数のrresファイルを作成します。

リソースチャンク: rresResourceChunk

rresファイルには、多数のリソース チャンクが含まれています。すべてのリソース チャンクは、自己完結型のデータ パックを表します。リソース チャンクは、 rresパッカー ツールによるrresファイル作成時に入力ファイルから生成されます。ファイル拡張子に応じて、 rresパッカー ツールはファイルから必要なデータを抽出し、1 つ以上のリソース チャンクを生成します。たとえば、画像ファイルの場合、画像のピクセル データとそのデータをリソース ファイルから読み取るために必要なプロパティのみを含むRRES_DATA_IMAGE typeのリソース チャンクが生成されます。

rresファイルの作成時に、1 つの入力ファイルで複数のリソース チャンクが生成される可能性があることに注意することが重要です。たとえば、 .ttf入力ファイルは、 RRES_DATA_IMAGEリソース チャンクとRRES_DATA_FONT_GLYPHSリソース チャンクを生成できます。ファイルを単純なRRES_DATA_RAWリソース チャンク タイプとしてパックすることもできます。その場合、入力ファイルは処理されず、生データとしてパックされるだけです。

rres作成時に、 rresパッカーは、処理された入力ファイルに関するデータを含むRRES_DATA_DIRECTORYタイプの追加のリソース チャンクを作成する可能性があります。場合によっては、入力ファイル名を生成されたリソース ID に直接関連付けたり、元の入力ファイルと同様のファイル構造でデータを抽出したりする場合に便利です。

すべてのリソース チャンクは、 rresResourceChunkInfo + rresResourceDataの 2 つの部分に分割されます。

リソースチャンク情報: 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 ハッシュを使用して入力ファイル名から生成され、一意ではありません。 1 つの入力ファイルで複数のリソース チャンクを生成でき、生成されたすべてのチャンクは同じ識別子を共有し、リソースのロード時に一緒にロードされます。たとえば、入力 .ttf は、同じ識別子を持つ 2 つのリソース チャンク ( RRES_DATA_IMAGE + RRES_DATA_FONT_GLYPHS ) を生成し、それらの識別子が要求されたときに一緒にロードされる可能性があります。ロードされたデータをどうするかはユーザーが決定します。
compTypeリソースチャンクデータに使用される圧縮アルゴリズムを定義します。圧縮は rres とエンジンの間の中間ライブラリに依存します。rres.h rres.h 、圧縮を実装する場合に使用されるいくつかの有用なアルゴリズム値を定義するだけです。圧縮は常に暗号化の前に適用する必要があり、完全なrresResourceData ( Property Count + Properties[] + Data ) が圧縮されます。データ暗号化が適用されない場合、 packedSize圧縮データのサイズを定義します。
cipherTypeリソースチャンクデータに使用される暗号化アルゴリズムを定義します。圧縮と同様に、暗号化は rres とエンジンの間の中間ライブラリに依存します。rres.h 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

rresResourceChunkInfoで指定されたリソースtype 、リソース チャンクに含まれるデータのタイプとプロパティの数を定義します。

ここでは現在定義されているデータ型を示します。一部の入力ファイルは、複数のタイプの複数のリソース チャンクを生成する可能性があることに注意してください。必要に応じて、追加のリソース タイプを追加できます。 

 // 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小道具数小道具データ
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] :cultureCode		テキストデータ
RRES_DATA_IMAGE IMGE 4 props[0] :幅
props[1] :高さ
props[2] : rresPixelFormat
props[3] :ミップマップ		ピクセルデータ
RRES_DATA_WAVE WAVE 4 props[0] :frameCount
props[1] :サンプルレート
props[2] :サンプルサイズ
props[3] :チャンネル		オーディオサンプルデータ
RRES_DATA_VERTEX VRTX 4 props[0] :vertexCount
props[1] : rresVertexAttribute
props[2] :componentCount
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 拡張子は、ドットで始まるcharバイトの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利用可能な場合にrresファイルからCentral Directoryをロードする関数rresLoadCentralDirectory()と、元のファイル名からリソース識別子を取得する関数rresGetIdFromFileName()を提供します。

Central Directoryを使用せずにrresファイルが生成される場合は、ユーザー コードで使用するために、すべてのリソースの ID 参照を含むセカンダリ ヘッダー ファイル ( .h ) を提供する必要があります。

カスタムエンジンの実装

rresは、あらゆるゲーム エンジンで使用できる、エンジンに依存しないファイル形式として設計されています。 rresを採用する開発者は、カスタム ライブラリとカスタム抽象化を実装して、 rres汎用データを独自のエンジン データ構造とカスタムrresパッケージ化ツールにマッピングできます。

次の図は、 raylibライブラリのrresのサンプル実装を示しています。

図 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 、提供されている関数rresLoadResourceChunk()を使用して.rresファイルからロードし、 rresUnloadResourceChunk()でアンロードできます。

完全なrresResourceMulti 、提供されている関数rresLoadResourceMulti()を使用して.rresファイルからロードし、 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 ツール、GUI インターフェイス。バッチ処理用の CLI もサポートしています。

rrespacker itch.io からオンライン (またはダウンロード) で使用できます。

バージョン

  • rres v1.0 (2022 年 5 月 12 日) - 仕様の最初のリリース。

ライセンス

rresファイル形式の仕様、 rres.hライブラリ、およびrres-raylib.hライブラリは、MIT ライセンスに基づいてライセンスされています。詳細についてはライセンスを確認してください。

Copyright (c) 2014-2024 ラモン・サンタマリア (@raysan5)

拡大する
追加情報
関連アプリ
おすすめ
関連情報 すべて