|
30 | 30 |
|
31 | 31 | /** |
32 | 32 | * Main graphics and rendering context, as well as the base API implementation. |
33 | | - * <p> |
| 33 | + * |
| 34 | + * <h2>Subclassing and initializing PGraphics objects</h2> |
34 | 35 | * Starting in release 0149, subclasses of PGraphics are handled differently. |
35 | 36 | * The constructor for subclasses takes no parameters, instead a series of |
36 | 37 | * functions are called by the hosting PApplet to specify its attributes. |
37 | | - * |
38 | 38 | * <ul> |
39 | 39 | * <li>setParent(PApplet) - is called to specify the parent PApplet. |
40 | 40 | * <li>setPrimary(boolean) - called with true if this PGraphics will be the |
|
44 | 44 | * <li>setSize(int, int) - this is called last, at which point it's safe for |
45 | 45 | * the renderer to complete its initialization routine. |
46 | 46 | * </ul> |
47 | | - * |
48 | 47 | * The functions were broken out because of the growing number of parameters |
49 | 48 | * such as these that might be used by a renderer, yet with the exception of |
50 | 49 | * setSize(), it's not clear which will be necessary. So while the size could |
51 | 50 | * be passed in to the constructor instead of a setSize() function, a function |
52 | 51 | * would still be needed that would notify the renderer that it was time to |
53 | 52 | * finish its initialization. Thus, setSize() simply does both. |
| 53 | + * |
| 54 | + * <h2>Know your rights: public vs. private methods</h2> |
| 55 | + * Methods that are protected are often subclassed by other renderers, however |
| 56 | + * they are not set 'public' because they shouldn't be part of the user-facing |
| 57 | + * public API accessible from PApplet. That is, we don't want sketches calling |
| 58 | + * textModeCheck() or vertexTexture() directly. |
| 59 | + * |
| 60 | + * <h2>Handling warnings and exceptions</h2> |
| 61 | + * Methods that are unavailable generally show a warning, unless their lack of |
| 62 | + * availability will soon cause another exception. For instance, if a method |
| 63 | + * like getMatrix() returns null because it is unavailable, an exception will |
| 64 | + * be thrown stating that the method is unavailable, rather than waiting for |
| 65 | + * the NullPointerException that will occur when the sketch tries to use that |
| 66 | + * method. As of release 0149, warnings will only be shown once, and exceptions |
| 67 | + * have been changed to warnings where possible. |
| 68 | + * |
| 69 | + * <h2>Using xxxxImpl() for subclassing smoothness</h2> |
| 70 | + * The xxxImpl() methods are generally renderer-specific handling for some |
| 71 | + * subset if tasks for a particular function (vague enough for you?) For |
| 72 | + * instance, imageImpl() handles drawing an image whose x/y/w/h and u/v coords |
| 73 | + * have been specified, and screen placement (independent of imageMode) has |
| 74 | + * been determined. There's no point in all renderers implementing the |
| 75 | + * <tt>if (imageMode == BLAH)</tt> placement/sizing logic, so that's handled |
| 76 | + * by PGraphics, which then calls imageImpl() once all that is figured out. |
| 77 | + * |
| 78 | + * <h2>His brother PImage</h2> |
| 79 | + * PGraphics subclasses PImage so that it can be drawn and manipulated in a |
| 80 | + * similar fashion. As such, many methods are inherited from PGraphics, |
| 81 | + * though many are unavailable: for instance, resize() is not likely to be |
| 82 | + * implemented; the same goes for mask(), depending on the situation. |
| 83 | + * |
| 84 | + * <h2>What's in PGraphics, what ain't</h2> |
| 85 | + * For the benefit of subclasses, as much as possible has been placed inside |
| 86 | + * PGraphics. For instance, bezier interpolation code and implementations of |
| 87 | + * the strokeCap() method (that simply sets the strokeCap variable) are |
| 88 | + * handled here. Features that will vary widely between renderers are located |
| 89 | + * inside the subclasses themselves. For instance, all matrix handling code |
| 90 | + * is per-renderer: Java 2D uses its own AffineTransform, P2D uses a PMatrix2D, |
| 91 | + * and PGraphics3D needs to keep continually update forward and reverse |
| 92 | + * transformations. A proper (future) OpenGL implementation will have all its |
| 93 | + * matrix madness handled by the card. Lighting also falls under this |
| 94 | + * category, however the base material property settings (emissive, specular, |
| 95 | + * et al.) are handled in PGraphics because they use the standard colorMode() |
| 96 | + * logic. Subclasses should override methods like emissiveFromCalc(), which |
| 97 | + * is a point where a valid color has been defined internally, and can be |
| 98 | + * applied in some manner based on the calcXxxx values. |
| 99 | + * |
| 100 | + * <h2>What's in the PGraphics documentation, what ain't</h2> |
| 101 | + * Some things are noted here, some things are not. For public API, always |
| 102 | + * refer to the <a href="http://processing.org/reference">reference</A> |
| 103 | + * on Processing.org for proper explanations. <b>No attempt has been made to |
| 104 | + * keep the javadoc up to date or complete.</b> It's an enormous task for |
| 105 | + * which we simply do not have the time. |
54 | 106 | */ |
55 | 107 | public class PGraphics extends PImage implements PConstants { |
56 | 108 |
|
|
0 commit comments