Painter(3I)

✨ Painter(3I) ✨

okay so bestie, we're in the InterViews Reference Manual section 3I today and the vibe is graphics output — literally that's the whole NAME, "Painter - graphics output" 🎨💖

✨ SYNOPSIS ✨

#include <InterViews/painter.h>

💅 DESCRIPTION 💅

So Painter is a class, right? And what it does is give you "immediate-mode" graphics operations for drawing on a canvas. Periodt. 🖌️

And here's the thing — a painter's state is the graphics context for all those drawing ops. Like, it's holding:

• a brush
• foreground and background colors
• a fill pattern and mode
• a text font
• a text style
• an output origin and current position
• and a transformation matrix

That's the whole squad right there. No cap. 👑

🎀 STATE OPERATIONS 🎀

• Painter(Painter* = stdpaint) — Make a brand new painter and copy its whole state from the painter you hand it. Default is stdpaint, iykyk. 🫶
• void SetBrush(Brush*) / Brush* GetBrush() — Set or get the painter's brush. Default is the predefined brush single. Simple, iconic.
• void SetColors(Color* fg, Color* bg) / Color* GetFgColor() / Color* GetBgColor() — Set or get the painter's colors. Heads up bestie: if either argument to SetColors is nil, then that corresponding color just... doesn't change. No drama. Defaults are black for foreground and white for background. 🤍🖤
• void SetFont(Font*) / Font* GetFont() — Set or get the painter's text font. Default is the predefined font stdfont. ✨
• void SetStyle(int style) / int GetStyle() — Set or get the text style. A text style is a bit vector, and you assemble it from the predefined constants Plain, Boldface, Underlined, and Reversed. Default is Plain. Mix and match, she's flexible 💅
• void SetPattern(Pattern*) / Pattern* GetPattern() / void FillBg(boolean mode) / boolean BgFilled() — Set or get the fill pattern and mode. If the mode is true, fill operations set pixels corresponding to ones in the current fill pattern to the foreground color, and pixels corresponding to zeros to the background color. If it's false, then only the foreground pixels get set. Default pattern is solid; default mode is true. 💖
• void SetOrigin(int x0, int y0) / void GetOrigin(int& x0, int& y0) — Set or get the origin that all your coordinates get offset by. Default is (0, 0). The classic.
• void Translate(float dx, float dy) / void Rotate(float angle) / void Scale(float x, float y) / void SetTransformer(Transformer*) / Transformer* GetTransformer() — Coordinates you pass to drawing operations get transformed according to the current origin, translation (which is cumulative, mind you), rotation, and scale factor. Internally there's a transformation matrix stored that you can directly set and access with SetTransformer and GetTransformer. The default transformer is nil, which means no transformations happen at all — just vibes. 🦋
• void SetPlaneMask(int mask) — Sets which bit planes get affected by drawing operations. If the Kth bit of mask is set, then display operations will draw on plane K. Plane K said yes to being included. 👑
• void SetOverwrite(boolean) — Sets whether a painter is allowed to write in subcanvases. If true, drawing operations will be able to write over the canvases of component interactors. If false, drawing operations get clipped by any subcanvases. The default is false. 🚧
• void Clip(Canvas*, Coord x1, Coord y1, Coord x2, Coord y2) / void NoClip() — Clip restricts output operations to the specified region of the canvas. NoClip removes the restriction so operations affect the entire canvas. And listen: only one clipping region may be in effect at a time. One. Not two. Pick a lane. 🙈
• void MoveTo(Coord x, Coord y) — Sets the current output position. This position is used and updated by Text and CurveTo. She's a main character who grows. 🌱

🌈 DRAWING OPERATIONS 🌈

