Beranda>Terkait pemrograman>kode sumber C#
Unduh
rres


rres adalah format file yang sederhana dan mudah digunakan untuk mengemas sumber daya

rres telah dirancang untuk mengemas aset game (gambar, font, teks, audio, model...) ke dalam format komprehensif mandiri yang sederhana, mudah dibaca dan ditulis, dirancang untuk memuat data dengan cara yang cepat dan efisien.

rres terinspirasi oleh format file berikut: XNB (digunakan oleh XNA/MonoGame), RIFF, PNG dan ZIP.



Indeks

  1. Tujuan Desain
  2. Manfaat Penggunaan
  3. Sejarah Desain
  4. Struktur Berkas
  5. Tajuk Berkas: rresFileHeader
  6. Potongan Sumber Daya: rresResourceChunk
    1. Info Potongan Sumber Daya: rresResourceChunkInfo
    2. Data Potongan Sumber Daya: rresResourceChunkData
    3. Tipe Data Sumber Daya: rresResourceDataType
    4. Potongan Sumber Daya: Direktori Pusat: rresCentralDir
  7. Implementasi Mesin Kustom
  8. Lisensi

Tujuan Desain

  • Kesederhanaan : struktur rres sederhana, satu header file dan banyak sumber daya satu demi satu. Namun, setiap sumber daya memiliki header info sumber daya kecil (32 byte) dengan beberapa opsi yang tersedia.

  • Kemudahan penggunaan : perpustakaan rres untuk membaca file .rres berukuran kecil dengan hanya fungsi minimum yang diperlukan untuk membaca data sumber daya dari idnya. Ini hanya menggunakan sejumlah kecil fungsi dari perpustakaan C standar. Alat rrespacker dengan GUI/CLI disediakan untuk membuat dan melihat file .rres dengan mudah.

  • Fleksibilitas : format rres mendukung segala jenis file input, jika data tidak diklasifikasikan sebagai tipe data dasar maka dapat dikemas sebagai data file mentah saja.

  • Portabilitas : format file rres tidak terikat pada mesin tertentu, pustaka dasar hanya membaca data sumber daya sebagai paket dan data tersebut dapat dipetakan ke struktur mesin mana pun. Contoh penggunaan telah disediakan dengan perpustakaan tambahan rres-raylib.h yang memetakan data rres ke struktur raylib.

  • Keamanan : rres mendukung kompresi dan enkripsi per sumber daya jika diperlukan. Namun, meskipun format file mendukung, pengguna tetap harus mengimplementasikannya di alat rres packer dan pustaka pemetaan mesin. rres tidak memaksakan algoritma kompresi/enkripsi tertentu sesuai desainnya

  • Ekstensibilitas : format file rres dapat diperluas, mendukung tipe data baru, fitur baru, dan data khusus jika diperlukan.

  • Gratis dan sumber terbuka : rres adalah spesifikasi terbuka dan perpustakaan sumber terbuka dan gratis. Ini dapat digunakan dengan alat yang disediakan ( rrespacker ) atau pengemas/pemuat khusus dapat diterapkan untuk mesin apa pun . Deskripsi format tersebut juga dapat dijadikan sebagai bahan pembelajaran bagi siapapun yang ingin membuat sendiri format file pengemasan datanya.

Manfaat Penggunaan

Ada beberapa alasan penting untuk mengemas data aset game ke dalam format seperti rres , berikut beberapa alasan bagus untuk melakukannya.

  • Organisasi : Hindari ribuan file yang didistribusikan di ratusan direktori dalam pembuatan game terakhir. Semua data file game dapat diatur dalam satu atau beberapa file .rres . Itu membuat direktori permainan tetap bersih dan terstruktur dengan baik.

  • Kinerja : Menyimpan semua file yang diperlukan untuk suatu level/peta ke dalam satu file .rres mengurangi kebutuhan pegangan file untuk mengakses banyak file; pegangan file adalah sumber daya OS dan biaya membuka file tidak sedikit, hal ini dapat menyebabkan penundaan dalam permainan. Waktu akses data di dalam file .rres juga penting dan bergantung pada cara file diatur, waktu pemuatan juga dapat ditingkatkan.

  • Keamanan : Hindari memaparkan semua aset game secara langsung kepada pengguna agar mudah disalin atau dimodifikasi. Data yang dikemas ke dalam file .rres akan lebih sulit untuk diekstraksi dan dimodifikasi bagi sebagian besar pengguna; lindungi aset berhak cipta game Anda. rres juga mendukung kompresi dan enkripsi data per sumber daya, menambahkan tingkat keamanan ekstra bila diperlukan.

  • Waktu pengunduhan : Jika data perlu diakses dari server dan diunduh, aset yang dikemas ke dalam satu atau beberapa file .rres meningkatkan waktu pengunduhan, dibandingkan dengan mengunduh setiap file satu per satu.

