framebuf — ניהול חוצץ פריימים (frame buffer)

המודול framebuf מספק חוצץ פיקסלים קטן וללא הקצאות עם פעולות ציור בסיסיות. הוא מיועד להפעלת מסכים חיצוניים (OLED, LCD, e-paper וכדומה).

הערה

לעבודת עיבוד תמונה על פריימים שנלכדו, השתמשו במחלקה העשירה הרבה יותר 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) עם רדיוס-x של xr ורדיוס-y של 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, ההשוואה נעשית מול פלט ה-palette, ולא מול ערך ה-fbuf הגולמי.

fbuf יכול להיות מופע FrameBuffer או tuple/list התואם לחתימת הבנאי:

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

כאשר המקור הוא tuple/list, 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 במקום זאת.