الصفحة الرئيسية>المتعلقة بالبرمجة>كود مصدر 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 بسيطة، رأس ملف واحد وموارد متعددة واحدة تلو الأخرى. ومع ذلك، يحتوي كل مورد على رأس صغير لمعلومات المورد (32 بايت) مع خيارات متعددة متاحة.

  • سهولة الاستخدام : مكتبة rres لقراءة ملفات .rres صغيرة الحجم وتحتوي فقط على الحد الأدنى من الوظائف المطلوبة لقراءة بيانات الموارد من معرفها. يستخدم فقط مجموعة صغيرة من الوظائف من مكتبة C القياسية. يتم توفير أداة rrespacker مع واجهة المستخدم الرسومية/CLI لإنشاء ملفات .rres وعرضها بسهولة.

  • المرونة : يدعم تنسيق rres أي نوع من ملفات الإدخال، وإذا لم يتم تصنيف البيانات كنوع بيانات أساسي، فيمكن تجميعها كبيانات ملف أولية فقط.

  • قابلية النقل : تنسيق ملف rres غير مرتبط بمحرك معين، فالمكتبة الأساسية تقرأ فقط بيانات المورد كما هي معبأة ويمكن تعيين تلك البيانات إلى أي بنية محرك. تم توفير مثال للاستخدام مع المكتبة المساعدة rres-raylib.h التي تقوم بتعيين بيانات rres إلى بنيات raylib.

  • الأمان : يدعم rres الضغط والتشفير لكل مورد إذا لزم الأمر. ومع ذلك، على الرغم من الدعم الذي يقدمه تنسيق الملف، فإن الأمر متروك للمستخدم لتنفيذه في أداة rres packer ومكتبة تعيين المحرك. لا يفرض rres أي خوارزمية ضغط/تشفير محددة حسب التصميم

  • القابلية للتوسعة : تنسيق ملف rres قابل للتوسعة، ويدعم أنواع البيانات الجديدة والميزات الجديدة والبيانات المخصصة إذا لزم الأمر.

  • مصدر مجاني ومفتوح : rres عبارة عن مواصفات مفتوحة ومكتبة مجانية ومفتوحة المصدر. يمكن استخدامه مع الأداة المتوفرة ( rrespacker ) أو يمكن تنفيذ أداة تعبئة/محمل مخصصة لأي محرك . يمكن أيضًا استخدام وصف التنسيق كمواد تعليمية لأي شخص يرغب في إنشاء تنسيق ملف حزم البيانات الخاص به.

فوائد الاستخدام

هناك بعض الأسباب المهمة لحزم بيانات أصول اللعبة في تنسيق مثل rres ، إليك بعض الأسباب الوجيهة للقيام بذلك.

  • التنظيم : تجنب آلاف الملفات الموزعة في مئات الأدلة في النسخة النهائية للعبة. يمكن تنظيم جميع بيانات ملفات اللعبة في ملف واحد أو عدد قليل من ملفات .rres . فهو يحافظ على دليل اللعبة نظيفًا ومنظمًا بشكل جيد.

  • الأداء : يؤدي الاحتفاظ بجميع الملفات المطلوبة للمستوى/الخريطة في ملف .rres واحد إلى تقليل الحاجة إلى مؤشرات الملفات للوصول إلى ملفات متعددة؛ تعتبر مقابض الملفات أحد موارد نظام التشغيل وتكلفة فتح الملف ليست قليلة، فقد تتسبب في تأخيرات في اللعبة. تعد أوقات الوصول إلى البيانات داخل ملف .rres مهمة أيضًا، وقد يؤدي ذلك أيضًا إلى تحسين أوقات التحميل اعتمادًا على كيفية تنظيم الملفات.

  • الأمان : تجنب تعريض جميع أصول اللعبة مباشرة للمستخدم لسهولة النسخ أو التعديل. سيكون استخراج البيانات المعبأة في ملف .rres وتعديلها أكثر صعوبة بالنسبة لمعظم المستخدمين؛ حماية أصول لعبتك المحمية بحقوق الطبع والنشر. يدعم rres أيضًا ضغط البيانات وتشفيرها لكل مورد، مما يضيف مستوى إضافيًا من الأمان عند الحاجة.

  • أوقات التنزيل : إذا كانت هناك حاجة للوصول إلى البيانات من خادم وتنزيلها، فإن الأصول المجمعة في ملف واحد أو عدد قليل من ملفات .rres تعمل على تحسين أوقات التنزيل، مقارنة بتنزيل كل ملف على حدة.