Sejarah Desain

rres telah dikembangkan sejak 2014 . Saya memulai proyek ini dengan tujuan untuk membuat format file kemasan yang mirip dengan XNB untuk raylib. Dalam 8 tahun terakhir, proyek ini telah mengalami banyak desain ulang dan perbaikan sepanjang proses pembelajaran format file. Saat itu saya menerapkan pemuat/penulis untuk +20 format file berbeda dan juga membuat +12 format file khusus untuk beberapa alat khusus raylibtech.

Format file rres telah melalui setidaknya 4 desain ulang besar :

  • Desain pertama format ini terbatas pada pengemasan sumber daya satu demi satu, setiap sumber daya terdiri dari satu header info sumber daya diikuti dengan kumpulan empat parameter yang mungkin dan data sumber daya. Di sepanjang file .rres , file header .h dibuat pemetaan dengan mendefinisikan rresId dengan nama file sumber daya (biasanya nama file asli dari data yang belum diproses). Model ini cukup sederhana dan intuitif, namun memiliki beberapa kelemahan penting: model ini tidak mempertimbangkan bagian data kompleks yang memerlukan banyak bagian dan tidak ada cara untuk mengekstrak/mengambil file sumber asli (atau yang serupa).

  • Desain kedua jauh lebih kompleks dan mencoba mengatasi kekurangan desain pertama. Dalam desain kedua, setiap sumber daya dapat mencakup banyak potongan data dalam semacam struktur pohon. Sebenarnya, desain tersebut mirip dengan format file RIFF: setiap potongan dapat berisi potongan tambahan, masing-masing dengan header dan datanya sendiri. Beberapa opsi sumber daya tambahan juga ditambahkan tetapi formatnya menjadi cukup rumit untuk dipahami dan dikelola. Akhirnya, implementasi pengujian dibuang dan alternatif yang lebih sederhana diselidiki.

  • Desain ketiga adalah kembali ke desain pertama: kesederhanaan namun tetap mempertahankan beberapa opsi untuk sumber daya individual. Masalah beberapa sumber daya yang dihasilkan dari satu file masukan diselesaikan dengan menggunakan bidang offset sederhana di header info sumber daya yang menunjuk ke sumber daya tertaut berikutnya bila diperlukan. Sumber daya dimuat sebagai larik potongan sumber daya. Potongan sumber daya Direktori Pusat opsional telah ditambahkan untuk menyimpan referensi untuk file input. Formatnya bagus tetapi masih memerlukan implementasi dan penyelidikan lebih lanjut, harus agnostik mesin dan masih bergantung pada struktur dan fungsionalitas raylib.

  • Desain keempat telah dilakukan sepanjang implementasi, hampir semua struktur dan bidang telah ditinjau dan diganti namanya untuk konsistensi dan kesederhanaan. Pustaka terpisah telah dibuat ( rres-raylib.h ) untuk memetakan data sumber daya yang dimuat ke dalam tipe data pustaka/mesin khusus, segala ketergantungan pada raylib telah dihapus, menjadikannya format file yang sepenuhnya tidak bergantung pada mesin. Beberapa contoh penggunaan raylib telah diterapkan untuk menggambarkan koneksi mesin perpustakaan rres dan berbagai jenis pemuatan sumber daya telah diterapkan. Alat rrespacker telah dibuat dari awal untuk menghasilkan file rres , alat ini mendukung antarmuka GUI yang bagus dengan dukungan drag and drop tetapi juga baris perintah yang kuat untuk pemrosesan batch. Implementasi kompresi dan enkripsi telah dipindahkan ke implementasi perpustakaan pengguna agar selaras dengan alat pengemasan dan menjaga format file rres lebih bersih dan sederhana.

Ini adalah proyek selama 8 tahun , dikerjakan terus-menerus, dengan banyak desain ulang dan revisi, tetapi saya pribadi sangat senang dengan hasil akhirnya. rres adalah format file pengemasan sumber daya pada tingkat format paket mesin profesional apa pun TETAPI gratis dan bersumber terbuka , tersedia untuk pengembang game mana pun yang ingin menggunakannya, mengimplementasikannya, atau membuat versi khusus.

