Proposal: css::rendering::XSimpleCanvas
|
View:
New views
15 Messages
—
Rating Filter:
Alert me
|
 |
Proposal: css::rendering::XSimpleCanvas
by Thorsten Behrens
::
Rate this Message:
Hi,
within the context of OOo extensions & improved usability of the toolkit API, we thought about superseding the deprecated css::awt::XGraphics rendering interface with something new. The css::rendering::XCanvas interface was deemed a little bit too complex for basic rendering, as it is e.g. necessary for rendering parts of a control (like individual list box entries). Therefore, here comes a proposal for a simplified canvas interface, taking the essentials from css::awt::XGraphics (and dropping the non-portable/legacy functionality), which can easily be implemented as a facade around a real XCanvas: --%<------------------------------------------------------------------ interface XSimpleCanvas: com::sun::star::uno::XInterface { /** Select a font.<p> This method selects the specified font (or a close substitute) as the current font for text output.<p> @param sFontName The name of the font (like e.g. Arial) @param size The size of the font (note that this is not the usual points unit, but in the same coordinate system as the other rendering operations - usually, device pixel). @param bold When true, selected font is bold. @param italic When true, selected font is italic */ void selectSimpleFont( [in] string sFontName, [in]double size, [in] bool bold, [in] bool italic ); //------------------------------------------------------------------------- /** Request the font metrics of the current font.<p> @return the font metrics of the currently selected font. */ FontMetrics getFontMetrics(); //------------------------------------------------------------------------- /** Sets the color used by line and text operations.<p> To disable stroking, simply set this color to something with zero alpha (i.e. fully transparent).<p> @param nsRgbaColor RGBA color tuple, interpreted in the sRGB color space. */ void setPenColor( [in] com::sun::star::util::Color nsRgbaColor ); //------------------------------------------------------------------------- /** Sets the fill color.<p> To disable filling, simply set this color to something with zero alpha (i.e. fully transparent).<p> @param nsRgbaColor RGBA color tuple, interpreted in the sRGB color space. */ void setFillColor( [in] com::sun::star::util::Color nsRgbaColor ); //------------------------------------------------------------------------- /** Sets the clip to the specified poly-polygon.<p> */ void setClip( [in] XPolyPolygon2D aClipPoly ); //------------------------------------------------------------------------- /** Sets the clip to the specified rectangle.<p> */ void setRectClip( [in] ::com::sun::star::geometry::RealRectangle2D aRect ); //------------------------------------------------------------------------- /** Set the current transform matrix.<p> */ void setTransformation( [in] ::com::sun::star::geometry::AffineMatrix2D aTransform ); //------------------------------------------------------------------------- /** Sets a single pixel on the canvas.<p> */ void drawPixel( [in] ::com::sun::star::geometry::RealPoint2D aPoint ); //------------------------------------------------------------------------- /** Draws a line on the canvas.<p> */ void drawLine( [in] ::com::sun::star::geometry::RealPoint2D aStartPoint, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint ); //------------------------------------------------------------------------- /** Draws a bezier curve on the canvas.<p> */ void drawBezier( [in] ::com::sun::star::geometry::RealBezierSegment2D aBezierSegment, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint ); //------------------------------------------------------------------------- /** Draws a rectangle on the canvas.<p> */ void drawRect( [in] ::com::sun::star::geometry::RealRectangle2D aRect ); //------------------------------------------------------------------------- /** Draws a poly-polygon on the canvas.<p> */ void drawPolyPolygon( [in] XPolyPolygon2D xPolyPolygon ); //------------------------------------------------------------------------- /** Draws text on the canvas.<p> @param aText Text to render @param aOutPos Output position of the text. This is the left or right edge, depending on nTextDirection. Output position is always relative to the font baseline. @param nTextDirection A value from the <type>TextDirection</type> collection, denoting the main writing direction for this string. The main writing direction determines the origin of the text output, i.e. the left edge for left-to-right and the right edge for right-to-left text. */ void drawText( [in] StringContext aText, [in] ::com::sun::star::geometry::RealPoint2D aOutPos, [in] byte nTextDirection ); //------------------------------------------------------------------------- /** Draws the bitmap on the canvas.<p> @param xBitmap Bitmap to render @param aLeftTop Left, top position of the bitmap on the destination canvas. */ void drawBitmap( [in] XBitmap xBitmap, [in] ::com::sun::star::geometry::RealPoint2D aLeftTop ); //------------------------------------------------------------------------- /** Request the associated graphic device for this canvas.<p> A graphic device provides methods specific to the underlying output device capabilities, which are common for all canvases rendering to such a device. This includes device resolution, color space, or bitmap formats.<p> @return the associated <type>XGraphicDevice</type>. */ XGraphicDevice getDevice(); //------------------------------------------------------------------------- /** Query the underlying <type>XCanvas</type>.<p> @return the canvas interface this object is internally based on. */ XCanvas getCanvas(); //------------------------------------------------------------------------- }; --%<------------------------------------------------------------------ Feedback greatly appreciated! Cheers, -- Thorsten --------------------------------------------------------------------- To unsubscribe, e-mail: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
Re: Proposal: css::rendering::XSimpleCanvas
by Frank Schönheit - Sun Microsystems Germany
::
Rate this Message:
Hi Thorsten,
> /** Sets the clip to the specified poly-polygon.<p> > */ > void setClip( [in] XPolyPolygon2D aClipPoly ); can probably be saved since we have access to the XCanvas, where this also can be done. I think a non-rect clipping is seldom enough to justify removing this functionality from the simplified interface. > /** Set the current transform matrix.<p> > */ > void setTransformation( [in] ::com::sun::star::geometry::AffineMatrix2D aTransform ); I'm not sure this is needed at the simplified version. I'm not even sure I know what this is good for in general ;) > //------------------------------------------------------------------------- > > /** Sets a single pixel on the canvas.<p> > */ > void drawPixel( [in] ::com::sun::star::geometry::RealPoint2D aPoint ); I assume that aPoint is in pixel coordinates. If so, what's the sense in having *real* coordinates, instead of integers? Just wondering. > /** Draws a bezier curve on the canvas.<p> > */ > void drawBezier( [in] ::com::sun::star::geometry::RealBezierSegment2D aBezierSegment, > [in] ::com::sun::star::geometry::RealPoint2D aEndPoint ); Sounds too ... unusual to me for inclusion in the X*Simple* interface. > //------------------------------------------------------------------------- > > /** Draws the bitmap on the canvas.<p> > > @param xBitmap > Bitmap to render > > @param aLeftTop > Left, top position of the bitmap on the destination canvas. > */ > void drawBitmap( [in] XBitmap xBitmap, > [in] ::com::sun::star::geometry::RealPoint2D aLeftTop ); Lot of other APIs use css.graphic.XGraphic. Since XSimpleCanvas is going to be a convenience interface, there should be either an easy way to obtain an XBitmap from an XGraphic, or a method taking an XGraphic. Also, I think having access to the state of the simple canvas might be necessary (sorry I previously thought and told you otherwise :), in case people really want to use more complex functionality at the XCanvas. They need the current state of the simple XCanvas then, don't they? Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenheit@... - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Database http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --------------------------------------------------------------------- To unsubscribe, e-mail: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
|
|
|
Re: Proposal: css::rendering::XSimpleCanvas
by Frank Schönheit - Sun Microsystems Germany
::
Rate this Message:
Hi Thorsten,
>>I'm not sure this is needed at the simplified version. I'm not even sure >>I know what this is good for in general ;) > > Might come in handy when you need rotated bitmaps or text. If it's mainly about rotation, then add a method "setRotation" (or so). Clients of this interface - remember: convenience, simplyfied, and so - will not know how to create an "AffineMatrix2D" when they want to rotate their bitmap by 90 degrees. >>I assume that aPoint is in pixel coordinates. If so, what's the sense in >>having *real* coordinates, instead of integers? Just wondering. > > In concert with transformations, this does make sense. Apart from > that, it keeps the interface consistent (having real coordinates for > e.g. lines is AFAICT uncontroversial - XCanvas has anti-aliasing > implementations). Okay. >>Lot of other APIs use css.graphic.XGraphic. Since XSimpleCanvas is going >>to be a convenience interface, there should be either an easy way to >>obtain an XBitmap from an XGraphic, or a method taking an XGraphic. > > Naa, lots? I count 9... Okay, let me say it the other way round: The usual way to retrieve *ready-made* images today is from the XGraphicProvider, which gives you an XGraphic. So as long as you don't have a bitmap copied from some other device, or created programmatically, you will probably load it from some file or resource or so, and then have an XGraphic. The XSimpleCanvas should /somehow/ be able to cope with this. > ...but of course you're right, from an ease-of-use POV. Is a helper > service acceptable, that can convert an XGraphic into an XBitmap, or > alternatively render an XGraphic to an XCanvas (complementing the > GraphicRendererVCL service)? The second sounds like too much indirections to me. Conversion would be better. Even better, IMO, would be a drawGraphic :) Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenheit@... - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Database http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --------------------------------------------------------------------- To unsubscribe, e-mail: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
|
|
|
Re: Proposal: css::rendering::XSimpleCanvas
by Frank Schönheit - Sun Microsystems Germany
::
Rate this Message:
Hi Thorsten,
>>If it's mainly about rotation, then add a method "setRotation" (or so). > > Problematic - what would be the pivot point of the rotation? But I'd > volunteer writing an XSimpleCanvas HowTo, covering also this topic. ;-) What is a pivot point? No, I don't really expect an answer, I just want to point out that you might miss the target audience here. People who know what a pivot point is, and how to build an affine matrix, will not use XSimpleCanvas. On the other hand, people who will use XSimpleCanvas will probably be very happy with a simple "setRotation", since that's what they need (if at all). People who just evolve from the second class to the first can use XCanvas directly, if necessary. I strongly vote for not alienating the second class'es people by throwing "affine transformation", "pivot point", and other meaningless (sorry :) techno babble at them. Else, we should think about whom this whole interface should really serve. >>The second sounds like too much indirections to me. Conversion would be >>better. Even better, IMO, would be a drawGraphic :) > > XGraphic is alien to XCanvas, thus I'd be extremely reluctant to take > it into the interface the put it into css.awt, and it will not be alien anymore ;) > (besides that one will need rendering of > XGraphic also on XCanvas, I guess). Why? Conversion could happen internally in drawGraphic, before it's passed to the XCanvas. > Converting XGraphic to XBitmap is > lossy, in general (because XGraphic can also contain vector > images). That's okay - for the target audience of this interface, as I understand it. > What's wrong with a GraphicRendererX(Simple)Canvas? As a > matter of fact, that's how you render it to an OutDev... Well, talking about today's Output Device API is not really a good argument, as X(Simple)Canvas is meant exactly to replace it on the long term, isn't it. Besides that: The renderer is, as I said, too much indirections for my taste: XGraphicRenderer renderer = GraphicRendererCanvas.create( context ); renderer.setPropertyValue( "Canvas", simpleCanvas ); renderer.render( graphic ) as opposed to simpleCanvas.drawGraphic( graphic ) Okay, perhaps if you can simplify the renderer so that its usage is XCanvasGraphicRenderer renderer = CanvasGraphicRenderer.create( context ) renderer.renderToCanvas( canvas, graphic ) or XCanvasGraphicRenderer renderer = CanvasGraphicRenderer.create( context, canvas ) renderer.render( graphic ) then I'd say it is simple enough. (Again, in my understanding the main purpose of this interface is to provide *simple* access to the most often used operations.) Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenheit@... - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Database http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --------------------------------------------------------------------- To unsubscribe, e-mail: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
|
|
|
Re: Proposal: css::rendering::XSimpleCanvas
by Frank Schönheit - Sun Microsystems Germany
::
Rate this Message:
Hi Thorsten,
>>People who know what a pivot point is, and how to build an affine >>matrix, will not use XSimpleCanvas. On the other hand, people who will >>use XSimpleCanvas will probably be very happy with a simple >>"setRotation", since that's what they need (if at all). >> > Doesn't help. Rotation without being able to set the center of > rotation (that's what pivot point means here) is utterly useless. Okay, then a semi-simpl "setRotation( degree, center )" :) I wonder how difficult it is for a non-mathematical API user to create an AffineMatrix2D from a degree and a center point. Please don't tell me this needs pen and paper, this would make the method completely useless to the average user (and thus I'd continue to argue it should be removed). If there were some service which creates such a matrix from a degree and a center point, then I'd vote for leaving the method in. As a compromise :), what about adding an /additional/ simplified "setRotation"? >>I strongly vote for not alienating the second class'es people by >>throwing "affine transformation", "pivot point", and other meaningless >>(sorry :) techno babble at them. > > I see your point, but I don't think we need dumbing down the interface > more than necessary. Transformations come almost for free on the > canvas (both simple and normal), and make things easy that have been > clumsy before. Every modern graphics API has them, people who need it > will (quite easily) learn about them, and the rest can simply leave > this method alone. You are argueing from the wrong side here, IMO. The fact that affine transformations can be implemented easily doesn't have anything to do with the question whether or not to slay the user of a XSimpleFoo API :) I conitnue to think that a majority of users (of this interface) will neither be able to easily set a rotation, nor have any other use for the setTransformation, so it's superfluous. >>Else, we should think about whom this whole interface should really serve. >> > > People who want to render simple stuff in user draw, I'd say. Those > will need rotation/scaling eventually, and it'd be a shame to have an > XSimpleCanvas2 just because of this missing expressiveness (or > exposing people to the full power of XCanvas, if they need > transformations). Which reminds me ... I don't know XCanvas and css.rendering in detail, but is it true that XSimpleCanvas, except simplifying the API, internally "only" holds the RenderState and the ViewState to be used for XCanvas' methods? If so, would it make sense to expose those two as attributes/methods? Else, the gap between using XSimpleCanvas and XSimpleCanvas::getCanvas would be pretty big, since a client which needs one small functionality of XCanvas is immediately forced to create own View/RenderStates, which need to account for everything else which he did so far with the XSimpleCanvas. Quite a steep learning curve, which could be eased by providing those two states. >>>(besides that one will need rendering of >>>XGraphic also on XCanvas, I guess). >> >>Why? Conversion could happen internally in drawGraphic, before it's >>passed to the XCanvas. >> > Sure. But what about the people using naked XCanvas? Should they > create an XSimpleCanvas, just because they need to render an XGraphic? > I call _that_ clumsy... Good point :) >>>Converting XGraphic to XBitmap is >>>lossy, in general (because XGraphic can also contain vector >>>images). >> >>That's okay - for the target audience of this interface, as I understand it. > > No, it's not. Just because an interface is simple/easy to use, it does > not mean it has to encourage wrong usage (please note that I'm really > thinking long-term here - a few years from now, scalable UI will be > prevalent, see Avalon/Aqua/increasingly cairo-based toolkits. I'm sure > you don't want ugly up-scaled bitmaps in OOo then...) I don't get your point here. Can XBitmap contain vector images? If not, then wouldn't it be better to use XGraphics, according to your argueing? /me is confused. > So, > clearly, an idiom like this should be achievable: > > mxRenderer.render( graphic ); > > or, if you retrieve the canvas dynamically: > > mxRenderer.render( graphic, canvas ); > > Looks concise enough to me. ;-) Sounds good to me :) Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenheit@... - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Database http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --------------------------------------------------------------------- To unsubscribe, e-mail: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
|
|
|
Re: Proposal: css::rendering::XSimpleCanvas
by Frank Schönheit - Sun Microsystems Germany
::
Rate this Message:
Hi Thorsten,
>>I wonder how difficult it is for a non-mathematical API user to create >>an AffineMatrix2D from a degree and a center point. Please don't tell me >>this needs pen and paper, this would make the method completely useless >>to the average user (and thus I'd continue to argue it should be removed). >>If there were some service which creates such a matrix from a degree and >>a center point, then I'd vote for leaving the method in. > > basegfx::B2DHomMatrix aMatrix; > aMatrix.rotate(nAngle); > aMatrix.scale(nScaleX,nScaleY); > aMatrix.translate(nMoveX,nMoveY); > ... > canvas.setTransformation( > basegfx::unotools::affineMatrixFromHomMatrix(aMatrix)); > > All the expressive power you need is in B2DHomMatrix. We can even add > additional convenience functions, if you miss anything. Okay, and now the version for the developer writing a component in Basic. Well, extensions of that kind in Basic might be unusual, so: Python. Or Ruby. Or ... you get the idea. We're talking about a UNO API here, so only UNO services are allowed :) >>>I see your point, but I don't think we need dumbing down the interface > Well, given the existence of B2DHomMatrix (and > java.awt.geom.AffineTransform, BTW) - do you still think the > transformation abstraction is too complex? See above. Without an UNO-accessible way: yes. > So, to summarize: except for setTransformation(), we seem to agree > largely. Yes. > I'd vote for keeping it, I'd vote for removing it :) > /** Retrieve current clip rect > */ > com::sun::star::geometry::RealRectangle2D getCurrentClipRect(); thinking more about it (sorry :): Do we need this? What happens when the current clip region isn't a rectangle? Should we just have a "getClip" returning the complete thing? Finally, retrieval is much more seldom than setting it, probably. Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenheit@... - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Database http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --------------------------------------------------------------------- To unsubscribe, e-mail: interface-discuss-unsubscribe@... For additional commands, e-mail: interface-discuss-help@... |
|
|
|
|
|
Re: Proposal: css::rendering::XSimpleCanvas
by Frank Schönheit - Sun Microsystems Germany
::
Rate this Message:
|
