debug draw

Debug Draw

الوضع الفوري ، العارض لا يندري ، رسم تصحيح أخطاء خفيفة الوزن API لـ C ++.

رخصة

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

يتم توفير رمز المصدر "كما هو" ، دون أي ضمان من أي نوع ، صريح أو ضمني. لا يلزم الإسناد ، ولكن يتم تقدير ذكر حول المؤلف (المؤلفون).

باستخدام Debug Draw

Debug Draw هي مكتبة ملفات مصدر واحد ، وبالتالي فإن إعلانات "الرأس" إلى الأمام والتنفيذ موجودة في نفس الملف ( debug_draw.hpp ). هذا يجب أن يسهل النشر والتكامل مع مشاريعك الخاصة. كل ما عليك فعله هو #include ملف المكتبة في أحد ملفات المصدر الخاصة بك وتحديد DEBUG_DRAW_IMPLEMENTATION في هذا الملف لإنشاء التنفيذ. لا يزال بإمكانك أيضًا تضمين المكتبة في أماكن أخرى. عندما لا يتم تعريف DEBUG_DRAW_IMPLEMENTATION ، فإنه يعمل كملف رأس C ++ عادي. مثال:

في my_program.cpp :

# define DEBUG_DRAW_IMPLEMENTATION
# include " debug_draw.hpp "

الآن في my_program.hpp أو أي رأس أو ملف مصدر آخر ، يمكنك تضمينه كرأس C ++ عادي:

# include " debug_draw.hpp "

هذا كل شيء ، يجب أن تكون قادرًا الآن على بناء رسم تصحيح في طلبك.

التواصل مع العارض الخاص بك

لا يقدم Debug Draw افتراضات حول واجهة برمجة تطبيقات العارض الأساسي ، بحيث يمكن دمجها بسهولة شديدة مع Direct3D أو OpenGL أو أي محرك عرض آخر من اختيارك. كل ما هو مطلوب هو أن تقدم تطبيقًا لفئة dd::RenderInterface Abstract ، والتي توفر رسم تصحيح مع الأساليب الأساسية لرسم النقاط والخطوط الحرفية. فيما يلي ما يشبه dd::RenderInterface :

 class RenderInterface
{
public:
    virtual void beginDraw ();
    virtual void endDraw ();

    virtual GlyphTextureHandle createGlyphTexture ( int width, int height, const void * pixels);
    virtual void destroyGlyphTexture (GlyphTextureHandle glyphTex);

    virtual void drawPointList ( const DrawVertex * points, int count, bool depthEnabled);
    virtual void drawLineList ( const DrawVertex * lines, int count, bool depthEnabled);
    virtual void drawGlyphList ( const DrawVertex * glyphs, int count, GlyphTextureHandle glyphTex);

    virtual ~RenderInterface () = 0 ;
};

لا يجب تنفيذ جميع الطرق ، فأنت تقرر الميزات التي يجب دعمها! انظر إلى الكود المصدري لإعلان RenderInterface . يتم التعليق على كل طريقة بشكل جيد ويصف السلوك المتوقع الذي يجب عليك تنفيذه. للحصول على تطبيقات مرجعية لـ RenderInterface باستخدام واجهات برمجة التطبيقات القياسية مثل OpenGL ، راجع samples/ الدليل في هذا المشروع.

بمجرد تنفيذ RenderInterface للعارض الخاص بك ، كل ما عليك القيام به قبل البدء في استخدام Debug Draw هو استدعاء dd::initialize() تمريره إلى مؤشر إلى RenderInterface المخصصة الخاصة بك:

MyRenderInterface renderIface;
dd::initialize (&renderIface);

لاحظ أن الدُفعات التي ترسم تصحيح الأخطاء جميعها لتقليل عدد المكالمات RenderInterface ، لذلك لن يحدث الرسم فعليًا إلا في الوقت الذي تتصل فيه dd::flush() ، والذي يتم عادة في نهاية الإطار ، قبل تقليب المخازن المؤقتة للشاشة:

 // You only have to pass the current time if you have timed debug
