| //+-------------------------------------------------------------------+
|
| //| Clip.mqh |
|
| //| Copyright 2026, Sandro Begashvili |
|
| //| https://www.mql5.com/en/users/sandrobegashvil |
|
| //| Telegram: https://t.me/MrMQL5Developer |
|
| //| Cairo5 - 2D vector engine - PART 9 code |
|
| //| |
|
| //| THE CLIP - where drawing is allowed to land. |
|
| //| |
|
| //| Everything before this part could draw any shape anywhere. What |
|
| //| it could not do is STOP. A list of rows draws past the bottom of |
|
| //| its panel, a price line runs out over the axis labels, a label |
|
| //| too long for its button spills across the one beside it. No |
|
| //| shape helper fixes that, because the shape is not the problem - |
|
| //| the drawing has to be cut off at a boundary that belongs to |
|
| //| something else entirely. |
|
| //| |
|
| //| THE IDEA, AND WHY IT COSTS ALMOST NOTHING HERE |
|
| //| |
|
| //| Part 4 made the rasterizer compute COVERAGE: for every pixel, a |
|
| //| number from 0 to 1 saying how much of it the shape reached. A |
|
| //| clip is the same quantity asked of a different shape - how much |
|
| //| of this pixel is drawing allowed to reach? |
|
| //| |
|
| //| Two coverages, one multiplication: |
|
| //| |
|
| //| final = shape_coverage * clip_coverage |
|
| //| |
|
| //| That single line is the whole feature. It also means the clip is |
|
| //| ANTI-ALIASED for free - a circular clip has the same smooth edge |
|
| //| a circular fill has, because it is the same number out of the |
|
| //| same rasterizer - and that SOFT clipping, where the boundary is |
|
| //| partly transparent, is not a separate feature at all. |
|
| //| |
|
| //| TWO KINDS, AND THE REASON FOR THE CHEAP ONE |
|
| //| |
|
| //| A RECTANGLE needs no memory. The overlap of a pixel with a |
|
| //| rectangle is four comparisons and a multiply, computed on |
|
| //| demand. Nearly every clip in an interface is a rectangle - a |
|
| //| panel, a cell, a viewport, a scrolling list - so the common case |
|
| //| allocates nothing at all. |
|
| //| |
|
| //| A PATH needs a MASK: one byte per pixel inside its bounds, |
|
| //| holding the coverage the rasterizer computed when the clip was |
|
| //| set. That is the price of clipping to a rounded card or a round |
|
| //| avatar, and it is paid once per clip rather than once per shape |
|
| //| drawn inside it. |
|
| //| |
|
| //| The mask is built by CCairoRasterizer::ClipToPath(), over in |
|
| //| Raster.mqh, because the rasterizer is the thing that knows how |
|
| //| to turn a path into coverage. This file knows nothing about |
|
| //| scanlines. It stores the answer and hands it back one pixel at a |
|
| //| time. |
|
| //+-------------------------------------------------------------------+
|
| #ifndef CAIRO5_CLIP_MQH
|
| #define CAIRO5_CLIP_MQH
|
|
|
| #include "Path.mqh"
|
|
|
| //+-------------------------------------------------------------------+
|
| //| CCairoClip |
|
| //| |
|
| //| HELD BY THE CALLER, PASSED TO THE RASTERIZER. One clip object can |
|
| //| be narrowed repeatedly - a panel, then a row inside it, then a |
|
| //| cell inside that - and each step intersects with what was already |
|
| //| there, so a clip can only ever get smaller. |
|
| //| |
|
| //| The mask arrays are never shrunk, for the reason no buffer in |
|
| //| this library is ever shrunk: the next frame is going to want |
|
| //| them. |
|
| //+-------------------------------------------------------------------+
|
| class CCairoClip
|
| {
|
| private:
|
| SCairoRect m_rect; // the clip bounds, in device pixels
|
| bool m_empty; // nothing can be drawn at all
|
|
|
| //--- the optional soft mask, 0..255 per pixel, covering exactly the
|
| //--- integer pixel box [m_mx, m_mx + m_mw) x [m_my, m_my + m_mh)
|
| uchar m_mask[];
|
| int m_mx, m_my, m_mw, m_mh;
|
| bool m_has_mask;
|
|
|
| //--- the PREVIOUS mask, kept alive only while a new one is being
|
| //--- built out of it. See BeginIntersect() for why it has to exist.
|
| uchar m_prev[];
|
| int m_px, m_py, m_pw, m_ph;
|
| bool m_prev_mask;
|
| bool m_building; // is a Begin/End pair open?
|
|
|
| bool m_alloc_failed; // sticky until the next Reset()
|
|
|
| public:
|
| CCairoClip();
|
|
|
| //--- LIFECYCLE
|
| void Reset(const int width, const int height);
|
| void SetEmpty();
|
| void Release();
|
|
|
| //--- NARROWING
|
| bool IntersectRect(const SCairoRect &r);
|
|
|
| //--- Take on another clip's state, mask included. This is what a
|
| //--- save/restore of the clip is built from: a clip can only ever
|
| //--- be narrowed, so the only way back out is to have kept a copy.
|
| //--- The parameter is a POINTER because a stack of saved clips is
|
| //--- naturally an array of pointers, and MQL5 will not pass a
|
| //--- pointer to a reference parameter.
|
| bool CopyFrom(CCairoClip *other);
|
|
|
| //--- QUERIES
|
| bool IsEmpty() const { return m_empty; }
|
| bool HasMask() const { return m_has_mask; }
|
| bool IsValid() const { return !m_alloc_failed; }
|
| SCairoRect Rect() const { return m_rect; }
|
|
|
| //--- The integer pixel range the clip can touch. The rasterizer
|
| //--- intersects its own bounding box with this before it walks a
|
| //--- single row, which is what makes a clipped draw cheap rather
|
| //--- than merely correct.
|
| int PixelLeft() const;
|
| int PixelTop() const;
|
| int PixelRight() const; // inclusive
|
| int PixelBottom() const; // exclusive, like the row loop
|
|
|
| //--- how much of this pixel may be drawn to, 0 .. 1
|
| double CoverageAt(const int x, const int y) const;
|
|
|
| //--- MASK CONSTRUCTION
|
| //--- Called by CCairoRasterizer::ClipToPath() and by nobody else.
|
| //--- The four-step shape exists because intersecting a clip with a
|
| //--- path has to READ the old clip while WRITING the new one: the
|
| //--- result is old_coverage * path_coverage, and both operands live
|
| //--- in the same object.
|
| //---
|
| //--- BeginIntersect(bounds) the old mask steps aside, a new
|
| //--- one is allocated and zeroed
|
| //--- PrevCoverageAt(x, y) read the old clip
|
| //--- SetMaskValue(x, y, v) write the new one
|
| //--- EndIntersect() the old mask is let go of
|
|
|
| bool BeginIntersect(const SCairoRect &bounds);
|
| double PrevCoverageAt(const int x, const int y) const;
|
| void SetMaskValue(const int x, const int y, const double value);
|
| void EndIntersect();
|
| };
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Constructor - an empty clip, which allows nothing. |
|
| //| |
|
| //| Deliberately the restrictive default. A clip used before Reset() |
|
| //| has been called is a bug, and a drawing that disappears is a |
|
| //| louder bug report than one that ignores its boundary. |
|
| //+-------------------------------------------------------------------+
|
| CCairoClip::CCairoClip()
|
| {
|
| m_rect.SetEmpty();
|
|
|
| m_empty = true;
|
| m_has_mask = false;
|
| m_prev_mask = false;
|
| m_building = false;
|
| m_alloc_failed = false;
|
|
|
| m_mx = 0;
|
| m_my = 0;
|
| m_mw = 0;
|
| m_mh = 0;
|
| m_px = 0;
|
| m_py = 0;
|
| m_pw = 0;
|
| m_ph = 0;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Open the clip up to a whole buffer, and drop any mask. |
|
| //| |
|
| //| This is what a frame starts with. The mask array is kept, not |
|
| //| freed - the next clipped widget will want a buffer of about the |
|
| //| same size, and this one is already paid for. |
|
| //+-------------------------------------------------------------------+
|
| void CCairoClip::Reset(const int width, const int height)
|
| {
|
| m_rect.Set(0.0, 0.0, (double)width, (double)height);
|
|
|
| m_empty = m_rect.IsEmpty();
|
| m_has_mask = false;
|
| m_prev_mask = false;
|
| m_building = false;
|
|
|
| //--- a refused allocation is not a permanent condition, and this is
|
| //--- the method a frame begins with. Left latched, one failure in one
|
| //--- frame would make IsValid() answer false for the rest of the
|
| //--- session - which is how CCairoPath treats it in Clear(), and the
|
| //--- two had no business disagreeing.
|
| m_alloc_failed = false;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Clip everything away. Drawing through this does nothing at all. |
|
| //+-------------------------------------------------------------------+
|
| void CCairoClip::SetEmpty()
|
| {
|
| m_rect.SetEmpty();
|
|
|
| m_empty = true;
|
| m_has_mask = false;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Hand the mask memory back. |
|
| //+-------------------------------------------------------------------+
|
| void CCairoClip::Release()
|
| {
|
| SetEmpty();
|
|
|
| m_prev_mask = false;
|
| m_building = false;
|
|
|
| ArrayFree(m_mask);
|
| ArrayFree(m_prev);
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Narrow the clip to its overlap with a rectangle. |
|
| //| |
|
| //| The mask, if there is one, is KEPT rather than rebuilt. A mask is |
|
| //| only ever read inside the clip rectangle, so shrinking the |
|
| //| rectangle shrinks the region the mask applies to without touching |
|
| //| a byte of it - which makes "clip to this panel, then to this row" |
|
| //| cost two comparisons. |
|
| //+-------------------------------------------------------------------+
|
| bool CCairoClip::IntersectRect(const SCairoRect &r)
|
| {
|
| m_rect.Intersect(r);
|
|
|
| m_empty = m_rect.IsEmpty();
|
|
|
| return !m_empty;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Take on another clip's state, mask and all. |
|
| //| |
|
| //| The mask array is COPIED rather than shared. Two clips holding |
|
| //| the same array would be two objects with one owner, and the |
|
| //| second one to narrow itself would corrupt the first - which, in a |
|
| //| list of widgets, means one row's clip quietly following its |
|
| //| neighbour's. |
|
| //| |
|
| //| The copy is only as large as the mask actually in use, not as |
|
| //| large as the buffer behind it, because the tail of that buffer is |
|
| //| left over from a bigger clip that has already been restored. |
|
| //+-------------------------------------------------------------------+
|
| bool CCairoClip::CopyFrom(CCairoClip *other)
|
| {
|
| if(other == NULL)
|
| return false;
|
|
|
| //--- this object is being re-initialized out of another one, so
|
| //--- whatever failed in its past is no longer about it
|
| m_alloc_failed = false;
|
|
|
| m_rect = other.m_rect;
|
| m_empty = other.m_empty;
|
|
|
| m_mx = other.m_mx;
|
| m_my = other.m_my;
|
| m_mw = other.m_mw;
|
| m_mh = other.m_mh;
|
|
|
| m_has_mask = other.m_has_mask;
|
| m_prev_mask = false;
|
| m_building = false;
|
|
|
| if(!m_has_mask)
|
| return true;
|
|
|
| const int needed = m_mw * m_mh;
|
|
|
| if(needed <= 0)
|
| {
|
| m_has_mask = false;
|
| return true;
|
| }
|
|
|
| if(ArraySize(m_mask) < needed)
|
| if(ArrayResize(m_mask, needed) < needed)
|
| {
|
| m_alloc_failed = true;
|
| m_has_mask = false;
|
|
|
| return false;
|
| }
|
|
|
| if(ArrayCopy(m_mask, other.m_mask, 0, 0, needed) != needed)
|
| {
|
| m_has_mask = false;
|
| return false;
|
| }
|
|
|
| return true;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| The integer pixel box the clip can touch. |
|
| //| |
|
| //| Floor on the near edges and ceil on the far ones, because a pixel |
|
| //| partly inside a fractional boundary is not nothing - it is what |
|
| //| CoverageAt() reports as 0.35. |
|
| //| |
|
| //| BOTH HALVES OF THE CLIP GET A SAY. The rectangle is the obvious |
|
| //| one. The mask's own box is the other, and after a path clip it is |
|
| //| much the tighter of the two: a circle in the middle of a chart |
|
| //| allows nothing in the corners, and walking them is work with a |
|
| //| guaranteed answer of zero. |
|
| //+-------------------------------------------------------------------+
|
| int CCairoClip::PixelLeft() const
|
| {
|
| if(m_empty)
|
| return 0;
|
|
|
| int left = (int)MathFloor(m_rect.Left());
|
|
|
| if(m_has_mask && m_mx > left)
|
| left = m_mx;
|
|
|
| return left;
|
| }
|
|
|
| //+------------------------------------------------------------------+
|
| //| PixelTop() |
|
| //+------------------------------------------------------------------+
|
| int CCairoClip::PixelTop() const
|
| {
|
| if(m_empty)
|
| return 0;
|
|
|
| int top = (int)MathFloor(m_rect.Top());
|
|
|
| if(m_has_mask && m_my > top)
|
| top = m_my;
|
|
|
| return top;
|
| }
|
|
|
| //+------------------------------------------------------------------+
|
| //| PixelRight() |
|
| //+------------------------------------------------------------------+
|
| int CCairoClip::PixelRight() const
|
| {
|
| if(m_empty)
|
| return -1;
|
|
|
| int right = (int)MathCeil(m_rect.Right()) - 1;
|
|
|
| if(m_has_mask && m_mx + m_mw - 1 < right)
|
| right = m_mx + m_mw - 1;
|
|
|
| return right;
|
| }
|
|
|
| //+------------------------------------------------------------------+
|
| //| PixelBottom() |
|
| //+------------------------------------------------------------------+
|
| int CCairoClip::PixelBottom() const
|
| {
|
| if(m_empty)
|
| return 0;
|
|
|
| int bottom = (int)MathCeil(m_rect.Bottom());
|
|
|
| if(m_has_mask && m_my + m_mh < bottom)
|
| bottom = m_my + m_mh;
|
|
|
| return bottom;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| How much of pixel (x, y) may be drawn to? |
|
| //| |
|
| //| The rectangle part is computed ANALYTICALLY, the same way Part 4 |
|
| //| computes coverage in X: the overlap of the pixel's square with |
|
| //| the clip rectangle. A clip edge at x = 120.4 therefore gives |
|
| //| column 120 a coverage of 0.4 rather than a hard choice between |
|
| //| all and nothing, and a panel boundary that does not land on a |
|
| //| pixel stops being visible as a jagged line. |
|
| //| |
|
| //| The mask part is a lookup. The two multiply, because a pixel half |
|
| //| allowed by the rectangle and half allowed by the mask is a |
|
| //| quarter allowed. |
|
| //+-------------------------------------------------------------------+
|
| double CCairoClip::CoverageAt(const int x, const int y) const
|
| {
|
| if(m_empty)
|
| return 0.0;
|
|
|
| //--- FAST PATH: no mask, and the pixel sits wholly inside the
|
| //--- rectangle, so both overlaps are a full 1.0. That is the state
|
| //--- after every ResetClip(), which is most pixels this library ever
|
| //--- draws, and four comparisons are cheaper than four MathMin /
|
| //--- MathMax calls, two tests and a multiply.
|
| if(!m_has_mask &&
|
| (double)x >= m_rect.Left() && (double)x + 1.0 <= m_rect.Right() &&
|
| (double)y >= m_rect.Top() && (double)y + 1.0 <= m_rect.Bottom())
|
| return 1.0;
|
|
|
| //--- the pixel's overlap with the clip rectangle, one axis at a time
|
| double cx = MathMin((double)x + 1.0, m_rect.Right()) -
|
| MathMax((double)x, m_rect.Left());
|
|
|
| if(!(cx > 0.0))
|
| return 0.0;
|
|
|
| if(cx > 1.0)
|
| cx = 1.0;
|
|
|
| double cy = MathMin((double)y + 1.0, m_rect.Bottom()) -
|
| MathMax((double)y, m_rect.Top());
|
|
|
| if(!(cy > 0.0))
|
| return 0.0;
|
|
|
| if(cy > 1.0)
|
| cy = 1.0;
|
|
|
| double c = cx * cy;
|
|
|
| if(!m_has_mask)
|
| return c;
|
|
|
| //--- outside the mask's own box there is no coverage at all: the mask
|
| //--- was built over the whole region the clip allowed at the time
|
| if(x < m_mx || x >= m_mx + m_mw || y < m_my || y >= m_my + m_mh)
|
| return 0.0;
|
|
|
| const int idx = (y - m_my) * m_mw + (x - m_mx);
|
|
|
| //--- the two halves multiply, and they hold different things: the
|
| //--- rectangle every rectangle the caller asked for, the mask every
|
| //--- path. Neither may carry the other's boundary - the note at the
|
| //--- end of BeginIntersect() says what happens when one does.
|
| return c * (m_mask[idx] / 255.0);
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Step 1 of intersecting with a path: stand the old mask aside and |
|
| //| allocate a new one over `bounds`. |
|
| //| |
|
| //| The old mask has to survive, because the new value of every pixel |
|
| //| is old_coverage * path_coverage. ArraySwap moves it into m_prev |
|
| //| without copying a byte, and EndIntersect() lets go of it again - |
|
| //| so a nested clip costs one extra buffer briefly, rather than one |
|
| //| buffer per nesting level forever. |
|
| //+-------------------------------------------------------------------+
|
| bool CCairoClip::BeginIntersect(const SCairoRect &bounds)
|
| {
|
| SCairoRect box = bounds;
|
|
|
| box.Intersect(m_rect);
|
|
|
| //--- and with the existing mask's own box: outside it the previous
|
| //--- coverage is already zero, so a new mask has nothing to add there
|
| //--- and no reason to be allocated for it
|
| if(m_has_mask)
|
| {
|
| SCairoRect mbox = CairoRect((double)m_mx, (double)m_my,
|
| (double)m_mw, (double)m_mh);
|
|
|
| box.Intersect(mbox);
|
| }
|
|
|
| if(box.IsEmpty())
|
| {
|
| SetEmpty();
|
| return false;
|
| }
|
|
|
| //--- the integer pixel box the new mask has to cover
|
| const int ix0 = (int)MathFloor(box.Left());
|
| const int iy0 = (int)MathFloor(box.Top());
|
| const int ix1 = (int)MathCeil(box.Right());
|
| const int iy1 = (int)MathCeil(box.Bottom());
|
|
|
| const int mw = ix1 - ix0;
|
| const int mh = iy1 - iy0;
|
|
|
| if(mw <= 0 || mh <= 0)
|
| {
|
| SetEmpty();
|
| return false;
|
| }
|
|
|
| //--- the old mask steps aside, taking its own geometry with it
|
| ArraySwap(m_mask, m_prev);
|
|
|
| m_px = m_mx;
|
| m_py = m_my;
|
| m_pw = m_mw;
|
| m_ph = m_mh;
|
| m_prev_mask = m_has_mask;
|
|
|
| const int needed = mw * mh;
|
|
|
| if(ArrayResize(m_mask, needed) < needed)
|
| {
|
| //--- give the old mask back and leave the clip exactly as it was
|
| ArraySwap(m_mask, m_prev);
|
|
|
| m_alloc_failed = true;
|
| m_prev_mask = false;
|
|
|
| return false;
|
| }
|
|
|
| //--- zero means "not reached by the path", which is the right answer
|
| //--- for every pixel the sweep is about to skip
|
| ArrayInitialize(m_mask, 0);
|
|
|
| m_mx = ix0;
|
| m_my = iy0;
|
| m_mw = mw;
|
| m_mh = mh;
|
|
|
| //--- m_rect IS DELIBERATELY NOT NARROWED TO `box`.
|
| //---
|
| //--- It looks like the obvious thing to do - the clip cannot reach
|
| //--- outside the path's bounds, so why not say so - and it is wrong,
|
| //--- because CoverageAt() multiplies the rectangle by the mask. The
|
| //--- mask has just anti-aliased the path's boundary; putting that
|
| //--- same boundary into the rectangle would soften it a second time,
|
| //--- and a clip at x = 10.5 would let through a quarter of the pixel
|
| //--- where it should let through a half.
|
| //---
|
| //--- The two halves of a clip are kept disjoint on purpose: the
|
| //--- rectangle holds the rectangle clips, the mask holds the path
|
| //--- clips. `box` has done its work already - it sized the mask, and
|
| //--- it decided whether anything was left at all.
|
| m_empty = false;
|
| m_has_mask = true;
|
| m_building = true;
|
|
|
| return true;
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Step 2: read the clip as it was BEFORE this intersection began. |
|
| //| |
|
| //| Only the old MASK is read here, not the old rectangle. The |
|
| //| rectangle is applied once, at query time, by CoverageAt() - so |
|
| //| folding it in here as well would be the double counting that |
|
| //| method's comment warns about. |
|
| //+-------------------------------------------------------------------+
|
| double CCairoClip::PrevCoverageAt(const int x, const int y) const
|
| {
|
| if(!m_prev_mask)
|
| return 1.0; // the old clip was a plain rectangle
|
|
|
| if(x < m_px || x >= m_px + m_pw || y < m_py || y >= m_py + m_ph)
|
| return 0.0;
|
|
|
| const int idx = (y - m_py) * m_pw + (x - m_px);
|
|
|
| return (m_prev[idx] / 255.0);
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Step 3: write one pixel of the new mask. |
|
| //| |
|
| //| Writes are refused unless a Begin/End pair is open, and |
|
| //| out-of-range coordinates are dropped rather than clamped. The |
|
| //| rasterizer already walks only the rows and columns the mask |
|
| //| covers, so a value arriving from outside it is a bug - and |
|
| //| clamping would hide that bug by painting it on the border. |
|
| //+-------------------------------------------------------------------+
|
| void CCairoClip::SetMaskValue(const int x, const int y, const double value)
|
| {
|
| if(!m_building)
|
| return;
|
|
|
| if(x < m_mx || x >= m_mx + m_mw || y < m_my || y >= m_my + m_mh)
|
| return;
|
|
|
| double v = value;
|
|
|
| if(v <= 0.0)
|
| v = 0.0;
|
|
|
| if(v > 1.0)
|
| v = 1.0;
|
|
|
| const int idx = (y - m_my) * m_mw + (x - m_mx);
|
|
|
| m_mask[idx] = (uchar)(v * 255.0 + 0.5);
|
| }
|
|
|
| //+-------------------------------------------------------------------+
|
| //| Step 4: the old mask is finished with. |
|
| //| |
|
| //| The array itself is kept. It is the right size for the next clip |
|
| //| of about the same size, and the next one usually is. |
|
| //+-------------------------------------------------------------------+
|
| void CCairoClip::EndIntersect()
|
| {
|
| m_prev_mask = false;
|
| m_building = false;
|
| }
|
|
|
| #endif // CAIRO5_CLIP_MQH
|