• void Curve(Canvas*, Coord x0, y0, x1, y1, x2, y2, x3, y3) / void CurveTo(Canvas*, Coord x1, y1, x2, y2, x3, y3) — Paints a Bezier curve on the canvas from the first point to the last point (but not going through the intermediate control points, so don't @ me). The curve will lie within the polygon formed by the four points. CurveTo uses the current position for the first point. 🌀
• void BSpline(Canvas*, Coord x[], y[], int n) / void ClosedBSpline(Canvas*, Coord x[], y[], int n) / void FillBSpline(Canvas*, Coord x[], y[], int n) — Draws the B-spline defined by the n control vertices. If it's closed or filled, the last point gets connected back to the first point. Full circle moment. 🔄
• void Circle(Canvas*, Coord x, y, int r) / void FillCircle(Canvas*, Coord x, y, int radius) — Draws a circle with center (x, y) and radius r. Yes, the parameter is called r in one and radius in the other, and yes, we're keeping it exactly like that. 💀
• void Ellipse(Canvas*, Coord x, y, int xr, int yr) / void FillEllipse(Canvas*, Coord x, y, int xr, int yr) — Draws an ellipse with center (x, y), horizontal radius xr, and vertical radius yr. An icon, but stretched. 🥚
• void Line(Canvas*, Coord x1, y1, x2, y2) / void MultiLine(Canvas*, Coord x[], y[], int n) / void Polygon(Canvas*, Coord x[], y[], int n) / void FillPolygon(Canvas*, Coord x[], y[], int n) — Draw a path using the current brush and colors. Line draws a vector between two points (inclusive); MultiLine draws a number of connected vectors; Polygon draws a closed set of vectors; FillPolygon fills the area inside a polygon using the current fill pattern and colors. 🖍️
• void Point(Canvas*, Coord x, y) / void MultiPoint(Canvas*, Coord x[], y[], int n) — Sets a point, or a whole set of points, to the current foreground color. Tiny but mighty. ⭐
• void Rect(Canvas*, Coord x1, y1, x2, y2) / void FillRect(Canvas*, Coord x1, y1, x2, y2) / void ClearRect(Canvas*, Coord x1, y1, x2, y2) — Draws a rectangle with opposite corners specified by (x1, y1) and (x2, y2). FillRect fills it using the current pattern and colors; ClearRect fills it with the background color. 🟦
• void Text(Canvas*, const char* str, Coord x, Coord y) / void Text(Canvas*, const char* str, int n, Coord x, Coord y) / void Text(Canvas*, const char* str) / void Text(Canvas*, const char* str, int n) — Draws a string, or a substring of text, using the current Font and text style.

The (x, y) coordinates specify the lower-left corner of the bounding box of the text. The width of that bounding box is the width of the string as reported by the Font::Width operation, and the height of the bounding box is the Font height. Most fonts will result in output that only affects pixels within the bounding box.

The current transformation matrix gets applied to both the positions and the shapes of the characters drawn.

⚠️ If the matrix specifies a transformation involving rotation or scaling, the resulting operation may proceed much more slowly than normal. She's doing her best but she's working hard for it. 😭

If background fill mode is on, the characters are drawn in the foreground color and the other pixels within the bounding box get set to the background color. If background fill mode is off, only the foreground pixels get set.

If you don't specify coordinates, then the current position (the one defined by MoveTo) is used — and it gets updated to reflect the lower-right corner of the bounding box. 💖

• void Stencil(Canvas*, Coord x, Coord y, Bitmap* image, Bitmap* mask = nil) — Paints foreground and background colors through a stencil formed by positioning the image and mask Bitmaps with their origins at the point (x, y). Foreground color gets painted where the image Bitmap has a true value, and background color where image is false. However, only pixels corresponding to a true value in the mask Bitmap are affected. A nil mask is equivalent to a mask of the same size and shape as image and containing all true values. The current transformation matrix gets applied to both the image and mask Bitmaps.

⚠️ Again: if the matrix specifies a transformation involving rotation or scaling, the resulting operation may proceed much more slowly than normal. 🐌

• void RasterRect(Canvas*, Coord x, Coord y, Raster*) — Renders the Raster with its lower-left corner at the position (x, y). The current transformation matrix gets applied to the Raster.

⚠️ And once more for the people in the back: if the matrix specifies a transformation involving rotation or scaling, the resulting operation may proceed much more slowly than normal. Bestie, just know it. 💀

• void Read(Canvas*, void*, Coord x1, y1, x2, y2) / void Write(Canvas*, const void*, Coord x1, y1, x2, y2) / void Copy(Canvas* src, Coord x1, y1, x2, y2, Canvas* dst, Coord x0, y0) — Read copies a region of a canvas into memory. Write copies data from memory to a region of a canvas. Copy reads a region of one canvas and writes the data into a region of another canvas (or within a canvas if src and dst are the same). The point (x0, y0) is the lower-left corner of the destination region.

🚨 Note that Read and Write are superseded by operations that use Rasters. Not me being outdated, it's just the lore. 🙈

🦋 SEE ALSO 🦋

Bitmap(3I), Brush(3I), Canvas(3I), Color(3I), Font(3I), Pattern(3I), Raster(3I), Transformer(3I)

Go read those too, they're all part of the friend group. 🫶

and that's the whole page, bestie!! this one's from InterViews, dated 15 June 1987 — yeah she's vintage, she's an icon, she's a legend and she is the moment. 💅✨👑