CairoG2D/MQL5/Include/CairoG2D/Clip.mqh
SandroBegashvil SandroBegashvil 9d0ee3af5c
2026-10-05 12:51:40 +04:00
610 satır
24 KiloByte
MQL5
//+-------------------------------------------------------------------+
//| 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