تاريخ التصميم

لقد كان rres قيد التطوير منذ عام 2014 . لقد بدأت هذا المشروع بهدف إنشاء تنسيق ملف تعبئة مشابه لـ XNB لـ raylib. في السنوات الثماني الماضية، عانى المشروع من عمليات إعادة تصميم وتحسينات متعددة على طول عملية تعلم تنسيقات الملفات. في ذلك الوقت، قمت بتنفيذ أدوات التحميل/الكتابة لأكثر من 20 تنسيقًا مختلفًا للملفات وأنشأت أيضًا +12 تنسيقًا مخصصًا للملفات للعديد من أدوات raylibtech المخصصة.

لقد مر تنسيق الملف rres بما لا يقل عن 4 عمليات إعادة تصميم كبيرة :

  • اقتصر التصميم الأول للتنسيق على تعبئة مورد تلو الآخر، حيث يتكون كل مورد من رأس معلومات مورد واحد متبوعًا بمجموعة ثابتة من أربع معلمات محتملة وبيانات المورد. على طول الملف .rres ، تم إنشاء ملف رأس .h مع تحديد rresId باسم ملف المورد (عادةً ما يكون اسم الملف الأصلي للبيانات غير المعالجة). كان هذا النموذج بسيطًا جدًا وبديهيًا، ولكن له بعض الجوانب السلبية المهمة: فهو لم يأخذ في الاعتبار أجزاء البيانات المعقدة التي يمكن أن تتطلب أجزاء متعددة ولم تكن هناك طريقة لاستخراج/استرداد ملفات المصدر الأصلية (أو ملفات مماثلة).

  • كان التصميم الثاني أكثر تعقيدًا وحاول معالجة عيوب التصميم الأول. في التصميم الثاني، يمكن أن يتضمن كل مورد أجزاء متعددة من البيانات في نوع من البنية الشجرية. في الواقع، كان هذا التصميم مشابهًا لتنسيق ملف RIFF: يمكن أن تحتوي كل قطعة على أجزاء إضافية، كل واحدة لها رأسها وبياناتها. تمت إضافة بعض خيارات الموارد الإضافية أيضًا ولكن التنسيق أصبح معقدًا للغاية من حيث الفهم والإدارة. وأخيرا، تم تجاهل تنفيذ الاختبار وتم التحقيق في بديل أبسط.

  • كان التصميم الثالث عبارة عن عودة إلى التصميم الأول: البساطة مع الاحتفاظ ببعض الخيارات للموارد الفردية. تم حل مشكلة الموارد المتعددة التي تم إنشاؤها من ملف إدخال واحد باستخدام حقل إزاحة بسيط في رأس معلومات المورد يشير إلى المورد المرتبط التالي عند الحاجة. تم تحميل الموارد كمجموعة من قطع الموارد. تمت إضافة مجموعة موارد الدليل المركزي الاختيارية للاحتفاظ بمراجع ملفات الإدخال. كان التنسيق جيدًا ولكنه لا يزال يتطلب التنفيذ ومزيدًا من البحث، وكان بحاجة إلى أن يكون مستقلاً عن المحرك وكان لا يزال يعتمد على هياكل ووظائف رايليب.

  • تم تنفيذ التصميم الرابع أثناء التنفيذ، وتمت مراجعة جميع الهياكل والمجالات تقريبًا وإعادة تسميتها من أجل الاتساق والبساطة. تم إنشاء مكتبة منفصلة ( rres-raylib.h ) لتعيين بيانات الموارد المحملة إلى أنواع بيانات محرك/مكتبة مخصصة، وتمت إزالة أي تبعية لـ raylib، مما جعله تنسيق ملف لا يعتمد على المحرك تمامًا. تم تنفيذ العديد من أمثلة استخدام raylib لتوضيح اتصال محرك المكتبة لـ rres وتم تنفيذ أنواع متعددة من تحميل الموارد. تم إنشاء أداة rrespacker من البداية لإنشاء ملفات rres ، وهي تدعم واجهة المستخدم الرسومية الرائعة مع دعم السحب والإفلات ولكنها أيضًا تحتوي على سطر أوامر قوي لمعالجة الدفعات. تم نقل تنفيذ الضغط والتشفير إلى تطبيق مكتبة المستخدم ليتوافق مع أداة التغليف ويحافظ على تنسيق ملف rres أكثر نظافة وبساطة.

