Java > Open Source Codes > org > apache > batik > svggen > SVGGraphics2D


1 /*
2
3    Copyright 2001-2003 The Apache Software Foundation
4
5    Licensed under the Apache License, Version 2.0 (the "License");
6    you may not use this file except in compliance with the License.
7    You may obtain a copy of the License at
8
9        http://www.apache.org/licenses/LICENSE-2.0
10
11    Unless required by applicable law or agreed to in writing, software
12    distributed under the License is distributed on an "AS IS" BASIS,
13    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14    See the License for the specific language governing permissions and
15    limitations under the License.
16
17  */
18 package org.apache.batik.svggen;
19
20 import java.awt.BasicStroke ;
21 import java.awt.Color ;
22 import java.awt.Dimension ;
23 import java.awt.Font ;
24 import java.awt.FontMetrics ;
25 import java.awt.Graphics ;
26 import java.awt.Graphics2D ;
27 import java.awt.GraphicsConfiguration ;
28 import java.awt.Image ;
29 import java.awt.Shape ;
30 import java.awt.Stroke ;
31 import java.awt.font.GlyphVector ;
32 import java.awt.font.TextLayout ;
33 import java.awt.geom.AffineTransform ;
34 import java.awt.geom.NoninvertibleTransformException ;
35 import java.awt.image.BufferedImage ;
36 import java.awt.image.BufferedImageOp ;
37 import java.awt.image.ImageObserver ;
38 import java.awt.image.RenderedImage ;
39 import java.awt.image.renderable.RenderableImage ;
40 import java.io.FileOutputStream ;
41 import java.io.IOException ;
42 import java.io.OutputStreamWriter ;
43 import java.io.Writer ;
44 import java.text.AttributedCharacterIterator ;
45
46 import org.apache.batik.ext.awt.g2d.AbstractGraphics2D;
47 import org.apache.batik.ext.awt.g2d.GraphicContext;
48 import org.apache.batik.util.XMLConstants;
49 import org.w3c.dom.Document ;
50 import org.w3c.dom.DocumentFragment ;
51 import org.w3c.dom.Element ;
52 import org.w3c.dom.Node ;
53
54 /**
55  * This implementation of the java.awt.Graphics2D abstract class
56  * allows users to generate SVG (Scalable Vector Graphics) content
57  * from Java code.
58  *
59  * SVGGraphics2D generates a DOM tree whose root is obtained through
60  * the getRoot method. Refer to the DOMTreeManager and DOMGroupManager
61  * documentation for details on the structure of the generated
62  * DOM tree.
63  *
64  * The SVGGraphics2D class can produce a DOM tree using any implementation
65  * that conforms to the W3C DOM 1.0 specification (see http://www.w3.org).
66  * At construction time, the SVGGraphics2D must be given a org.w3.dom.Document
67  * instance that is used as a factory to create the various nodes in the
68  * DOM tree it generates.
69  *
70  * The various graphic context attributes (e.g., AffineTransform,
71  * Paint) are managed by a GraphicContext object.
72  *
73  *
74  * @author <a HREF="mailto:vincent.hardy@eng.sun.com">Vincent Hardy</a>
75  * @version $Id: SVGGraphics2D.java,v 1.42 2005/04/02 12:58:17 deweese Exp $
76  * @see org.apache.batik.ext.awt.g2d.GraphicContext
77  * @see org.apache.batik.svggen.DOMTreeManager
78  * @see org.apache.batik.svggen.DOMGroupManager
79  * @see org.apache.batik.svggen.ImageHandler
80  * @see org.apache.batik.svggen.ExtensionHandler
81  * @see org.w3c.dom.Document
82  */
83 public class SVGGraphics2D extends AbstractGraphics2D
84     implements Cloneable , SVGSyntax, XMLConstants, ErrorConstants {
85     /*
86      * Constants definitions
87      */
88     public static final String DEFAULT_XML_ENCODING = "ISO-8859-1";
89
90     /**
91      * Controls the policy for grouping nodes. Once the number of attributes
92      * overridden by a child element is greater than DEFAULT_MAX_GC_OVERRIDES,
93      * a new group is created.
94      *
95      * @see org.apache.batik.svggen.DOMTreeManager
96      */
97     public static final int DEFAULT_MAX_GC_OVERRIDES = 3;
98
99
100     /**
101      * The DOMTreeManager manages the process of creating
102      * and growing the SVG tree. This SVGGraphics2D relies on
103      * the DOMTreeManager to process attributes based on the
104      * GraphicContext state and create groups when needed.
105      */
106     protected DOMTreeManager domTreeManager;
107
108     /**
109      * The DOMGroupManager manages additions to the current group
110      * node associated for this Graphics2D object. Once a group
111      * is complete, the group manager appends it to the DOM tree
112      * through the DOMTreeManager.
113      * Note that each SVGGraphics2D instance has its own DOMGroupManager
114      * (i.e., its own current group) but that all SVGGraphics2D
115      * originating from the same SVGGraphics2D through various
116      * createGraphics calls share the same DOMTreeManager.
117      */
118     protected DOMGroupManager domGroupManager;
119
120     /**
121      * Contains some information for SVG generation.
122      */
123     protected SVGGeneratorContext generatorCtx;
124
125     /**
126      * Used to convert Java 2D API Shape objects to equivalent SVG
127      * elements
128      */
129     protected SVGShape shapeConverter;
130
131     /**
132      * SVG Canvas size
133      */
134     protected Dimension svgCanvasSize;
135
136     /**
137      * Used to create proper font metrics
138      */
139     protected Graphics2D fmg;
140
141     {
142         BufferedImage bi
143             = new BufferedImage (1, 1, BufferedImage.TYPE_INT_ARGB);
144
145         fmg = bi.createGraphics();
146     }
147
148     /**
149      * @return SVG Canvas size, as set in the root svg element
150      */
151     public final Dimension getSVGCanvasSize(){
152         return svgCanvasSize;
153     }
154
155     /**
156      * Set the Canvas size, this is used to set the width and
157      * height attributes on the outermost 'svg' element.
158      * @param svgCanvasSize SVG Canvas size. May be null (equivalent
159      * to 100%, 100%)
160      */
161     public final void setSVGCanvasSize(Dimension svgCanvasSize) {
162         this.svgCanvasSize = new Dimension (svgCanvasSize);
163     }
164
165     /**
166      * @return the SVGGeneratorContext used by this SVGGraphics2D instance.
167      */
168     public final SVGGeneratorContext getGeneratorContext() {
169         return generatorCtx;
170     }
171
172     /**
173      * @return the SVGShape used by this SVGGraphics2D instance to
174      * turn Java2D shapes into SVG Shape objects.
175      */
176     public final SVGShape getShapeConverter() {
177         return shapeConverter;
178     }
179
180     /**
181      * @return the DOMTreeManager used by this SVGGraphics2D instance
182      */
183     public final DOMTreeManager getDOMTreeManager(){
184         return domTreeManager;
185     }
186
187     /**
188      * Set a DOM Tree manager for the SVGGraphics2D.
189      * @param treeMgr the new DOM Tree manager this SVGGraphics2D should use
190      */
191      protected final void setDOMTreeManager(DOMTreeManager treeMgr) {
192         this.domTreeManager = treeMgr;
193         generatorCtx.genericImageHandler.setDOMTreeManager(domTreeManager);
194     }
195
196      /**
197      * @return the DOMGroupManager used by this SVGGraphics2D instance
198      */
199     protected final DOMGroupManager getDOMGroupManager(){
200         return domGroupManager;
201     }
202
203     /**
204      * Set a new DOM Group manager for this SVGGraphics2D.
205      * @param groupMgr the new DOM Group manager this SVGGraphics2D should use
206      */
207      protected final void setDOMGroupManager(DOMGroupManager groupMgr) {
208     this.domGroupManager = groupMgr;
209     }
210
211     /**
212      * @return the Document used as a DOM object factory by this
213      * SVGGraphics2D instance
214      */
215     public final Document getDOMFactory(){
216         return generatorCtx.domFactory;
217     }
218
219     /**
220      * @return the ImageHandler used by this SVGGraphics2D instance
221      */
222     public final ImageHandler getImageHandler(){
223         return generatorCtx.imageHandler;
224     }
225
226     /**
227      * @return the GenericImageHandler used by this SVGGraphics2D instance
228      */
229     public final GenericImageHandler getGenericImageHandler(){
230         return generatorCtx.genericImageHandler;
231     }
232
233     /**
234      * @return the extension handler used by this SVGGraphics2D instance
235      */
236     public final ExtensionHandler getExtensionHandler(){
237         return generatorCtx.extensionHandler;
238     }
239
240     /**
241      * @param extensionHandler new extension handler this SVGGraphics2D
242      * should use
243      */
244     public final void setExtensionHandler(ExtensionHandler extensionHandler) {
245         generatorCtx.setExtensionHandler(extensionHandler);
246     }
247
248     /**
249      * @param domFactory Factory which will produce Elements for the DOM tree
250      * this Graphics2D generates.
251      * @exception SVGGraphics2DRuntimeException if domFactory is null.
252      */
253     public SVGGraphics2D(Document domFactory) {
254         this(SVGGeneratorContext.createDefault(domFactory), false);
255     }
256
257     /**
258      * @param domFactory Factory which will produce Elements for the DOM tree
259      * this Graphics2D generates.
260      * @param imageHandler defines how images are referenced in the
261      * generated SVG fragment
262      * @param extensionHandler defines how Java 2D API extensions map
263      * to SVG Nodes.
264      * @param textAsShapes if true, all text is turned into SVG shapes in the
265      * convertion. No SVG text is output.
266      *
267      * @exception SVGGraphics2DRuntimeException if domFactory is null.
268      */
269     public SVGGraphics2D(Document domFactory,
270                          ImageHandler imageHandler,
271                          ExtensionHandler extensionHandler,
272                          boolean textAsShapes) {
273         this(buildSVGGeneratorContext(domFactory,
274                                       imageHandler,
275                                       extensionHandler),
276              textAsShapes);
277     }
278
279     /**
280      * Helper method to create an <tt>SVGGeneratorContext</tt> from the
281      * constructor parameters.
282      */
283     public static SVGGeneratorContext
284         buildSVGGeneratorContext(Document domFactory,
285                                  ImageHandler imageHandler,
286                                  ExtensionHandler extensionHandler){
287
288         SVGGeneratorContext generatorCtx = new SVGGeneratorContext(domFactory);
289         generatorCtx.setIDGenerator(new SVGIDGenerator());
290         generatorCtx.setExtensionHandler(extensionHandler);
291         generatorCtx.setImageHandler(imageHandler);
292         generatorCtx.setStyleHandler(new DefaultStyleHandler());
293         generatorCtx.setComment("Generated by the Batik Graphics2D SVG Generator");
294         generatorCtx.setErrorHandler(new DefaultErrorHandler());
295
296         return generatorCtx;
297     }
298
299     /**
300      * Creates a new SVGGraphics2D object.
301      * @param generatorCtx the <code>SVGGeneratorContext</code> instance
302      * that will provide all useful information to the generator.
303      * @param textAsShapes if true, all text is turned into SVG shapes in the
304      * convertion. No SVG text is output.
305      *
306      * @exception SVGGraphics2DRuntimeException if generatorContext is null.
307      */
308     public SVGGraphics2D(SVGGeneratorContext generatorCtx,
309                          boolean textAsShapes) {
310         super(textAsShapes);
311
312         if (generatorCtx == null)
313             // no error handler here as we don't have the ctx...
314 throw new SVGGraphics2DRuntimeException(ERR_CONTEXT_NULL);
315
316         setGeneratorContext(generatorCtx);
317     }
318
319     /**
320      * Sets an non null <code>SVGGeneratorContext</code>.
321      */
322     protected void setGeneratorContext(SVGGeneratorContext generatorCtx) {
323         this.generatorCtx = generatorCtx;
324
325         this.gc = new GraphicContext(new AffineTransform ());
326
327         SVGGeneratorContext.GraphicContextDefaults gcDefaults =
328             generatorCtx.getGraphicContextDefaults();
329
330         if(gcDefaults != null){
331             if(gcDefaults.getPaint() != null){
332                 gc.setPaint(gcDefaults.getPaint());
333             }
334             if(gcDefaults.getStroke() != null){
335                 gc.setStroke(gcDefaults.getStroke());
336             }
337             if(gcDefaults.getComposite() != null){
338                 gc.setComposite(gcDefaults.getComposite());
339             }
340             if(gcDefaults.getClip() != null){
341                 gc.setClip(gcDefaults.getClip());
342             }
343             if(gcDefaults.getRenderingHints() != null){
344                 gc.setRenderingHints(gcDefaults.getRenderingHints());
345             }
346             if(gcDefaults.getFont() != null){
347                 gc.setFont(gcDefaults.getFont());
348             }
349             if(gcDefaults.getBackground() != null){
350                 gc.setBackground(gcDefaults.getBackground());
351             }
352         }
353
354         this.shapeConverter = new SVGShape(generatorCtx);
355         this.domTreeManager = new DOMTreeManager(gc,
356                                                  generatorCtx,
357                                                  DEFAULT_MAX_GC_OVERRIDES);
358         this.domGroupManager = new DOMGroupManager(gc, domTreeManager);
359         this.domTreeManager.addGroupManager(domGroupManager);
360         generatorCtx.genericImageHandler.setDOMTreeManager(domTreeManager);
361     }
362
363     /**
364      * This constructor is used in create()
365      *
366      * @see #create
367      */
368     public SVGGraphics2D(SVGGraphics2D g) {
369         super(g);
370         this.generatorCtx = g.generatorCtx;
371         this.gc.validateTransformStack();
372         this.shapeConverter = g.shapeConverter;
373         this.domTreeManager = g.domTreeManager;
374         this.domGroupManager = new DOMGroupManager(this.gc, this.domTreeManager);
375         this.domTreeManager.addGroupManager(this.domGroupManager);
376     }
377
378     /**
379      * @param svgFileName name of the file where SVG content
380      * should be written
381      */
382     public void stream(String svgFileName) throws SVGGraphics2DIOException {
383         stream(svgFileName, false);
384     }
385
386     /**
387      * @param svgFileName name of the file where SVG content
388      * should be written
389      * @param useCss defines whether the output SVG should use CSS style
390      * properties as opposed to plain attributes.
391      */
392     public void stream(String svgFileName, boolean useCss)
393         throws SVGGraphics2DIOException {
394         try {
395             OutputStreamWriter writer =
396                 new OutputStreamWriter (new FileOutputStream (svgFileName),
397                                        DEFAULT_XML_ENCODING);
398             stream(writer, useCss);
399             writer.flush();
400             writer.close();
401         } catch (SVGGraphics2DIOException io) {
402             // this one as already been handled in stream(Writer, boolean)
403 // method => rethrow it in all cases
404 throw io;
405         } catch (IOException e) {
406             generatorCtx.errorHandler.
407                 handleError(new SVGGraphics2DIOException(e));
408         }
409     }
410
411     /**
412      * @param writer used to writer out the SVG content
413      */
414     public void stream(Writer writer) throws SVGGraphics2DIOException {
415         stream(writer, false);
416     }
417
418     /**
419      * @param writer used to writer out the SVG content
420      * @param useCss defines whether the output SVG should use CSS
421      * style properties as opposed to plain attributes.
422      */
423     public void stream(Writer writer, boolean useCss)
424         throws SVGGraphics2DIOException {
425         Element svgRoot = getRoot();
426         stream(svgRoot, writer, useCss);
427     }
428
429     /**
430      * @param svgRoot root element to stream out
431      */
432     public void stream(Element svgRoot, Writer writer)
433         throws SVGGraphics2DIOException {
434         stream(svgRoot, writer, false);
435     }
436
437     /**
438      * @param svgRoot root element to stream out
439      * @param writer output
440      * @param useCss defines whether the output SVG should use CSS style
441      * properties as opposed to plain attributes.
442      */
443     public void stream(Element svgRoot, Writer writer, boolean useCss)
444         throws SVGGraphics2DIOException {
445         Node rootParent = svgRoot.getParentNode();
446         Node nextSibling = svgRoot.getNextSibling();
447
448         try {
449             //
450 // Enforce that the default and xlink namespace
451 // declarations appear on the root element
452 //
453 svgRoot.setAttributeNS(XMLNS_NAMESPACE_URI,
454                                    XMLNS_PREFIX,
455                                    SVG_NAMESPACE_URI);
456
457             svgRoot.setAttributeNS(XMLNS_NAMESPACE_URI,
458                                    XMLNS_PREFIX + ":" + XLINK_PREFIX,
459                                    XLINK_NAMESPACE_URI);
460
461             DocumentFragment svgDocument =
462                 svgRoot.getOwnerDocument().createDocumentFragment();
463             svgDocument.appendChild(svgRoot);
464
465             if (useCss)
466                 SVGCSSStyler.style(svgDocument);
467
468             XmlWriter.writeXml(svgDocument, writer);
469             writer.flush();
470         } catch (SVGGraphics2DIOException e) {
471             // this catch prevents from catching an SVGGraphics2DIOException
472 // and wrapping it again in another SVGGraphics2DIOException
473 // as would do the second catch (XmlWriter throws SVGGraphics2DIO
474 // Exception but flush throws IOException)
475 generatorCtx.errorHandler.
476                 handleError(e);
477         } catch (IOException io) {
478             generatorCtx.errorHandler.
479                 handleError(new SVGGraphics2DIOException(io));
480         } finally {
481             // Restore the svgRoot to its original tree position
482 if (rootParent != null) {
483                 if (nextSibling == null) {
484                     rootParent.appendChild(svgRoot);
485                 } else {
486                     rootParent.insertBefore(svgRoot, nextSibling);
487                 }
488             }
489         }
490     }
491
492     /**
493      * Invoking this method will return a set of definition element that
494      * contain all the definitions referenced by the attributes generated by
495      * the various converters. This also resets the converters.
496      */
497     public java.util.List getDefinitionSet(){
498         return domTreeManager.getDefinitionSet();
499     }
500
501     /**
502      * Invoking this method will return a reference to the topLevelGroup
503      * Element managed by this object. It will also cause this object
504      * to start working with a new topLevelGroup.
505      *
506      * @return top level group
507      */
508     public Element getTopLevelGroup(){
509         return getTopLevelGroup(true);
510     }
511
512     /**
513      * Invoking this method will return a reference to the topLevelGroup
514      * Element managed by this object. It will also cause this object
515      * to start working with a new topLevelGroup.
516      *
517      * @param includeDefinitionSet if true, the definition set is included and
518      * the converters are reset (i.e., they start with an empty set
519      * of definitions).
520      * @return top level group
521      */
522     public Element getTopLevelGroup(boolean includeDefinitionSet){
523         return domTreeManager.getTopLevelGroup(includeDefinitionSet);
524     }
525
526     /**
527      * Sets the topLevelGroup to the input element. This will throw an exception
528      * if the input element is not of type 'g' or if it is null.
529      */
530     public void setTopLevelGroup(Element topLevelGroup){
531         domTreeManager.setTopLevelGroup(topLevelGroup);
532     }
533
534     /**
535      * @return the svg root node of the SVG document associated with this
536      * object
537      */
538     public Element getRoot(){
539         return getRoot(null);
540     }
541
542     /**
543      * This version of the getRoot method will append the input svgRoot
544      * and set its attributes.
545      *
546      * @param svgRoot an SVG element underwhich the content should
547      * be appended.
548      * @return the svg root node of the SVG document associated with
549      * this object.
550      */
551     public Element getRoot(Element svgRoot) {
552         svgRoot = domTreeManager.getRoot(svgRoot);
553         if (svgCanvasSize != null){
554             svgRoot.setAttributeNS(null, SVG_WIDTH_ATTRIBUTE,
555                                    "" + svgCanvasSize.width);
556             svgRoot.setAttributeNS(null, SVG_HEIGHT_ATTRIBUTE,
557                                    "" + svgCanvasSize.height);
558         }
559         return svgRoot;
560     }
561
562     /**
563      * Creates a new <code>Graphics</code> object that is
564      * a copy of this <code>Graphics</code> object.
565      * @return a new graphics context that is a copy of
566      * this graphics context.
567      */
568     public Graphics create(){
569         return new SVGGraphics2D(this);
570     }
571
572
573     /**
574      * Sets the paint mode of this graphics context to alternate between
575      * this graphics context's current color and the new specified color.
576      * This specifies that logical pixel operations are performed in the
577      * XOR mode, which alternates pixels between the current color and
578      * a specified XOR color.
579      * <p>
580      * When drawing operations are performed, pixels which are the
581      * current color are changed to the specified color, and vice versa.
582      * <p>
583      * Pixels that are of colors other than those two colors are changed
584      * in an unpredictable but reversible manner; if the same figure is
585      * drawn twice, then all pixels are restored to their original values.
586      * @param c1 the XOR alternation color
587      */
588     public void setXORMode(Color c1) {
589         generatorCtx.errorHandler.
590             handleError(new SVGGraphics2DRuntimeException(ERR_XOR));
591     }
592
593     /**
594      * Gets the font metrics for the specified font.
595      * @return the font metrics for the specified font.
596      * @param f the specified font
597      * @see java.awt.Graphics#getFont
598      * @see java.awt.FontMetrics
599      * @see java.awt.Graphics#getFontMetrics()
600      */
601     public FontMetrics getFontMetrics(Font f){
602         return fmg.getFontMetrics(f);
603     }
604
605     /**
606      * Copies an area of the component by a distance specified by
607      * <code>dx</code> and <code>dy</code>. From the point specified
608      * by <code>x</code> and <code>y</code>, this method
609      * copies downwards and to the right. To copy an area of the
610      * component to the left or upwards, specify a negative value for
611      * <code>dx</code> or <code>dy</code>.
612      * If a portion of the source rectangle lies outside the bounds
613      * of the component, or is obscured by another window or component,
614      * <code>copyArea</code> will be unable to copy the associated
615      * pixels. The area that is omitted can be refreshed by calling
616      * the component's <code>paint</code> method.
617      * @param x the <i>x</i> coordinate of the source rectangle.
618      * @param y the <i>y</i> coordinate of the source rectangle.
619      * @param width the width of the source rectangle.
620      * @param height the height of the source rectangle.
621      * @param dx the horizontal distance to copy the pixels.
622      * @param dy the vertical distance to copy the pixels.
623      */
624     public void copyArea(int x, int y, int width, int height,
625                          int dx, int dy){
626         // No-op
627 }
628
629     /**
630      * Draws as much of the specified image as is currently available.
631      * The image is drawn with its top-left corner at
632      * (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's coordinate
633      * space. Transparent pixels in the image do not affect whatever
634      * pixels are already there.
635      * <p>
636      * This method returns immediately in all cases, even if the
637      * complete image has not yet been loaded, and it has not been dithered
638      * and converted for the current output device.
639      * <p>
640      * If the image has not yet been completely loaded, then
641      * <code>drawImage</code> returns <code>false</code>. As more of
642      * the image becomes available, the process that draws the image notifies
643      * the specified image observer.
644      * @param img the specified image to be drawn.
645      * @param x the <i>x</i> coordinate.
646      * @param y the <i>y</i> coordinate.
647      * @param observer object to be notified as more of
648      * the image is converted.
649      * @see java.awt.Image
650      * @see java.awt.image.ImageObserver
651      * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
652      */
653     public boolean drawImage(Image img, int x, int y,
654                              ImageObserver observer) {
655         Element imageElement =
656             getGenericImageHandler().createElement(getGeneratorContext());
657         AffineTransform xform = getGenericImageHandler().handleImage(
658                                                          img, imageElement,
659                                                          x, y,
660                                                          img.getWidth(null),
661                                                          img.getHeight(null),
662                                                          getGeneratorContext());
663         
664         if (xform == null) {
665             domGroupManager.addElement(imageElement);
666         } else {
667             AffineTransform inverseTransform = null;
668             try {
669                 inverseTransform = xform.createInverse();
670             } catch(NoninvertibleTransformException e) {
671                 // This should never happen since handleImage
672 // always returns invertible transform
673 throw new SVGGraphics2DRuntimeException(ERR_UNEXPECTED);
674             }
675             gc.transform(xform);
676             domGroupManager.addElement(imageElement);
677             gc.transform(inverseTransform);
678         }
679         return true;
680     }
681
682     /**
683      * Draws as much of the specified image as has already been scaled
684      * to fit inside the specified rectangle.
685      * <p>
686      * The image is drawn inside the specified rectangle of this
687      * graphics context's coordinate space, and is scaled if
688      * necessary. Transparent pixels do not affect whatever pixels
689      * are already there.
690      * <p>
691      * This method returns immediately in all cases, even if the
692      * entire image has not yet been scaled, dithered, and converted
693      * for the current output device.
694      * If the current output representation is not yet complete, then
695      * <code>drawImage</code> returns <code>false</code>. As more of
696      * the image becomes available, the process that draws the image notifies
697      * the image observer by calling its <code>imageUpdate</code> method.
698      * <p>
699      * A scaled version of an image will not necessarily be
700      * available immediately just because an unscaled version of the
701      * image has been constructed for this output device. Each size of
702      * the image may be cached separately and generated from the original
703      * data in a separate image production sequence.
704      * @param img the specified image to be drawn.
705      * @param x the <i>x</i> coordinate.
706      * @param y the <i>y</i> coordinate.
707      * @param width the width of the rectangle.
708      * @param height the height of the rectangle.
709      * @param observer object to be notified as more of
710      * the image is converted.
711      * @see java.awt.Image
712      * @see java.awt.image.ImageObserver
713      * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
714      */
715     public boolean drawImage(Image img, int x, int y,
716                              int width, int height,
717                              ImageObserver observer){
718         Element imageElement =
719             getGenericImageHandler().createElement(getGeneratorContext());
720         AffineTransform xform
721             = getGenericImageHandler().handleImage(
722                                        img, imageElement,
723                                        x, y,
724                                        width, height,
725                                        getGeneratorContext());
726         
727         if (xform == null) {
728             domGroupManager.addElement(imageElement);
729         } else {
730             AffineTransform inverseTransform = null;
731             try {
732                 inverseTransform = xform.createInverse();
733             } catch(NoninvertibleTransformException e) {
734                 // This should never happen since handleImage
735 // always returns invertible transform
736 throw new SVGGraphics2DRuntimeException(ERR_UNEXPECTED);
737             }
738             gc.transform(xform);
739             domGroupManager.addElement(imageElement);
740             gc.transform(inverseTransform);
741         }
742         return true;
743     }
744
745     /**
746      * Disposes of this graphics context and releases
747      * any system resources that it is using.
748      * A <code>Graphics</code> object cannot be used after
749      * <code>dispose</code>has been called.
750      * <p>
751      * When a Java program runs, a large number of <code>Graphics</code>
752      * objects can be created within a short time frame.
753      * Although the finalization process of the garbage collector
754      * also disposes of the same system resources, it is preferable
755      * to manually free the associated resources by calling this
756      * method rather than to rely on a finalization process which
757      * may not run to completion for a long period of time.
758      * <p>
759      * Graphics objects which are provided as arguments to the
760      * <code>paint</code> and <code>update</code> methods
761      * of components are automatically released by the system when
762      * those methods return. For efficiency, programmers should
763      * call <code>dispose</code> when finished using
764      * a <code>Graphics</code> object only if it was created
765      * directly from a component or another <code>Graphics</code> object.
766      * @see java.awt.Graphics#finalize
767      * @see java.awt.Component#paint
768      * @see java.awt.Component#update
769      * @see java.awt.Component#getGraphics
770      * @see java.awt.Graphics#create
771      */
772     public void dispose() {
773         this.domTreeManager.removeGroupManager(this.domGroupManager);
774     }
775
776     /**
777      * Strokes the outline of a <code>Shape</code> using the settings of the
778      * current <code>Graphics2D</code> context. The rendering attributes
779      * applied include the <code>Clip</code>, <code>Transform</code>,
780      * <code>Paint</code>, <code>Composite</code> and
781      * <code>Stroke</code> attributes.
782      * @param s the <code>Shape</code> to be rendered
783      * @see #setStroke
784      * @see #setPaint
785      * @see java.awt.Graphics#setColor
786      * @see #transform
787      * @see #setTransform
788      * @see #clip
789      * @see #setClip
790      * @see #setComposite
791      */
792     public void draw(Shape s) {
793         // Only BasicStroke can be converted to an SVG attribute equivalent.
794 // If the GraphicContext's Stroke is not an instance of BasicStroke,
795 // then the stroked outline is filled.
796 Stroke stroke = gc.getStroke();
797         if (stroke instanceof BasicStroke ) {
798             Element svgShape = shapeConverter.toSVG(s);
799             if (svgShape != null) {
800                 domGroupManager.addElement(svgShape, DOMGroupManager.DRAW);
801             }
802         } else {
803             Shape strokedShape = stroke.createStrokedShape(s);
804             fill(strokedShape);
805         }
806     }
807
808
809     /**
810      * Renders an image, applying a transform from image space into user space
811      * before drawing.
812      * The transformation from user space into device space is done with
813      * the current <code>Transform</code> in the <code>Graphics2D</code>.
814      * The specified transformation is applied to the image before the
815      * transform attribute in the <code>Graphics2D</code> context is applied.
816      * The rendering attributes applied include the <code>Clip</code>,
817      * <code>Transform</code>, and <code>Composite</code> attributes.
818      * Note that no rendering is done if the specified transform is
819      * noninvertible.
820      * @param img the <code>Image</code> to be rendered
821      * @param xform the transformation from image space into user space
822      * @param obs the {@link ImageObserver}
823      * to be notified as more of the <code>Image</code>
824      * is converted
825      * @return <code>true</code> if the <code>Image</code> is
826      * fully loaded and completely rendered;
827      * <code>false</code> if the <code>Image</code> is still being loaded.
828      * @see #transform
829      * @see #setTransform
830      * @see #setComposite
831      * @see #clip
832      * @see #setClip
833      */
834     public boolean drawImage(Image img,
835                              AffineTransform xform,
836                              ImageObserver obs){
837         boolean retVal = true;
838
839         if (xform == null) {
840             retVal = drawImage(img, 0, 0, null);
841         } else if(xform.getDeterminant() != 0){
842             AffineTransform inverseTransform = null;
843             try{
844    &nb