JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
AWTPrintLifecycle.java
Go to the documentation of this file.
1/**
2 * Copyright 2013 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28package com.jogamp.nativewindow.awt;
29
30import java.awt.Component;
31import java.awt.Container;
32import java.awt.Graphics;
33import java.awt.Graphics2D;
34import java.awt.print.PrinterJob;
35
36import jogamp.nativewindow.awt.AWTMisc;
37
38/**
39 * Interface describing print lifecycle to support AWT printing,
40 * e.g. on AWT {@link com.jogamp.opengl.GLAutoDrawable GLAutoDrawable}s.
41 * <a name="impl"><h5>Implementations</h5></a>
42 * <p>
43 * Implementing {@link com.jogamp.opengl.GLAutoDrawable GLAutoDrawable} classes based on AWT
44 * supporting {@link Component#print(Graphics)} shall implement this interface.
45 * </p>
46 * <a name="usage"><h5>Usage</h5></a>
47 * <p>
48 * Users attempting to print an AWT {@link Container} containing {@link AWTPrintLifecycle} elements
49 * shall consider decorating the {@link Container#printAll(Graphics)} call with<br>
50 * {@link #setupPrint(double, double, int, int, int) setupPrint(..)} and {@link #releasePrint()}
51 * on all {@link AWTPrintLifecycle} elements in the {@link Container}.<br>
52 * To minimize this burden, a user can use {@link Context#setupPrint(Container, double, double, int, int, int) Context.setupPrint(..)}:
53 * <pre>
54 * Container cont;
55 * double scaleGLMatXY = 72.0/glDPI;
56 * int numSamples = 0; // leave multisampling as-is
57 * PrinterJob job;
58 * ...
59 final AWTPrintLifecycle.Context ctx = AWTPrintLifecycle.Context.setupPrint(cont, scaleGLMatXY, scaleGLMatXY, numSamples);
60 try {
61 AWTEDTExecutor.singleton.invoke(true, new Runnable() {
62 public void run() {
63 try {
64 job.print();
65 } catch (PrinterException ex) {
66 ex.printStackTrace();
67 }
68 } });
69 } finally {
70 ctx.releasePrint();
71 }
72 *
73 * </pre>
74 * </p>
75 */
76public interface AWTPrintLifecycle {
77
78 public static final int DEFAULT_PRINT_TILE_SIZE = 1024;
79
80
81 /**
82 * Shall be called before {@link PrinterJob#print()}.
83 * <p>
84 * See <a href="#usage">Usage</a>.
85 * </p>
86 * @param scaleMatX {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatX * width pixels
87 * @param scaleMatY {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatY * height pixels
88 * @param numSamples multisampling value: < 0 turns off, == 0 leaves as-is, > 0 enables using given num samples
89 * @param tileWidth custom tile width for {@link com.jogamp.opengl.util.TileRenderer#setTileSize(int, int, int) tile renderer}, pass -1 for default.
90 * @param tileHeight custom tile height for {@link com.jogamp.opengl.util.TileRenderer#setTileSize(int, int, int) tile renderer}, pass -1 for default.
91 * FIXME: Add border size !
92 */
93 void setupPrint(double scaleMatX, double scaleMatY, int numSamples, int tileWidth, int tileHeight);
94
95 /**
96 * Shall be called after {@link PrinterJob#print()}.
97 * <p>
98 * See <a href="#usage">Usage</a>.
99 * </p>
100 */
102
103 /**
104 * Convenient {@link AWTPrintLifecycle} context simplifying calling {@link AWTPrintLifecycle#setupPrint(double, double, int, int, int) setupPrint(..)}
105 * and {@link AWTPrintLifecycle#releasePrint()} on all {@link AWTPrintLifecycle} elements of a {@link Container}.
106 * <p>
107 * See <a href="#usage">Usage</a>.
108 * </p>
109 */
110 public static class Context {
111 /**
112 * <p>
113 * See <a href="#usage">Usage</a>.
114 * </p>
115 *
116 * @param c container to be traversed through to perform {@link AWTPrintLifecycle#setupPrint(double, double, int, int, int) setupPrint(..)} on all {@link AWTPrintLifecycle} elements.
117 * @param scaleMatX {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatX * width pixels
118 * @param scaleMatY {@link Graphics2D} {@link Graphics2D#scale(double, double) scaling factor}, i.e. rendering 1/scaleMatY * height pixels
119 * @param numSamples multisampling value: < 0 turns off, == 0 leaves as-is, > 0 enables using given num samples
120 * @param tileWidth custom tile width for {@link TileRenderer#setTileSize(int, int, int) tile renderer}, pass -1 for default.
121 * @param tileHeight custom tile height for {@link TileRenderer#setTileSize(int, int, int) tile renderer}, pass -1 for default.
122 * @return the context
123 */
124 public static Context setupPrint(final Container c, final double scaleMatX, final double scaleMatY, final int numSamples, final int tileWidth, final int tileHeight) {
125 final Context t = new Context(c, scaleMatX, scaleMatY, numSamples, tileWidth, tileHeight);
126 t.setupPrint(c);
127 return t;
128 }
129
130 /**
131 * <p>
132 * See <a href="#usage">Usage</a>.
133 * </p>
134 */
135 public void releasePrint() {
136 count = AWTMisc.performAction(cont, AWTPrintLifecycle.class, releaseAction);
137 }
138
139 /**
140 * @return count of performed actions of last {@link #setupPrint(Container, double, double, int, int, int) setupPrint(..)} or {@link #releasePrint()}.
141 */
142 public int getCount() { return count; }
143
144 private final Container cont;
145 private final double scaleMatX;
146 private final double scaleMatY;
147 private final int numSamples;
148 private final int tileWidth;
149 private final int tileHeight;
150 private int count;
151
152 private final AWTMisc.ComponentAction setupAction = new AWTMisc.ComponentAction() {
153 @Override
154 public void run(final Component c) {
155 ((AWTPrintLifecycle)c).setupPrint(scaleMatX, scaleMatY, numSamples, tileWidth, tileHeight);
156 } };
157 private final AWTMisc.ComponentAction releaseAction = new AWTMisc.ComponentAction() {
158 @Override
159 public void run(final Component c) {
160 ((AWTPrintLifecycle)c).releasePrint();
161 } };
162
163 private Context(final Container c, final double scaleMatX, final double scaleMatY, final int numSamples, final int tileWidth, final int tileHeight) {
164 this.cont = c;
165 this.scaleMatX = scaleMatX;
166 this.scaleMatY = scaleMatY;
167 this.numSamples = numSamples;
168 this.tileWidth = tileWidth;
169 this.tileHeight = tileHeight;
170 this.count = 0;
171 }
172 private void setupPrint(final Container c) {
173 count = AWTMisc.performAction(c, AWTPrintLifecycle.class, setupAction);
174 }
175 }
176}
Convenient AWTPrintLifecycle context simplifying calling setupPrint(..) and AWTPrintLifecycle#release...
static Context setupPrint(final Container c, final double scaleMatX, final double scaleMatY, final int numSamples, final int tileWidth, final int tileHeight)
Interface describing print lifecycle to support AWT printing, e.g.
void releasePrint()
Shall be called after PrinterJob#print().
void setupPrint(double scaleMatX, double scaleMatY, int numSamples, int tileWidth, int tileHeight)
Shall be called before PrinterJob#print().