لقد استغرق المشروع 8 سنوات ، وعملت عليه بشكل متقطع، مع العديد من عمليات إعادة التصميم والمراجعات ولكني شخصيًا سعيد جدًا بالنتيجة النهائية. rres هو تنسيق ملف لتغليف الموارد على مستوى أي تنسيق حزمة محرك احترافي ولكنه مجاني ومفتوح المصدر ، وهو متاح لأي مطور ألعاب يرغب في استخدامه أو تنفيذه أو إنشاء إصدار مخصص.

هيكل الملف

يتكون تنسيق ملف rres من رأس ملف ( rresFileHeader ) متبوعًا بعدد من قطع الموارد ( rresResourceChunk ). تحتوي كل مجموعة مورد على رأس معلومات المورد ( rresResourceChunkInfo ) الذي يتضمن رمز نوع بيانات FOURCC ومعلومات بيانات المورد. تحتوي بيانات المورد ( rresResourceChunkData ) على مجموعة صغيرة من الخصائص لتحديد البيانات، اعتمادًا على النوع ويمكن أن تحتوي على بعض البيانات الإضافية في النهاية.

الشكل 01. بنية ملف rres v1.0.

ملاحظة: يتم إنشاء rresResourceChunk (s) من ملفات الإدخال. من المهم ملاحظة أنه لا يمكن تعيين الموارد للملفات 1:1، حيث يمكن لملف إدخال واحد إنشاء مجموعات موارد متعددة. على سبيل المثال، يمكن لملف إدخال ‎.ttf إنشاء مجموعة موارد صورة (نوع RRES_DATA_IMAGE ) بالإضافة إلى مجموعة موارد معلومات الحروف الرسومية للخط (نوع RRES_DATA_FONT_GLYPHS ). 

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

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

رأس الملف: rresFileHeader

تحدد بنية C التالية rresFileHeader : 

 // rres file header (16 bytes)
typedef struct rresFileHeader {
    unsigned char id [ 4 ];            // File identifier: rres
    unsigned short version ;         // File version: 100 for version 1.0
    unsigned short chunkCount ;      // Number of resource chunks in the file (MAX: 65535)
    unsigned int cdOffset ;          // Central Directory offset in file (0 if not available)
    unsigned int reserved ;          // 
} rresFileHeader ;
مجال وصف
id معرف توقيع الملف، يجب أن يكون بالأحرف الأربعة: r , r , e , s .
version يحدد الإصدار والتخريب من التنسيق.
chunkCount عدد قطع الموارد الموجودة في الملف. لاحظ أنه قد يكون أكبر من عدد ملفات الإدخال التي تمت معالجتها.
cdOffset الإزاحة المطلقة للدليل المركزي داخل الملف، لاحظ أن CDIR هو مجرد نوع آخر من قطع الموارد، ويمكن أن يكون الدليل المركزي موجودًا في الملف أم لا . من المستحسن أن يتم وضعها كقطعة أخيرة في الملف إذا تم تنفيذ أداة حزم rres مخصصة. تحقق من قسم rresCentralDir لمزيد من التفاصيل.
reserved هذا الحقل محجوز للإضافات المستقبلية إذا لزم الأمر.

الجدول 01. وصف حقول rresFileHeader وتفاصيلها

الاعتبارات:

  • تقتصر ملفات rres حسب التصميم على 65535 قطعة من الموارد كحد أقصى ، وفي حالة الحاجة إلى تعبئة المزيد من الموارد، يوصى بإنشاء ملفات rres متعددة.
  • تستخدم ملفات rres إزاحات 32 بت لمعالجة مجموعات الموارد المختلفة، وبالتالي، لا يمكن معالجة أكثر من 4 جيجابايت من البيانات ، يرجى الاحتفاظ بملفات rres أصغر من 4 جيجابايت . في حالة وجود مساحة أكبر مطلوبة لحزم الموارد، قم بإنشاء ملفات rres متعددة.

