framebuf --- التعامل مع مخزن الإطارات

توفر الوحدة framebuf مخزن بكسلات صغيراً وخالياً من التخصيص مع عمليات رسم بدائية. وهي مخصصة لتشغيل الشاشات الخارجية (شاشات OLED و LCD والورق الإلكتروني، إلخ).

ملاحظة

للعمل على معالجة الصور على الإطارات الملتقطة، استخدم بدلاً من ذلك الفئة image.Image الأكثر ثراءً في OpenMV -- فهي تقدّم بدائيات رسم وتحويلات ألوان وميزات تحليل أكثر بكثير من framebuf.

class FrameBuffer

A FrameBuffer wraps a user-supplied buffer-protocol object (typically a bytearray) and exposes methods to draw pixels, lines, rectangles, ellipses, polygons, text and other FrameBuffers into it.

مثال:

import framebuf

# FrameBuffer needs 2 bytes for every RGB565 pixel.
fbuf = framebuf.FrameBuffer(bytearray(100 * 10 * 2), 100, 10, framebuf.RGB565)

fbuf.fill(0)
fbuf.text("MicroPython!", 0, 0, 0xffff)
fbuf.hline(0, 9, 96, 0xffff)

المُنشئات

class framebuf.FrameBuffer(buffer: Any, width: int, height: int, format: int, stride: int | None = None, /)

إنشاء كائن FrameBuffer.

• buffer -- أي كائن يدعم بروتوكول المخزن المؤقت؛ يجب أن يكون كبيراً بما يكفي لاستيعاب stride * height بكسلاً بالتنسيق format المختار.

• width -- عرض مخزن الإطارات بالبكسل.

• height -- ارتفاع مخزن الإطارات بالبكسل.

• format -- تنسيق البكسل؛ أحد الثوابت المدرجة تحت الثوابت أدناه. يحدد التنسيق كلاً من حجم كل بكسل في buffer وكيفية تفسير عدد صحيح للون c يُمرّر إلى أي طريقة رسم.

• stride -- عدد البكسلات لكل صف أفقي، بما في ذلك أي حشو. الافتراضي هو width. اضبط هذا لاستخدام منطقة فرعية من مخزن مؤقت أكبر.

تمرير buffer صغير جداً، أو أبعاد غير صالحة، سينتج عنه نتائج غير محددة -- لا يتحقق المُنشئ من كل تركيبة.

طرق الرسم

FrameBuffer.fill(c: int) → None

ملء مخزن الإطارات بالكامل باللون c.

FrameBuffer.fill_rect(x: int, y: int, w: int, h: int, c: int) → None

ملء مستطيل w x h عند (x, y) باللون c. مكافئ لـ rect() مع f=True.

FrameBuffer.pixel(x: int, y: int, c: int | None = None) → int | None

بدون وسيطة c، تُرجع قيمة لون البكسل عند (x, y). مع إعطاء c، تضبط ذلك البكسل على اللون c.

FrameBuffer.hline(x: int, y: int, w: int, c: int) → None

FrameBuffer.vline(x: int, y: int, h: int, c: int) → None

FrameBuffer.line(x1: int, y1: int, x2: int, y2: int, c: int) → None

رسم خط بسمك بكسل واحد باللون c. ترسم hline() و vline() خطاً أفقياً/عمودياً بالطول المعطى؛ وترسم line() خطاً بين نقطتين اعتباطيتين.

FrameBuffer.rect(x: int, y: int, w: int, h: int, c: int, f: bool = False) → None

رسم مستطيل عند (x, y) بحجم w x h باللون c. إذا كانت f تساوي True يُملأ المستطيل؛ وإلا يُرسم مخطط خارجي بسمك بكسل واحد فقط.

FrameBuffer.ellipse(x: int, y: int, xr: int, yr: int, c: int, f: bool = False, m: int = 0) → None

رسم شكل بيضاوي مركّز على (x, y) بنصف قطر أفقي xr ونصف قطر عمودي yr باللون c. نصفا القطر المتساويان ينتجان دائرة. f=True تملأ الشكل بدلاً من رسم مخططه فقط.

‎m هو قناع بتات يقيّد الرسم على أرباع محددة (مرقّمة عكس اتجاه عقارب الساعة بدءاً من أعلى اليمين):

البت	الربع	المنطقة
البت 0	Q1	أعلى اليمين
البت 1	Q2	أعلى اليسار
البت 2	Q3	أسفل اليسار
البت 3	Q4	أسفل اليمين

القيمة الافتراضية m=0 ترسم جميع الأرباع الأربعة.

FrameBuffer.poly(x: int, y: int, coords: Any, c: int, f: bool = False) → None