// draws in the queues. Otherwise just omit the argument or pass 0.
dd::flush (getTimeMilliseconds());

لذا يجب أن يبدو الإعداد العام مثل ما يلي:

 class MyRenderInterface : public dd ::RenderInterface
{
    // Cherrypick the methods you want to implement or implement them all
    ...
};

int main ()
{
    MyRenderInterface renderIface;
    dd::initialize (&renderIface);

    while (!quitting)
    {
        // Any other drawing that you already do
        ...

        // Call any dd:: functions to add debug primitives to the draw queues
        ...

        dd::flush ( getTimeMilliseconds ());

        // Swap buffers to present the scene
        ...
    }

    dd::shutdown ();
}

مفاتيح التكوين

يوفر Debug Draw العديد من مفاتيح التحويلات البرمجية لتكوين المكتبة وتخصيصها. تحقق من الوثائق في debug_draw.hpp للحصول على قائمة بجميع المفاتيح بالإضافة إلى وصف مفصل لكل منها.

متطلبات اللغة/المترجم

المكتبة لديها عدد قليل جدا من متطلبات اللغة. أحد أهدافها الرئيسية هو أن تكون غير مؤلمة للاندماج والمحمول. المطلب الوحيد هو برنامج التحويل البرمجي C ++ حديث إلى حد ما مع الحد الأدنى من دعم المكتبة القياسية. يتم افتراض بعض ميزات C ++ 11 ، مثل nullptr و <cstdint> . تضمنت العينات الاستفادة الأثقل للمكتبة القياسية C ++ لإظهار استخدام DEBUG Draw الاستخدام مع المواضيع.

لا يتم استخدام استثناءات RTTI و C ++ ، لذلك لا ينبغي أن تواجه أي مشاكل في دمج المكتبة مع المشاريع التي تعطل هذه الميزات.

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

سلامة الموضوع والسياقات الصريحة

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

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

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

وضع السياق الصريح هو واجهة برمجة تطبيقات أكثر نظافة وأكثر وظيفية ويجب أن تكون الخيار المفضل للمستخدمين الجدد. لا يزال الوضع الإجرائي هو الافتراضي للتوافق مع إصدارات المكتبة الأقدم ، ولكن يوصى باستخدام وضع السياق الصريح عن طريق إضافة #define DEBUG_DRAW_EXPLICIT_CONTEXT مع DEBUG_DRAW_IMPLEMENTATION . في المستقبل ، سيتم إهمال واجهة برمجة تطبيقات الدولة الإجرائية لصالح الواحد الصريح.

عينات

رسم صندوق مع مجموعة من محاور الإحداثيات في مركزه:

 const ddVec3 boxColor  = { 0 . 0f , 0 . 8f , 0 . 8f };
const ddVec3 boxCenter = { 0 . 0f , 0 . 0f , 3 . 0f };

dd::box (boxCenter, boxColor, 1 . 5f , 1 . 5f , 1 . 5f );
dd::cross (boxCenter, 1 . 0f );

لتصور تحويل المصفوفة ، يمكنك استخدام dd::axisTriad() لرسم التحويل على أنه ثلاثة أسهم:

 const ddMat4x4 transform = { // The identity matrix
    1 . 0f , 0 . 0f , 0 . 0f , 0 . 0f ,
    0 . 0f , 1 . 0f , 0 . 0f , 0 . 0f ,
    0 . 0f , 0 . 0f , 1 . 0f , 0 . 0f ,
    0 . 0f , 0 . 0f , 0 . 0f , 1 . 0f
};
dd::axisTriad (transform, 0 . 3f , 2 . 0f );

يمكن العثور على عينات أكثر تعقيدًا وأمثلة حول كيفية دمج Debug Draw مع العارض الخاص بك داخل samples/ الدليل. يتم توثيق كل وظيفة مقدمة في واجهة برمجة التطبيقات العامة بشكل جيد في ملف الرأس. ستجد تعليق رأس وصفي قبل النموذج الأولي لكل وظيفة عامة تم تصديرها بواسطة المكتبة.