قطعة الموارد: rresResourceChunk

يحتوي ملف rres على عدد من قطع الموارد. يمثل كل جزء من الموارد حزمة بيانات قائمة بذاتها. يتم إنشاء قطع الموارد من ملفات الإدخال عند إنشاء ملف rres بواسطة أداة rres packer؛ اعتمادًا على امتداد الملف، تقوم أداة rres packer باستخراج البيانات المطلوبة من الملف وإنشاء قطعة موارد واحدة أو أكثر. على سبيل المثال، بالنسبة لملف صورة، يتم إنشاء مجموعة مورد من type RRES_DATA_IMAGE تحتوي فقط على بيانات البكسل الخاصة بالصورة والخصائص المطلوبة لقراءة تلك البيانات مرة أخرى من ملف المورد.

من المهم ملاحظة أن ملف إدخال واحد يمكنه إنشاء عدة مجموعات من الموارد عند إنشاء ملف rres . على سبيل المثال، يمكن لملف الإدخال .ttf إنشاء مجموعة موارد RRES_DATA_IMAGE بالإضافة إلى مجموعة موارد RRES_DATA_FONT_GLYPHS ؛ من الممكن أيضًا حزم الملف كنوع قطعة موارد RRES_DATA_RAW عادي، وفي هذه الحالة لا تتم معالجة ملف الإدخال، بل يتم تعبئته فقط كبيانات أولية.

عند إنشاء rres ، يمكن لـ rres packer إنشاء مجموعة موارد إضافية من النوع RRES_DATA_DIRECTORY تحتوي على بيانات حول ملفات الإدخال التي تمت معالجتها. قد يكون من المفيد في بعض الحالات، على سبيل المثال، ربط اسم ملف الإدخال مباشرة بمعرف المورد (الموارد) الذي تم إنشاؤه وكذلك استخراج البيانات في بنية ملف مماثلة للإدخال الأصلي.

يتم تقسيم كل جزء من الموارد إلى جزأين: rresResourceChunkInfo + rresResourceData .

معلومات قطعة الموارد: rresResourceChunkInfo

تحدد بنية C التالية rresResourceChunkInfo : 

 // rres resource chunk info header (32 bytes)