رسم مضلع مغلق اعتباطي (محدّب أو مقعّر) عند الإزاحة (x, y) باللون c. يجب أن تكون coords عبارة عن array من الأعداد الصحيحة الموقّعة ذات 16 بت موزّعة كـ array('h', [x0, y0, x1, y1, ..., xn, yn]). f=True تملأ المضلع بدلاً من رسم مخططه فقط.

FrameBuffer.text(s: str, x: int, y: int, c: int = 1) → None

رسم السلسلة النصية s بحيث تكون زاويتها العلوية اليسرى عند (x, y) باللون c. الخط المدمج ثابت عند 8x8 بكسل ولا يمكن تغييره. القيمة الافتراضية لـ c هي 1.

FrameBuffer.scroll(xstep: int, ystep: int) → None

إزاحة محتويات المخزن المؤقت بمقدار (xstep, ystep). البكسلات المُزاحة من خارج المخزن المؤقت لا تُمسح، لذا قد يبقى "طيف" من المحتويات السابقة عند الحافة الخلفية.

FrameBuffer.blit(fbuf: FrameBuffer | Tuple, x: int, y: int, key: int = -1, palette: FrameBuffer | None = None) → None

رسم مخزن إطارات آخر fbuf فوق هذا المخزن بحيث تكون زاويته العلوية اليسرى عند (x, y).

إذا أُعطيت key، يُعامل أي بكسل مصدر يطابق قيمة ذلك اللون على أنه شفاف ولا يُرسم. عندما يُوفّر palette، تُجرى المقارنة مقابل خرج اللوحة، وليس قيمة fbuf الأولية.

يمكن أن تكون fbuf نسخة FrameBuffer أو صفاً/قائمة تطابق توقيع المُنشئ:

(buffer, width, height, format)
(buffer, width, height, format, stride)

عندما يكون المصدر صفاً/قائمة، قد يكون buffer للقراءة فقط.

تتيح palette النقل البتّي (blitting) بين مخازن مؤقتة بتنسيقات مختلفة -- على سبيل المثال، عرض حرف أحادي اللون في مخزن مؤقت بتنسيق RGB565. وهي عبارة عن FrameBuffer يطابق تنسيقها الوجهة، بارتفاع 1 وعرض يساوي عدد ألوان المصدر (2**N لمصدر بـ N بت لكل بكسل). تُستبدل قيمة بكسل المصدر i باللون عند palette[i, 0] قبل الرسم.

الثوابت

قيم format التالية مقبولة من قبل المُنشئ. عمود "البايتات لكل بكسل" هو المضاعف اللازم عند تحديد حجم المخزن المؤقت الداعم.

الثابت	بايت/بكسل	تخطيط البكسل
MONO_VLSB	0.125	أحادي اللون (1 بت). يحمل كل بايت 8 بكسلات مكدّسة عمودياً مع البت 0 الأقرب إلى الأعلى. تتقدم صفوف الـ 8 بكسلات من اليسار إلى اليمين عبر المخزن المؤقت، ثم تلتف إلى صف الـ 8 بكسلات التالي.
MONO_HLSB	0.125	أحادي اللون (1 بت). يحمل كل بايت 8 بكسلات أفقية مع البت 7 في أقصى اليسار. تتقدم الصفوف بكسلاً واحداً في كل مرة عمودياً.
MONO_HMSB	0.125	أحادي اللون (1 بت). مثل MONO_HLSB لكن مع البت 0 في أقصى اليسار.
GS2_HMSB	0.25	تدرج رمادي بـ 2 بت (4 مستويات)، مُحزّم أفقياً بالبت الأكثر أهمية أولاً.
GS4_HMSB	0.5	تدرج رمادي بـ 4 بت (16 مستوى)، مُحزّم أفقياً بالنبلة الأكثر أهمية أولاً.
GS8	1	تدرج رمادي بـ 8 بت (256 مستوى).
RGB565	2	RGB بـ 16 بت مع 5 بتات حمراء و 6 خضراء و 5 زرقاء.

‎framebuf.MVLSB هو اسم مستعار مهجور لـ framebuf.MONO_VLSB؛ يُفضّل الأخير في الكود الجديد.

المُنشئ القديم

framebuf.FrameBuffer1(buffer: Any, width: int, height: int, stride: int | None = None, /) → FrameBuffer

اختصار مهجور لـ FrameBuffer(buffer, width, height, framebuf.MONO_VLSB, stride). مُحتفظ به للتوافق مع الإصدارات السابقة؛ استخدم المُنشئ الكامل FrameBuffer بدلاً من ذلك.