Struktur Berkas

Format file rres terdiri dari header file ( rresFileHeader ) diikuti oleh sejumlah potongan sumber daya ( rresResourceChunk ). Setiap potongan sumber daya memiliki header info sumber daya ( rresResourceChunkInfo ) yang mencakup kode tipe data FOURCC dan informasi data sumber daya. Data sumber daya ( rresResourceChunkData ) berisi sekumpulan kecil properti untuk mengidentifikasi data, bergantung pada jenisnya dan dapat berisi beberapa data tambahan di bagian akhir.

Gambar 01. Struktur file rres v1.0.

CATATAN: rresResourceChunk(s) dihasilkan dari file input. Penting untuk dicatat bahwa sumber daya tidak dapat dipetakan ke file 1:1, satu file masukan dapat menghasilkan beberapa potongan sumber daya. Misalnya, file input .ttf dapat menghasilkan potongan sumber daya gambar (tipe RRES_DATA_IMAGE ) ditambah potongan sumber daya info font glyph (tipe 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
}

Tajuk Berkas: rresFileHeader

Struct C berikut mendefinisikan 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 ;
Bidang Keterangan
id Pengidentifikasi tanda tangan file, harus terdiri dari empat karakter: r , r , e , s .
version Mendefinisikan versi dan subversi format.
chunkCount Jumlah potongan sumber daya yang ada dalam file. Perhatikan bahwa ini bisa lebih besar dari jumlah file masukan yang diproses.
cdOffset Offset absolut Direktori Pusat dalam file, perhatikan bahwa CDIR hanyalah jenis potongan sumber daya lainnya, Direktori Pusat dapat ada dalam file atau tidak . Disarankan untuk ditempatkan sebagai potongan terakhir dalam file jika rres packer khusus diterapkan. Periksa bagian rresCentralDir untuk lebih jelasnya.
reserved Bidang ini dicadangkan untuk penambahan di masa mendatang jika diperlukan.

Tabel 01. Deskripsi dan detail kolom rresFileHeader

Pertimbangan:

  • file rres dibatasi menurut desain hingga maksimum 65535 potongan sumber daya , jika lebih banyak sumber daya yang perlu dikemas, disarankan untuk membuat beberapa file rres .
  • File rres menggunakan offset 32 ​​bit untuk menangani potongan sumber daya yang berbeda, akibatnya, data yang dapat ditangani tidak lebih dari ~4GB , harap simpan file rres lebih kecil dari 4GB . Jika diperlukan lebih banyak ruang untuk mengemas sumber daya, buat beberapa file rres .

Potongan Sumber Daya: rresResourceChunk

File rres berisi sejumlah potongan sumber daya. Setiap potongan sumber daya mewakili paket data mandiri. Potongan sumber daya dihasilkan dari file masukan pada pembuatan file rres oleh alat rres packer; bergantung pada ekstensi file, alat rres packer mengekstrak data yang diperlukan dari file dan menghasilkan satu atau lebih potongan sumber daya. Misalnya, untuk file gambar, potongan sumber daya type RRES_DATA_IMAGE dihasilkan hanya berisi data piksel gambar dan properti yang diperlukan untuk membaca kembali data tersebut dari file sumber daya.

Penting untuk dicatat bahwa satu file masukan dapat menghasilkan beberapa potongan sumber daya saat file rres dibuat. Misalnya, file input .ttf dapat menghasilkan potongan sumber daya RRES_DATA_IMAGE ditambah potongan sumber daya RRES_DATA_FONT_GLYPHS ; dimungkinkan juga untuk mengemas file sebagai tipe potongan sumber daya RRES_DATA_RAW biasa, dalam hal ini file input tidak diproses, hanya dikemas sebagai data mentah.

Pada pembuatan rres , rres packer dapat membuat potongan sumber daya tambahan bertipe RRES_DATA_DIRECTORY yang berisi data tentang file input yang diproses. Ini bisa berguna dalam beberapa kasus, misalnya untuk menghubungkan nama file masukan secara langsung ke id sumber daya yang dihasilkan dan juga untuk mengekstrak data dalam struktur file yang mirip dengan masukan asli.

Setiap potongan sumber daya dibagi menjadi dua bagian: rresResourceChunkInfo + rresResourceData .

Info Potongan Sumber Daya: rresResourceChunkInfo

