نظرة عامة
يمكن استخدام الدالة rsForEvery() لاستدعاء النواة الجذرية لنص برمجي.
وتستخدم الدوال الأخرى للحصول على خصائص استدعاء النواة التنفيذية، مثل الأبعاد والمؤشرات الحالية. تأخذ هذه الدوال rs_kernel_context كوسيطة.
ملخّص
| الأنواع | |
|---|---|
| rs_for_each_strategy_t | طلب معالجة الخلية المقترح |
| rs_kernel | التعامل مع دالة نواة |
| rs_kernel_context | التعامل مع سياق استدعاء النواة |
| rs_script_call_t | معلومات التكرار للخلية |
| الدوال | |
|---|---|
| rsForHow | لتشغيل النواة (kernel) |
| rsForEveryinternal | (واجهة برمجة تطبيقات داخلية) إطلاق نواة في النص البرمجي الحالي (مع رقم الخانة) |
| rsForSummaryWithOptions | لتشغيل نواة مع خيارات |
| rsGetArray0 | الفهرس في سمة Array0 لسياق النواة المحدّدة |
| rsGetArray1 | الفهرس في سمة المصفوفة 1 لسياق النواة المحدّد |
| rsGetArray2 | الفهرس في سمة المصفوفة 2 لسياق النواة المحدّد |
| rsGetArray3 | الفهرس في سمة المصفوفة 3 لسياق النواة المحدّد |
| rsGetDimArray0 | حجم بُعد Array0 لسياق النواة المحدّد |
| rsGetDimArray1 | حجم سمة المصفوفة 1 لسياق النواة المحدّد |
| rsGetDimArray2 | حجم بُعد المصفوفة 2 لسياق النواة المحدّد |
| rsGetDimArray3 | حجم بُعد المصفوفة 3 لسياق النواة المحدّد |
| rsGetDimHasFaces | وجود أكثر من وجه واحد لسياق النواة المحدد |
| rsGetDimLod | عدد مستويات التفاصيل لسياق النواة المحدّد |
| rsGetDimX | حجم البُعد "س" لسياق النواة المحدّد |
| rsGetDimY | حجم البُعد "ص" لسياق النواة المحدّد |
| rsGetDimZ | حجم البُعد Z لسياق النواة المحدّد |
| rsGetFace | إحداثيات الوجه لسياق النواة المحدد |
| rsGetLod | الفهرس في بُعد "مستويات التفاصيل" لسياق النواة المحدّد |
الأنواع
rs_for_each_strategy_t : ترتيب معالجة الخلايا المقترح
تعداد يضم القيم التالية:
| RS_FOR_EACH_STRATEGY_SERIAL = 0 | تفضيل مناطق الذاكرة المتجاورة. |
|---|---|
| RS_FOR_EACH_STRATEGY_DONT_CARE = 1 | ما مِن إعدادات مفضّلة. |
| RS_FOR_EACH_STRATEGY_DST_LINEAR = 2 | تفضيل DST. |
| RS_FOR_EACH_STRATEGY_TILE_SMALL = 3 | أفضّل معالجة المناطق المستطيلة الصغيرة. |
| RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4 | أفضّل معالجة المناطق المستطيلة المتوسطة. |
| RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 | أفضّل معالجة المناطق المستطيلة الكبيرة. |
يُستخدم هذا النوع لاقتراح كيفية تكرار النواة التي تم استدعاؤها على خلايا التخصيصات. هذا تلميح فقط. قد لا تتبع عمليات التنفيذ الاقتراح.
يمكن أن تساعد هذه المواصفات في سلوك التخزين المؤقت للنواة قيد التشغيل، على سبيل المثال، المنطقة المحلية لذاكرة التخزين المؤقت عندما يتم توزيع المعالجة على عدة أنوية.
rs_kernel : معالجة دالة النواة
تحديد نوع: إلغاء* تمت إضافته في المستوى 24 من واجهة برمجة التطبيقات
يشير ذلك المصطلح إلى نوع مبهم لدالة يتم تحديدها باستخدام سمة النواة kernel. يمكن استخدام قيمة من هذا النوع في استدعاء rsForEvery لتشغيل نواة.
rs_kernel_context : التعامل مع سياق استدعاء النواة
تعريف نوع: Cont struct rs_kernel_context_t * تمت إضافته في مستوى واجهة برمجة التطبيقات 23
يحتوي سياق النواة على خصائص مشتركة للتوزيعات التي يتم تكرارها، مثل الأبعاد. يحتوي أيضًا على فهارس نادرًا ما تُستخدم للخلية التي تتم معالجتها حاليًا، مثل فهرس Array0 أو المستوى الحالي من التفاصيل.
يمكنك الوصول إلى سياق النواة عن طريق إضافة معلَمة خاصة اسمها "context" من النوع rs_kernel_context إلى دالة النواة kernel. للاطّلاع على أمثلة، يمكنك الانتقال إلى rsGetDimX() وrsGetArray0() .
rs_script_call_t : معلومات التكرار الخلوي
بنية تتضمّن الحقول التالية:
| استراتيجية rs_for_each_strategy_t | يتم تجاهله حاليًا. في المستقبل، سيتم اقتراح استراتيجية تكرار الخلية. |
|---|---|
| uint32_t xStart | بدء الفهرس في البُعد "س". |
| uint32_t xEnd | فهرس النهاية (حصري) في البُعد "س". |
| uint32_t yStart | بدء الفهرس في البُعد Y. |
| uint32_t yEnd | فهرس النهاية (حصري) في البُعد Y. |
| uint32_t zStart | بدء الفهرس في البُعد Z. |
| uint32_t zEnd | فهرس النهاية (حصري) في البُعد Z. |
| uint32_t assetStart | بدء الفهرس في بُعد Array0. |
| uint32_t assetEnd | فهرس النهاية (حصري) في سمة Array0. |
| uint32_t asset1Start | بدء الفهرس في بُعد Array1. |
| uint32_t asset1End | فهرس النهاية (حصري) في سمة Array1. |
| uint32_t asset2Start | بدء الفهرس في بُعد Array2. |
| uint32_tarre2End | فهرس النهاية (حصري) في سمة المصفوفة 2. |
| uint32_t asset3Start | بدء الفهرس في بُعد Array3. |
| uint32_tصفيف3End | فهرس النهاية (حصري) في سمة Array3. |
يُستخدم هذا الهيكل لتقديم معلومات التكرار إلى استدعاء rsForEvery. وهي تُستخدم حاليًا لتقييد المعالجة على مجموعة فرعية من الخلايا. في الإصدارات المستقبلية، سيتم استخدامه أيضًا لتقديم تلميح حول أفضل طريقة للتكرار عبر الخلايا.
تكون حقول "البداية" شاملة وحقول "النهاية" حصرية. على سبيل المثال، للتكرار عبر الخلايا 4 و5 و6 و7 في البعد X، قم بتعيين xStart على 4 وxEnd على 8.
الدوال
rsForEvery : لتشغيل نواة
| void rsForEvery(rs_kernel kernel, ... ...); | تمّت الإضافة في المستوى 24 من واجهة برمجة التطبيقات |
| void rsForEvery(rs_script script, rs_allocation ينتج, rs_allocation الناتج); | مستوى واجهة برمجة التطبيقات 14 - 23 |
| void rsForEvery(rs_script script, rs_allocation ينتج, rs_allocation الناتج, Cont void* usrData); | تمّت الإزالة من المستوى 14 لواجهة برمجة التطبيقات والمستويات الأعلى. |
| void rsForEvery(rs_script script, rs_allocation ستتمكن من الإدخال rs_allocation, Cont void* usrData, Cont rs_script_call_t* sc); | تمّت الإزالة من المستوى 14 لواجهة برمجة التطبيقات والمستويات الأعلى. |
| void rsForEvery(rs_script script, rs_allocation ستتمكن من الإدخال rs_allocation, Cont void* usrData, size_t usrDataLen); | المستوى 14 إلى 20 من واجهة برمجة التطبيقات |
| void rsForEvery(rs_script script, rs_allocation ستتمكن من الإدخال rs_allocation, Cont void* usrData, size_t usrDataLen, Cont rs_script_call_t* sc); | المستوى 14 إلى 20 من واجهة برمجة التطبيقات |
المعلّمات
| نص برمجي | نص برمجي للمكالمة. |
|---|---|
| مصدر إدخال | التخصيص لمصدر البيانات. |
| output | التخصيص الذي ستتم كتابة التاريخ فيه. |
| بيانات الولايات المتحدة | البيانات التي يحددها المستخدم لتمريرها إلى النص البرمجي. قد تكون فارغة. |
| sc | معلومات التحكّم الإضافية المستخدَمة لاختيار منطقة فرعية للتخصيص المراد معالجتها أو لاقتراح استراتيجية المشي. قد تكون فارغة. |
| usrDataLen | حجم بنية بيانات المستخدم. سيتم استخدام هذا لإجراء نسخة سطحية من البيانات إذا لزم الأمر. |
| النواة (kernel) | محدِّد الدالة لدالة يتم تحديدها باستخدام سمة النواة kernel. |
| ... | عمليات تخصيص المدخلات والمخرجات |
لتشغيل النواة kernel على صفر أو أكثر من عمليات تخصيص الإدخال. ويتم تمريرها بعد الوسيطة rs_kernel. إذا كانت النواة المحددة تُرجع قيمة، فيجب تحديد تخصيص الناتج كوسيطة أخيرة. يجب أن يكون لجميع عمليات تخصيص الإدخالات وتخصيص المخرجات إن وُجدت الأبعاد نفسها.
هذه دالة متزامنة. لا يتم إرجاع الاستدعاء لهذه الدالة إلا بعد اكتمال العمل لجميع خلايا تخصيصات الإدخال. إذا عرضت دالة النواة أي قيمة، ينتظر الاستدعاء حتى تتم كتابة جميع النتائج في تخصيص الإخراج.
حتى المستوى 23 من واجهة برمجة التطبيقات، يتم تحديد النواة بشكل ضمني على أنها نواة تسمى "الجذر" في النص البرمجي المحدد، ولا يمكن استخدام سوى تخصيص إدخال واحد. بدءًا من المستوى 24 لواجهة برمجة التطبيقات، يمكن استخدام دالة نواة عشوائية على النحو المحدد في وسيطة النواة kernel. تمت إزالة وسيطة النص البرمجي. يجب تحديد النواة kernel في النص البرمجي الحالي. بالإضافة إلى ذلك، يمكن استخدام أكثر من إدخال واحد.
مثال:
float __attribute__((kernel)) square(float a) {
return a * a;
}
void compute(rs_allocation ain, rs_allocation aout) {
rsForEach(square, ain, aout);
}
rsForEveryInternal : (واجهة برمجة تطبيقات داخلية) إطلاق نواة kernel في النص البرمجي الحالي (باستخدام رقم الخانة)
| void rsFor EveryInternal(int افتَح, rs_script_call_t* options, int has لإجراء, int numInputs, rs_allocation* allocs); | تمّت الإضافة في المستوى 24 من واجهة برمجة التطبيقات |
المعلّمات
| خانة | |
|---|---|
| الخيارات | |
| بمخرجات | تشير إلى ما إذا كانت النواة تخرج مخرجًا أم لا |
| عدد الإدخالات | عدد عمليات تخصيص الإدخالات |
| تخصيص | عمليات تخصيص المدخلات والمخرجات |
واجهة برمجة تطبيقات داخلية لتشغيل نواة.
rsForEveryWithOptions : لتشغيل نواة تحتوي على خيارات
| void rsForSummaryWithOptions(rs_kernel kernel, rs_script_call_t* options, ... ...); | تمّت الإضافة في المستوى 24 من واجهة برمجة التطبيقات |
المعلّمات
| النواة (kernel) | محدِّد الدالة لدالة يتم تحديدها باستخدام سمة النواة kernel. |
|---|---|
| الخيارات | خيارات الإطلاق |
| ... | عمليات تخصيص المدخلات والمخرجات |
تشغِّل النواة kernel بطريقة تشبه rsForEvery. ومع ذلك، بدلاً من معالجة جميع الخلايا في الإدخال، تعالج هذه الدالة الخلايا الموجودة في المساحة الفرعية لمساحة الفهرس المحددة في الخيارات فقط. مع تحديد مساحة الفهرس بشكل صريح بالخيارات، لا حاجة إلى تخصيص المدخلات أو المخرجات لتشغيل النواة باستخدام واجهة برمجة التطبيقات هذه. إذا تم تمرير عمليات التوزيع، يجب أن تتطابق مع عدد الوسيطات والقيمة المعروضة التي تتوقعها دالة النواة kernel. يكون تخصيص الناتج موجودًا فقط إذا كانت النواة تحتوي على قيمة معروضة غير باطلة.
مثال:
rs_script_call_t opts = {0};
opts.xStart = 0;
opts.xEnd = dimX;
opts.yStart = 0;
opts.yEnd = dimY / 2;
rsForEachWithOptions(foo, &opts, out, out);
rsGetArray0 : الفهرس في سمة المصفوفة 0 لسياق النواة المحدّد
| uint32_t rsGetArray0(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
يتم عرض الفهرس في بُعد Array0 للخلية التي تتم معالجتها، على النحو المحدد في سياق النواة المقدم.
يحتوي سياق النواة على خصائص مشتركة للتوزيعات التي يتم تكرارها على الفهارس ونادرًا ما يتم استخدامها، مثل فهرس Array0.
يمكنك الوصول إلى سياق النواة عن طريق إضافة معلمة خاصة تسمى "context" من النوع rs_kernel_context إلى دالة النواة kernel. مثال:
short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {
// The current index in the common x, y, z dimensions are accessed by
// adding these variables as arguments. For the more rarely used indices
// to the other dimensions, extract them from the kernel context:
uint32_t index_a0 = rsGetArray0(context);
//...
}
تعرض هذه الدالة 0 في حال عدم وجود بُعد Array0.
rsGetArray1 : الفهرس في سمة المصفوفة 1 لسياق النواة المحدّد
| uint32_t rsGetArray1(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
يتم عرض الفهرس في بُعد المصفوفة 1 للخلية التي تتم معالجتها، كما هو محدد في سياق النواة المقدم. راجِع rsGetArray0() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر بُعد Array1.
rsGetArray2 : الفهرس في سمة المصفوفة 2 لسياق النواة المحدّد
| uint32_t rsGetArray2(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
يتم عرض الفهرس في بُعد "المصفوفة 2" للخلية التي تتم معالجتها، كما هو محدد في سياق النواة المقدم. راجِع rsGetArray0() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر بُعد Array2.
rsGetArray3 : الفهرس في سمة المصفوفة 3 لسياق النواة المحدّد
| uint32_t rsGetArray3(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
يتم عرض الفهرس في بُعد المصفوفة 3 للخلية التي تتم معالجتها، كما هو محدد في سياق النواة المقدم. راجِع rsGetArray0() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر بُعد Array3.
rsGetDimArray0 : حجم سمة المصفوفة 0 لسياق النواة المحدّد
| uint32_t rsGetDimArray0(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
تعرض حجم بُعد Array0 لسياق النواة المحدّد. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض 0 في حال عدم وجود بُعد Array0.
rsGetDimArray1 : حجم سمة المصفوفة 1 لسياق النواة المحدّد
| uint32_t rsGetDimArray1(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
تعرض حجم بُعد Array1 لسياق النواة المحدّد. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر بُعد Array1.
rsGetDimArray2 : حجم سمة المصفوفة2 لسياق النواة المحدّد
| uint32_t rsGetDimArray2(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
تعرض حجم بُعد Array2 لسياق النواة المحدّد. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر بُعد Array2.
rsGetDimArray3 : حجم سمة المصفوفة 3 لسياق النواة المحدّد
| uint32_t rsGetDimArray3(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
تعرض حجم بُعد Array3 لسياق النواة المحدّد. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر بُعد Array3.
rsGetDimHasFaces : وجود أكثر من وجه واحد لسياق النواة المحدّد
| bool rsGetDimHasFaces(rs_kernel_context context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
الركلات المردودة
| تعرض القيمة true في حال وجود أكثر من وجه واحد، وإلا سيتم عرضها false في حال وجود أكثر من وجه. |
إذا كانت النواة تتكرر على خريطة مكعّبة، فإن هذه الدالة تُرجع القيمة "صحيح" إذا كان هناك أكثر من وجه واحد. وفي جميع الحالات الأخرى، تعرض القيمة false. راجِع rsGetDimX() للحصول على شرح للسياق.
الدالة rsAllocationGetDimFaces() متشابهة، ولكنها تعرض 0 أو 1 بدلاً من القيمة المنطقية.
rsGetDimLod : عدد مستويات التفاصيل لسياق النواة المحدّد
| uint32_t rsGetDimLod(rs_kernel_context event); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
لعرض عدد مستويات التفاصيل لسياق النواة المحددة. هذا مفيد لخرائط mipmaps. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض 0 في حال عدم استخدام مستوى التفاصيل.
الدالة rsAllocationGetDimLOD() متشابهة، ولكنها تعرض 0 أو 1 بدلاً من العدد الفعلي للمستويات.
rsGetDimX : حجم البُعد "س" لسياق النواة المحدّد
| uint32_t rsGetDimX(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
لعرض حجم البُعد "س" لسياق النواة المحدّد.
يحتوي سياق النواة على خصائص مشتركة للتوزيعات التي يتم تكرارها على الفهارس ونادرًا ما يتم استخدامها، مثل فهرس Array0.
يمكنك الوصول إليه عن طريق إضافة معلمة خاصة تسمى "context" من النوع rs_kernel_context إلى دالة النواة kernel. مثال:
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
uint32_t size = rsGetDimX(context); //...
وللحصول على بُعد عملية تخصيص معيّنة، استخدِم rsAllocationGetDimX().
rsGetDimY : حجم البُعد Y لسياق النواة المحدّد
| uint32_t rsGetDimY(rs_kernel_context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
لعرض حجم البُعد "س" لسياق النواة المحدّد. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض 0 إذا لم يكن البُعد "ص" موجودًا.
وللحصول على بُعد عملية تخصيص معيّنة، استخدِم rsAllocationGetDimY().
rsGetDimZ : حجم البُعد Z لسياق النواة المحدّد
| uint32_t rsGetDimZ(rs_kernel_context event); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
لعرض حجم البُعد Z لسياق النواة المحدد. راجِع rsGetDimX() للحصول على شرح للسياق.
تعرض القيمة 0 إذا لم يكن البُعد Z موجودًا.
وللحصول على سمة تخصيص محدَّد، استخدِم rsAllocationGetDimZ().
rsGetFace : تنسيق الوجه لسياق النواة المحدّد
| rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
لعرض الوجه الذي تم العثور على الخلية التي تجري معالجتها عليه، كما هو محدد في سياق النواة المتوفر. راجِع rsGetArray0() للحصول على شرح للسياق.
تعرض RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X إذا لم يكن بُعد الوجه موجودًا.
rsGetLod : الفهرس في بُعد "مستويات التفاصيل" لسياق النواة المحدّد
| uint32_t rsGetLod(rs_kernel_context event); | تمّت الإضافة في المستوى 23 من واجهة برمجة التطبيقات |
يتم عرض الفهرس في بُعد "مستويات التفاصيل" للخلية التي تتم معالجتها، كما هو محدد في سياق النواة المقدمة. راجِع rsGetArray0() للحصول على شرح للسياق.
تعرض 0 في حال عدم توفر البُعد "مستويات التفاصيل".