typedef struct rresResourceChunkInfo {
    unsigned char type [ 4 ];          // Resource chunk type (FourCC)
    unsigned int id ;                // Resource chunk identifier (generated from filename CRC32 hash)
    unsigned char compType ;         // Data compression algorithm
    unsigned char cipherType ;       // Data encription algorithm
    unsigned short flags ;           // Data flags (if required)
    unsigned int packedSize ;        // Data chunk size (compressed/encrypted + custom data appended)
    unsigned int baseSize ;          // Data base size (uncompressed/unencrypted)
    unsigned int nextOffset ;        // Next resource chunk global offset (if resource has multiple chunks)
    unsigned int reserved ;          // 
    unsigned int crc32 ;             // Data chunk CRC32 (propCount + props[] + data)
} rresResourceChunkInfo ;
مجال وصف
type رمز FourCC ويحدد نوع بيانات المورد الموجودة في ملف rresResourceChunkData . يحدد Enum rresResourceDataType عدة أنواع من البيانات، ويمكن إضافة أنواع جديدة إذا لزم الأمر.
id معرف مورد عالمي، يتم إنشاؤه من اسم ملف الإدخال باستخدام تجزئة CRC32 وهو ليس فريدًا. يمكن لملف إدخال واحد إنشاء مجموعات موارد متعددة، وجميع القطع التي تم إنشاؤها تشترك في نفس المعرف ويتم تحميلها معًا عند تحميل المورد. على سبيل المثال، يمكن لمدخل .ttf إنشاء قطعتين من الموارد ( RRES_DATA_IMAGE + RRES_DATA_FONT_GLYPHS ) بنفس المعرف الذي سيتم تحميله معًا عند طلب المعرف الخاص بهما. الأمر متروك للمستخدم ليقرر ما يجب فعله بالبيانات المحملة.
compType يحدد خوارزمية الضغط المستخدمة لبيانات قطعة المورد. يعتمد الضغط على المكتبة الوسطى بين rres والمحرك، rres.h فقط يحدد بعض قيم الخوارزمية المفيدة التي سيتم استخدامها في حالة تنفيذ الضغط. يجب دائمًا تطبيق الضغط قبل التشفير وهو يضغط rresResourceData بالكامل ( Property Count + Properties[] + Data ). إذا لم يتم تطبيق أي تشفير للبيانات، يحدد packedSize حجم البيانات المضغوطة.
cipherType يحدد خوارزمية التشفير المستخدمة لبيانات قطعة المورد. مثل الضغط، يعتمد التشفير على المكتبة الوسطى بين rres والمحرك، rres.h فقط يحدد بعض قيم الخوارزمية المفيدة التي سيتم استخدامها في حالة تنفيذ التشفير. يجب تطبيق التشفير بعد الضغط. اعتمادًا على خوارزمية التشفير ووضع التشفير، قد يتطلب الأمر إرفاق بعض البيانات الإضافية ببيانات المورد (أي تشفير MAC)، ويعتمد هذا على التنفيذ وتكون أداة rres packer / مكتبة rres المتوسطة للمحركات مسؤولة عن إدارة ذلك بيانات اضافية. من المستحسن أن يتم إلحاقها فقط ببيانات الموارد وأخذها بعين الاعتبار في packedSize .
flags محجوز للأعلام الإضافية، في حالة طلبها من خلال التنفيذ.
packedSize يحدد الحجم المعبأ (المضغوط/المشفر + بيانات المستخدم الإضافية) لـ rresResourceChunkData . يمكن أن تحتوي البيانات المجمعة على بيانات مستخدم ملحقة في النهاية، بعد البيانات المضغوطة/المشفرة، على سبيل المثال nonce/MAC للبيانات المشفرة، ولكنها تعتمد على التنفيذ، وتتم إدارتها بواسطة أداة rres packer ومكتبة المستخدم لتحميل بيانات القطع إلى هياكل المحرك المستهدفة.
baseSize يحدد الحجم الأساسي (غير المضغوط/غير المشفر) لـ rresResourceChunkData .
nextOffset يحدد عنوان موضع الملف العام لمجموعة الموارد ذات الصلة التالية، وهو مفيد لملفات الإدخال التي تولد موارد متعددة، مثل الخطوط أو الشبكات.
reserved هذا الحقل محجوز للإضافات المستقبلية إذا لزم الأمر.
crc32 يتم حسابه عبر مجموعة rresResourceData الكاملة ( packedSize ) ويهدف إلى اكتشاف أخطاء تلف البيانات.

الجدول 02. وصف وتفاصيل حقول rresResourceChunkInfo

بيانات قطعة المورد: rresResourceChunkData

يحتوي rresResourceChunkData على البيانات التالية:

  • Property Count : يعتمد عدد الخصائص الموجودة على type المورد
  • Properties[] : الخصائص المطلوبة لبيانات الموارد، تعتمد على type المورد
  • Data : البيانات الأولية للموارد، تعتمد على type المورد

ملاحظة: يمكن أن يحتوي rresResourceChunkData على بيانات مستخدم إضافية، وفي تلك الحالات يجب مراعاة حجم البيانات الإضافي في packedSize .

نوع بيانات المورد: rresResourceDataType

يحدد type المورد المحدد في rresResourceChunkInfo نوع البيانات وعدد الخصائص الموجودة في قطعة المورد.

هنا هي أنواع البيانات المحددة حاليا. يرجى ملاحظة أن بعض ملفات الإدخال يمكن أن تولد مجموعات موارد متعددة من أنواع متعددة. يمكن إضافة أنواع موارد إضافية إذا لزم الأمر. 

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

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

تتكون types البيانات المحددة حاليًا من الخصائص والبيانات التالية:

نوع المورد فور سي سي propsCount الدعائم بيانات
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] : كود الثقافة		 بيانات نصية
RRES_DATA_IMAGE IMGE 4 props[0] : العرض
props[1] : الارتفاع
props[2] : rresPixelFormat
props[3] :mipmaps		 بيانات البكسل
RRES_DATA_WAVE WAVE 4 props[0] :frameCount
props[1] : معدل العينة
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 إلى قيمة unsigned int 4 بايت، تبدأ بنقطة. أي ".png" => 0x2e706e67 . إذا لم يكن الامتداد ذا صلة، فيمكن أن يقرر تنفيذ المستخدم تعيين هذه الخصائص على 0 .

يعرّف rres.h enums التالية لتسهيل تعيين بعض الخصائص:

  • rresTextEncoding : يحدد العديد من ترميزات النص الممكنة، القيمة الافتراضية هي 0 (UTF-8)
  • rresCodeLang : يحدد عدة لغات برمجة، وهو مفيد في حالة تضمين ملفات التعليمات البرمجية أو البرامج النصية
  • rresPixelFormat : يحدد قيم تنسيق البكسل المتعددة لبيانات بكسل الصورة
  • rresVertexAttribute : يحدد عدة أنواع من سمات قمة الرأس للراحة
  • rresVertexFormat : يحدد العديد من تنسيقات البيانات لبيانات قمة الرأس
  • rresFontStyle : يحدد العديد من أنماط الخطوط (Regular، Bold، Italic...)، القيمة الافتراضية هي 0 ( RRES_FONT_STYLE_DEFAULT )

قطعة الموارد: الدليل المركزي: rresCentralDir

مجموعة موارد Central Directory هي مجموعة خاصة يمكن أن تكون موجودة أو غير موجودة في ملف rres ، فهي تقوم بتخزين معلومات حول ملفات الإدخال التي تمت معالجتها لإنشاء مجموعات الموارد المتعددة ويمكن أن تكون مفيدة لـ:

  • قم بالإشارة إلى الموارد حسب اسم الملف الأصلي الخاص بها. يعد هذا مفيدًا جدًا من حيث التنفيذ لتقليل تغييرات التعليمات البرمجية المطلوبة إذا تم تنفيذ حزمة rres عبر مشروع موجود أو في نهاية تطوير المشروع، إذا تم تحميل جميع الملفات باستخدام أسماء الملفات مباشرة.

  • استخراج بعض الموارد إلى ملف إدخال مماثل. سيكون ذلك ممكنًا فقط إذا لم تتم معالجة ملف الإدخال بطريقة مدمرة. على سبيل المثال، إذا تمت معالجة ملف a.ttf لإنشاء أطلس صورة رسومية + معلومات بيانات الحروف الرسومية، فلن يكون من الممكن استرداد ملف .ttf الأصلي.

يوفر rres بعض الهياكل المفيدة للتعامل مع بيانات مجموعة موارد Central Directory : 

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

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

ملاحظة: تتم محاذاة إدخالات اسم ملف الدليل المركزي مع مساحة 4 بايت لتحسين أوقات الوصول إلى الملفات.

يوفر rres.h وظيفة لتحميل Central Directory من ملف rres عند توفره: rresLoadCentralDirectory() وأيضًا وظيفة للحصول على معرفات الموارد من اسم الملف الأصلي: rresGetIdFromFileName() .

في حالة إنشاء ملف rres بدون Central Directory ، يجب توفير ملف رأس ثانوي ( .h ) مع مراجع المعرف لجميع الموارد، لاستخدامه في رمز المستخدم.

تنفيذ المحرك المخصص

تم تصميم rres كتنسيق ملف لا يعتمد على المحرك ويمكن استخدامه مع أي محرك ألعاب. يمكن للمطورين الذين يستخدمون rres تنفيذ مكتبة مخصصة وتجريد مخصص لتعيين بيانات rres العامة إلى هياكل بيانات محركاتهم الخاصة وكذلك أدوات تغليف rres المخصصة .

يوضح الرسم البياني التالي نموذجًا لتطبيق rres لمكتبة raylib .

الشكل 02. تنفيذ عينة rres: libs المحرك المخصص والأداة.

يتكون تنفيذ rres من عدة أجزاء:

  • المكتبة الأساسية: rres.h
  • مكتبة تعيين المحرك: rres-raylib.h
  • أداة التغليف: rrespacker

المكتبة الأساسية: rres.h