Struct C berikut mendefinisikan 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 ;
Bidang Keterangan
type Kode FourCC dan mengidentifikasi jenis data sumber daya yang terdapat dalam rresResourceChunkData . Enum rresResourceDataType mendefinisikan beberapa tipe data, yang baru dapat ditambahkan jika diperlukan.
id Pengidentifikasi sumber daya global, dihasilkan dari input nama file menggunakan hash CRC32 dan tidak unik. Satu file masukan dapat menghasilkan beberapa potongan sumber daya, semua potongan yang dihasilkan memiliki pengidentifikasi yang sama dan dimuat bersama saat sumber daya dimuat. Misalnya, masukan .ttf dapat menghasilkan dua potongan sumber daya ( RRES_DATA_IMAGE + RRES_DATA_FONT_GLYPHS ) dengan pengidentifikasi yang sama yang akan dimuat bersama ketika pengidentifikasinya diminta. Terserah pengguna untuk memutuskan apa yang harus dilakukan dengan data yang dimuat.
compType Mendefinisikan algoritma kompresi yang digunakan untuk data potongan sumber daya. Kompresi bergantung pada perpustakaan tengah antara rres dan mesin, rres.h hanya mendefinisikan beberapa nilai algoritma yang berguna untuk digunakan dalam penerapan kompresi. Kompresi harus selalu diterapkan sebelum enkripsi dan mengompresi seluruh rresResourceData ( Property Count + Properties[] + Data ). Jika tidak ada enkripsi data yang diterapkan, packedSize menentukan ukuran data terkompresi.
cipherType Mendefinisikan algoritma enkripsi yang digunakan untuk data potongan sumber daya. Seperti kompresi, enkripsi bergantung pada perpustakaan tengah antara rres dan mesin, rres.h hanya mendefinisikan beberapa nilai algoritma yang berguna untuk digunakan dalam penerapan enkripsi. Enkripsi harus diterapkan setelah kompresi. Tergantung pada algoritma enkripsi dan mode enkripsi, mungkin memerlukan beberapa bagian data tambahan untuk dilampirkan ke data sumber daya (yaitu enkripsi MAC), ini tergantung pada implementasi dan alat rres packer/perpustakaan tengah rres untuk mesin bertanggung jawab untuk mengelolanya. data tambahan. Disarankan untuk ditambahkan saja ke data sumber daya dan dipertimbangkan packedSize .
flags Dicadangkan untuk tanda tambahan, jika diperlukan oleh implementasi.
packedSize Menentukan ukuran paket (terkompresi/terenkripsi + data pengguna tambahan) rresResourceChunkData . Data yang dikemas dapat berisi data pengguna yang ditambahkan di bagian akhir, setelah data terkompresi/terenkripsi, misalnya nonce/MAC untuk data terenkripsi, namun hal ini bergantung pada implementasi, dikelola oleh alat rres packer dan pustaka pengguna untuk memuat data potongan ke dalam struktur mesin sasaran.
baseSize Menentukan ukuran dasar (tidak terkompresi/tidak terenkripsi) rresResourceChunkData .
nextOffset Menentukan alamat posisi file global untuk potongan sumber daya terkait berikutnya, berguna untuk memasukkan file yang menghasilkan banyak sumber daya, seperti font atau jerat.
reserved Bidang ini dicadangkan untuk penambahan di masa mendatang jika diperlukan.
crc32 Dihitung berdasarkan potongan rresResourceData penuh ( packedSize ) dan dimaksudkan untuk mendeteksi kesalahan kerusakan data.

Tabel 02. Deskripsi dan detail bidang rresResourceChunkInfo

Data Potongan Sumber Daya: rresResourceChunkData

rresResourceChunkData berisi data berikut:

  • Property Count : Jumlah properti yang terkandung, bergantung pada type sumber daya
  • Properties[] : Properti yang diperlukan data sumber daya, bergantung pada type sumber daya
  • Data : Data mentah sumber daya, bergantung pada type sumber daya

CATATAN: rresResourceChunkData dapat berisi data pengguna tambahan, dalam hal ini ukuran data tambahan harus dipertimbangkan packedSize .

Tipe Data Sumber Daya: rresResourceDataType

type sumber daya yang ditentukan dalam rresResourceChunkInfo menentukan jenis data dan jumlah properti yang terdapat dalam potongan sumber daya.

Ini dia tipe data yang didefinisikan saat ini. Harap dicatat bahwa beberapa file masukan dapat menghasilkan beberapa potongan sumber daya dari berbagai jenis. Jenis sumber daya tambahan dapat ditambahkan jika diperlukan. 

 // 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 data yang didefinisikan saat ini terdiri dari properti dan data berikut:

