From fc36bfd88bc16cf2e94b6f7d03016ced99b94350 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Mon, 20 Jan 2020 12:50:29 +0100 Subject: [PATCH] Improve documentation of clipping functions Clarify functionality of fl_not_clipped() and fl_clip_box(). Add developer documentation for Fl_Graphics_Driver::clip_box(). Documentation only, no code changes in this commit. --- FL/fl_draw.H | 96 +++++++++++++++++++++++++++----------- src/Fl_Graphics_Driver.cxx | 24 ++++++++-- 2 files changed, 89 insertions(+), 31 deletions(-) diff --git a/FL/fl_draw.H b/FL/fl_draw.H index 3805190b3..6854bcc7c 100644 --- a/FL/fl_draw.H +++ b/FL/fl_draw.H @@ -3,17 +3,17 @@ // // Portable drawing function header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2018 by Bill Spitzak and others. +// Copyright 1998-2020 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this // file is missing or damaged, see the license at: // -// http://www.fltk.org/COPYING.php +// https://www.fltk.org/COPYING.php // // Please report all bugs and problems on the following page: // -// http://www.fltk.org/str.php +// https://www.fltk.org/str.php // /** @@ -100,32 +100,75 @@ inline void fl_push_no_clip() {fl_graphics_driver->push_no_clip(); } you return to FLTK. */ inline void fl_pop_clip() {fl_graphics_driver->pop_clip(); } + /** - Does the rectangle intersect the current clip region? - \param[in] x,y,w,h position and size of rectangle - \returns non-zero if any of the rectangle intersects the current clip - region. If this returns 0 you don't have to draw the object. - - \note - Under X this returns 2 if the rectangle is partially clipped, - and 1 if it is entirely inside the clip region. - */ -inline int fl_not_clipped(int x, int y, int w, int h) {return fl_graphics_driver->not_clipped(x,y,w,h); } + Does the rectangle intersect the current clip region? + + \param[in] x,y,w,h position and size of rectangle + + \returns non-zero if any of the rectangle intersects the current clip + region. If this returns 0 you don't have to draw the object. + + \note Under X this returns 2 if the rectangle is partially clipped + and 1 if it is entirely inside the clip region. + + \see fl_clip_box() +*/ +inline int fl_not_clipped(int x, int y, int w, int h) { + return fl_graphics_driver->not_clipped(x, y, w, h); +} + /** - Intersects the rectangle with the current clip region and returns the - bounding box of the result. - - Returns non-zero if the resulting rectangle is different to the original. - This can be used to limit the necessary drawing to a rectangle. - \p W and \p H are set to zero if the rectangle is completely outside the region. - \param[in] x,y,w,h position and size of rectangle - \param[out] X,Y,W,H position and size of resulting bounding box. - \returns Non-zero if the resulting rectangle is different to the original. - */ -inline int fl_clip_box(int x, int y, int w, int h, int& X, int& Y, int& W, int& H) - {return fl_graphics_driver->clip_box(x,y,w,h,X,Y,W,H); } + Intersects a rectangle with the current clip region and returns the + bounding box of the result. + + Returns non-zero if the resulting rectangle is different to the original. + The given rectangle (x, y, w, h) \e should be entirely inside its + window, otherwise the result may be unexpected, i.e. this function \e may + not clip the rectangle to the window coordinates and size. In particular + \p x and \p y \e should not be negative. + + The resulting bounding box can be used to limit the necessary drawing to + this rectangle. + + Example: + \code + void MyGroup::draw() { + int X = 0, Y = 0, W = 0, H = 0; + int ret = fl_clip_box(x(), y(), w(), h(), X, Y, W, H); + if (ret == 0) { // entire group is visible (not clipped) + // full drawing code here + } else { // parts of this group are clipped + // partial drawing code here (uses X, Y, W, and H to test) + } + } + \endcode + + \p W and \p H are set to zero if the rectangle is completely outside the + clipping region. In this case \p X and \p Y are undefined and should + not be used. Possible values are (0, 0), (x, y), + or anything else (platform dependent). + + \note This function is platform-dependent. If the given rectangle is not + entirely inside the window, the results are not guaranteed to be the + same on all platforms. + + \param[in] x,y,w,h position and size of rectangle + \param[out] X,Y,W,H position and size of resulting bounding box. + + \returns Non-zero if the resulting rectangle is different to the original. + + \see fl_not_clipped() +*/ +inline int fl_clip_box(int x, int y, int w, int h, int& X, int& Y, int& W, int& H) { + return fl_graphics_driver->clip_box(x, y, w, h, X, Y, W, H); +} + /** Undoes any clobbering of clip done by your program */ -inline void fl_restore_clip() { fl_graphics_driver->restore_clip(); } +inline void fl_restore_clip() { + fl_graphics_driver->restore_clip(); +} + /** Replaces the top of the clipping stack with a clipping region of any shape. @@ -133,6 +176,7 @@ inline void fl_restore_clip() { fl_graphics_driver->restore_clip(); } \param[in] r clipping region */ inline void fl_clip_region(Fl_Region r) { fl_graphics_driver->clip_region(r); } + /** Returns the current clipping region. */ diff --git a/src/Fl_Graphics_Driver.cxx b/src/Fl_Graphics_Driver.cxx index 6eb670348..0fbe80106 100644 --- a/src/Fl_Graphics_Driver.cxx +++ b/src/Fl_Graphics_Driver.cxx @@ -9,11 +9,11 @@ // the file "COPYING" which should have been included with this file. If this // file is missing or damaged, see the license at: // -// http://www.fltk.org/COPYING.php +// https://www.fltk.org/COPYING.php // // Please report all bugs and problems to: // -// http://www.fltk.org/str.php +// https://www.fltk.org/str.php // /** @@ -462,16 +462,30 @@ void Fl_Graphics_Driver::polygon(int x0, int y0, int x1, int y1, int x2, int y2) /** see fl_push_clip() */ void Fl_Graphics_Driver::push_clip(int x, int y, int w, int h) {} -/** see fl_clip_box() */ +/** + Default graphics driver implementation of fl_clip_box(). + + This default implementation is sufficient for a graphics driver that does not + support clipping. Drivers that support clipping must override this virtual method. + + It returns + - in (X, Y, W, H) the same values as given in (x, y, w, h) respectively + - 0 (zero) as the function return value + which means that \b nothing was clipped. + + \returns 0 (zero) - nothing was clipped + + \see fl_clip_box() +*/ int Fl_Graphics_Driver::clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H) { X = x; Y = y; W = w; H = h; - return 0; // completely inside + return 0; } -/** see fl_not_clipped() */ +/** see fl_not_clipped() */ int Fl_Graphics_Driver::not_clipped(int x, int y, int w, int h) {return 1;} /** see fl_begin_complex_polygon() */