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.
This commit is contained in:
Albrecht Schlosser
parent
6aa9357b17
commit
fc36bfd88b
96
FL/fl_draw.H
96
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 <tt>(x, y, w, h)</tt> \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 <tt>(0, 0)</tt>, <tt>(x, y)</tt>,
|
||||
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.
|
||||
*/
|
||||
|
||||
@ -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() */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user