jenis sumber daya EmpatCC propsCount alat peraga data
RRES_DATA_NULL NULL 0 - -
RRES_DATA_RAW RAWD 4 props[0] :ukuran
props[1] : extension01
props[2] : extension02
props[3] : dicadangkan		 byte file mentah
RRES_DATA_TEXT TEXT 4 props[0] :ukuran
props[1] : rresTextEncoding
props[2] : rresCodeLang
props[3] :Kode Budaya		 data teks
RRES_DATA_IMAGE IMGE 4 props[0] :lebar
props[1] :tinggi
props[2] : rresPixelFormat
props[3] :mipmaps		 data piksel
RRES_DATA_WAVE WAVE 4 props[0] :frameCount
props[1] :sampleRate
props[2] :Ukuran sampel
props[3] :saluran		 data sampel audio
RRES_DATA_VERTEX VRTX 4 props[0] :vertexCount
props[1] : rresVertexAttribute
props[2] :componentCount
props[3] : rresVertexFormat		 data simpul
RRES_DATA_FONT_GLYPHS FNTG 4 props[0] :Ukuran dasar
props[1] :glyphCount
props[2] :glyphPadding
props[3] : rresFontStyle		 rresFontGlyphInfo[0..glyphCount]
RRES_DATA_LINK LINK 1 props[0] :ukuran data jalur file
RRES_DATA_DIRECTORY CDIR 1 props[0] :entryCount rresDirEntry[0..entryCount]

Tabel 03. rresResourceDataType menentukan nilai dan detailnya

CATATAN: RRES_DATA_RAW berisi ekstensi file yang dikemas sebagai bagian dari propertinya, ekstensi char diubah menjadi nilai big-endian unsigned int 4-byte, dimulai dengan titik. yaitu ".png" => 0x2e706e67 . Jika ekstensi tidak relevan, penerapan pengguna dapat memutuskan untuk menyetel properti tersebut ke 0 .

rres.h mendefinisikan enums berikut untuk kenyamanan dalam menetapkan beberapa properti:

  • rresTextEncoding : Mendefinisikan beberapa kemungkinan pengkodean teks, nilai defaultnya adalah 0 (UTF-8)
  • rresCodeLang : Mendefinisikan beberapa bahasa pemrograman, berguna dalam hal menyematkan file kode atau skrip
  • rresPixelFormat : Mendefinisikan beberapa nilai format piksel untuk data piksel gambar
  • rresVertexAttribute : Mendefinisikan beberapa tipe atribut vertex untuk kenyamanan
  • rresVertexFormat : Mendefinisikan beberapa format data untuk data vertex
  • rresFontStyle : Mendefinisikan beberapa gaya font (Reguler, Tebal, Miring...), nilai defaultnya adalah 0 ( RRES_FONT_STYLE_DEFAULT )

Potongan Sumber Daya: Direktori Pusat: rresCentralDir

Potongan sumber daya Central Directory adalah potongan khusus yang bisa ada atau tidak ada dalam file rres , potongan ini menyimpan informasi tentang file input yang diproses untuk menghasilkan beberapa potongan sumber daya dan dapat berguna untuk:

  • Referensi sumber daya dengan nama file aslinya. Hal ini sangat berguna dalam implementasi untuk meminimalkan perubahan kode yang diperlukan jika pengemasan rres dilakukan pada proyek yang sudah ada atau di akhir pengembangan proyek, jika semua pemuatan file telah dilakukan menggunakan nama file secara langsung.

  • Ekstrak beberapa sumber daya ke file masukan serupa. Ini hanya mungkin terjadi jika file masukan tidak diproses dengan cara yang merusak. Misalnya, jika file a.ttf telah diproses untuk menghasilkan atlas gambar glyphs + info data glyphs, file .ttf asli tidak dapat diambil.

rres menyediakan beberapa struktur berguna untuk menangani data potongan sumber daya 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 ;

CATATAN: Entri nama file Direktori Pusat disejajarkan dengan padding 4-byte untuk meningkatkan waktu akses file.

rres.h menyediakan fungsi untuk memuat Central Directory dari file rres bila tersedia: rresLoadCentralDirectory() dan juga fungsi untuk mendapatkan pengidentifikasi sumber daya dari nama file aslinya: rresGetIdFromFileName() .

Jika file rres dibuat tanpa Central Directory , file header sekunder ( .h ) harus dilengkapi dengan referensi id untuk semua sumber daya, untuk digunakan dalam kode pengguna.

Implementasi Mesin Kustom

rres dirancang sebagai format file tanpa mesin yang dapat digunakan dengan mesin game apa pun. Pengembang yang mengadopsi rres dapat mengimplementasikan perpustakaan khusus dan abstraksi khusus untuk memetakan data generik rres ke struktur data mesin mereka sendiri dan juga alat pengemasan rres khusus .

Diagram berikut menunjukkan contoh implementasi rres untuk perpustakaan raylib .

Gambar 02. contoh implementasi rres: lib dan alat mesin khusus.

Implementasi rres terdiri dari beberapa bagian:

  • Perpustakaan dasar: rres.h
  • Pustaka pemetaan mesin: rres-raylib.h
  • Alat pengemas : rrespacker

Perpustakaan dasar: rres.h

Pustaka rres dasar bertugas membaca potongan sumber daya file rres ke dalam struktur sumber daya generik, yang dikembalikan ke pengguna. Struktur sumber daya yang diekspos pengguna rresResourceChunk mengikuti struktur spesifikasi rres ( rresResourceChunkInfo + rresResourceChunkData ). Struktur berikut disediakan:

  • rresResourceChunk berisi satu potongan dengan info dan data yang dibutuhkan pengguna: rresResourceChunkInfo + rresResourceChunkData
  • rresresourceChunkInfo berisi informasi tentang potongan sumber daya yang dimuat
  • rresResourceChunkData berisi data aktual untuk sumber daya: properti yang diperlukan dan data mentah. Penting untuk dicatat bahwa jika data dikompresi/dienkripsi, perpustakaan pengguna ( rres-raylib.h ) akan memproses data tersebut; dalam kasus tersebut chunk.data.raw berisi data terkompresi/terenkripsi dan chunk.data.propCount = 0 dan chunk.data.props = NULL ; terserah perpustakaan pengguna untuk mengisi properti setelah dekompresi/dekripsi.
  • rresResourceMulti berisi beberapa rresResourceChunks untuk file input yang diproses 
 // 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 ;

Satu rresResourceChunk dapat dimuat dari file .rres dengan fungsi yang disediakan: rresLoadResourceChunk() dan dibongkar dengan rresUnloadResourceChunk() .

rresResourceMulti lengkap dapat dimuat dari file .rres dengan fungsi yang disediakan: rresLoadResourceMulti() dan dibongkar dengan rresUnloadResourceMulti() .

Pustaka pemetaan mesin: rres-raylib.h

Pustaka pemetaan mencakup rres.h dan menyediakan fungsionalitas untuk memetakan data potongan sumber daya yang dimuat dari file rres ke dalam struktur raylib . API yang disediakan sederhana dan intuitif, mengikuti konvensi 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

Perhatikan bahwa dekompresi/dekripsi data diterapkan di perpustakaan khusus ini, UnpackResourceChunk() disediakan untuk pengguna. rresResourceChunk berisi nilai pengenal kompresor/cipher untuk kenyamanan. Dukungan kompresor dan sandi bergantung pada implementasi pengguna dan harus selaras dengan alat pengemasan ( rrespacker ).

Format file rres tidak bergantung pada mesin, pustaka dan alat dapat dibuat untuk mesin/kerangka apa pun dalam bahasa pemrograman apa pun.

Alat pengemas : rrespacker

rrespacker adalah alat pengepakan rres yang bertugas memproses semua file input dan membuat file rres , mengikuti spesifikasi. Jika beberapa algoritme kompresi/enkripsi didukung, maka algoritme tersebut harus diimplementasikan oleh alat ini dan algoritme yang sama harus didukung oleh pustaka pemetaan, dalam kasus kami rres-raylib.h .

Gambar 03. Alat rrespacker, antarmuka GUI, juga mendukung CLI untuk pemrosesan batch.

rrespacker dapat digunakan secara online (atau diunduh) dari itch.io.

Versi

  • rres v1.0 (12-Mei-2022) - Rilis spesifikasi pertama.

Lisensi

spesifikasi format file rres , perpustakaan rres.h dan perpustakaan rres-raylib.h dilisensikan di bawah lisensi MIT. Periksa LISENSI untuk rincian lebih lanjut.

Hak Cipta (c) 2014-2024 Ramon Santamaria (@raysan5)

Memperluas
Informasi Tambahan
Aplikasi Terkait
Direkomendasikan untuk Anda
Informasi Terkait Semua