مكتبة rres الأساسية هي المسؤولة عن قراءة أجزاء موارد ملفات rres في بنية الموارد العامة، والتي يتم إرجاعها إلى المستخدم. يتبع المستخدم بنية الموارد المكشوفة rresResourceChunk بنية مواصفات rres ( rresResourceChunkInfo + rresResourceChunkData ). يتم توفير الهياكل التالية:

  • يحتوي rresResourceChunk على قطعة واحدة تحتوي على المعلومات والبيانات التي يطلبها المستخدم: rresResourceChunkInfo + rresResourceChunkData
  • يحتوي rresresourceChunkInfo على معلومات حول مجموعة الموارد المحملة
  • يحتوي rresResourceChunkData على البيانات الفعلية للمورد: الخصائص المطلوبة والبيانات الأولية. من المهم ملاحظة أنه في حالة ضغط/تشفير البيانات، فإن الأمر متروك لمكتبة المستخدم ( rres-raylib.h ) لمعالجة تلك البيانات؛ في هذه الحالات، يحتوي chunk.data.raw على البيانات المضغوطة/المشفرة و chunk.data.propCount = 0 و chunk.data.props = NULL ؛ الأمر متروك لمكتبة المستخدم لملء الخصائص بعد فك الضغط/فك التشفير.
  • يحتوي rresResourceMulti على عدة rresResourceChunks لملف إدخال تمت معالجته 
 // rres resource chunk
typedef struct rresResourceChunk {
    rresResourceChunkInfo info ;     // Resource chunk info
    rresResourceChunkData data ;     // Resource chunk packed data, contains propCount, props[] and raw data
} rresResourceChunk ;

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

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

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

يمكن تحميل rresResourceChunk واحد من ملف .rres باستخدام الوظيفة المتوفرة: rresLoadResourceChunk() وإلغاء تحميله باستخدام rresUnloadResourceChunk() .

يمكن تحميل rresResourceMulti كاملاً من ملف .rres باستخدام الوظيفة المتوفرة: rresLoadResourceMulti() وإلغاء تحميله باستخدام rresUnloadResourceMulti() .

مكتبة تعيين المحرك: rres-raylib.h

تتضمن مكتبة التعيين rres.h وتوفر وظيفة لتعيين بيانات قطع الموارد المحملة من ملف rres إلى بنيات raylib . واجهة برمجة التطبيقات المتوفرة بسيطة وبديهية، وتتبع اصطلاحات raylib : 

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

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

لاحظ أنه يتم تنفيذ فك ضغط/فك تشفير البيانات في هذه المكتبة المخصصة، ويتم توفير UnpackResourceChunk() للمستخدمين. يحتوي rresResourceChunk على قيم معرف الضاغط/التشفير لتوفير الراحة. يعتمد دعم الضواغط والشفرات على تنفيذ المستخدم ويجب أن يكون متوافقًا مع أداة التغليف ( rrespacker ).

تنسيق الملف rres لا يعتمد على المحرك، ويمكن إنشاء مكتبات وأدوات لأي محرك/إطار عمل بأي لغة برمجة.

أداة التغليف: rrespacker

rrespacker هي أداة تعبئة rres المسؤولة عن معالجة جميع ملفات الإدخال وإنشاء ملف rres ، باتباع المواصفات. في حالة دعم بعض خوارزميات الضغط/التشفير، يجب تنفيذها بواسطة هذه الأداة ويجب دعم نفس الخوارزميات بواسطة مكتبة التعيين، في حالتنا rres-raylib.h .

الشكل 03. أداة rrespacker، واجهة المستخدم الرسومية، كما أنها تدعم CLI لمعالجة الدفعات.

يمكن استخدام rrespacker عبر الإنترنت (أو تنزيله) من itch.io.

الإصدارات

  • rres v1.0 (12 مايو 2022) - الإصدار الأول من المواصفات.

رخصة

مواصفات تنسيق الملف rres ومكتبة rres.h ومكتبة rres-raylib.h مرخصة بموجب ترخيص MIT. تحقق من الترخيص لمزيد من التفاصيل.

حقوق الطبع والنشر (ج) 2014-2024 رامون سانتاماريا (@raysan5)

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل