/*************************************************************************
 *
 *  OpenOffice.org - a multi-platform office productivity suite
 *
 *  $RCSfile: XCanvas.idl,v $
 *
 *  $Revision: 1.4 $
 *
 *  last change: $Author: rt $ $Date: 2005/09/08 02:58:03 $
 *
 *  The Contents of this file are made available subject to
 *  the terms of GNU Lesser General Public License Version 2.1.
 *
 *
 *    GNU Lesser General Public License Version 2.1
 *    =============================================
 *    Copyright 2005 by Sun Microsystems, Inc.
 *    901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License version 2.1, as published by the Free Software Foundation.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 *
 *    You should have received a copy of the GNU Lesser General Public
 *    License along with this library; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *    MA  02111-1307  USA
 *
 ************************************************************************/
#ifndef __com_sun_star_rendering_XCanvas_idl__
#define __com_sun_star_rendering_XCanvas_idl__

#ifndef __com_sun_star_uno_XInterface_idl__ 
#include <com/sun/star/uno/XInterface.idl> 
#endif 
#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif 
#ifndef __com_sun_star_geometry_RealPoint2D_idl__
#include <com/sun/star/geometry/RealPoint2D.idl>
#endif
#ifndef __com_sun_star_geometry_RealBezierSegment2D_idl__
#include <com/sun/star/geometry/RealBezierSegment2D.idl>
#endif
#ifndef __com_sun_star_geometry_RealRectangle2D_idl__
#include <com/sun/star/geometry/RealRectangle2D.idl>
#endif
#ifndef __com_sun_star_geometry_Matrix2D_idl__
#include <com/sun/star/geometry/Matrix2D.idl>
#endif
#ifndef __com_sun_star_rendering_ViewState_idl__
#include <com/sun/star/rendering/ViewState.idl>
#endif
#ifndef __com_sun_star_rendering_RenderState_idl__
#include <com/sun/star/rendering/RenderState.idl>
#endif
#ifndef __com_sun_star_rendering_FontRequest_idl__
#include <com/sun/star/rendering/FontRequest.idl>
#endif
#ifndef __com_sun_star_rendering_FontInfo_idl__
#include <com/sun/star/rendering/FontInfo.idl>
#endif
#ifndef __com_sun_star_rendering_Texture_idl__
#include <com/sun/star/rendering/Texture.idl>
#endif
#ifndef __com_sun_star_rendering_StringContext_idl__
#include <com/sun/star/rendering/StringContext.idl>
#endif
#ifndef __com_sun_star_rendering_StrokeAttributes_idl__
#include <com/sun/star/rendering/StrokeAttributes.idl>
#endif
#ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
#include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
#endif

#ifndef __com_sun_star_beans_PropertyValue_idl__
#include <com/sun/star/beans/PropertyValue.idl>
#endif


module com {  module sun {  module star {  module geometry {
    interface XMapping2D;
}; }; }; };

module com { module sun { module star { module rendering {

interface XCanvasFont;
interface XPolyPolygon2D;
interface XCachedPrimitive;
interface XBitmap;
interface XGraphicDevice;
interface XTextLayout;

/** Central interface for rendering.<p>

	This is the central interface for graphical output production, and
	the place where all draw methods are located.<p>

    Some notes are in order to explain the concepts used here. The
    <type>XCanvas</type> interface is free of client-modifiable state,
    i.e. it can be used safely and without external synchronization in
    a multi-threaded environment. On the other hand, this implies that
    for nearly every canvas operation, external state is
    required. This is provided by <type>ViewState</type> and
    <type>RenderState</type> in a unified fashion, supplemented by a
    few extra state parameters for some methods (e.g. textured
    polygons or text rendering).<p>

    When used careless, this scheme can be inefficient to some extend,
    because internally, view, render and other states have to be
    combined before rendering. This is especially expensive for
    complex clip polygons, i.e. when both <type>ViewState</type> and
    <type>RenderState</type> have a complex clip polygon set, which
    have to be intersected before rendering. It is therefore
    recommended to combine <type>ViewState</type> and
    <type>RenderState</type> already at the client side, when objects
    are organized in a hierarchical way: the classic example are
    grouped draw shapes, whose parent group object imposes a
    common clipping and a common transformation on its siblings. The
    group object would therefore merge the <type>ViewState</type> and
    the <type>RenderState</type> it is called with into a new
    <type>ViewState</type>, and call its siblings with a
    <type>RenderState</type> containing only the local offset (and no
    extra clipping).<p>

    Furtheron, this stateless nature provides easy ways for
    caching. Every non-trivial operation on <type>XCanvas</type>
    returns a cache object, which, when called to redraw, renders the
    primitive usually much more quickly than the original method. Note
    that such caching is a lot more complicated, should the actual
    rendering a method yields depend on internal state (which is the
    case e.g. for the
    <type>::com::sun::star::drawing::XGraphics</type> interface).<p>

    @since OOo 2.0.0
 */
interface XCanvas : ::com::sun::star::uno::XInterface
{
	 /** Draw a point in device resolution on the device.

     	@param aPoint
        The point to draw.

        @param aViewState
        The viewstate to be used when drawing this point.

        @param aRenderState
        The renderstate to be used when drawing this point.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	void				drawPoint( [in] ::com::sun::star::geometry::RealPoint2D aPoint, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Draw a line in device resolution width (i.e. one device	pixel
		wide).

     	@param aStartPoint
        The start point of the line to draw.

     	@param aEndPoint
        The end point of the line to draw.

        @param aViewState
        The viewstate to be used when drawing this line.

        @param aRenderState
        The renderstate to be used when drawing this line.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	void				drawLine( [in] ::com::sun::star::geometry::RealPoint2D aStartPoint, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Draw a cubic bezier curve in device resolution width (i.e. one
		device pixel wide).

        @param aBezierSegment
        The start and the two control points of the bezier curve.

        @param aEndPoint
        The end point of the bezier curve.

        @param aViewState
        The viewstate to be used when drawing this curve.

        @param aRenderState
        The renderstate to be used when drawing this curve.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	void				drawBezier( [in] ::com::sun::star::geometry::RealBezierSegment2D aBezierSegment, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException); 
 
	//-------------------------------------------------------------------------

	/** Draw a poly-polygon in device resolution line width (i.e. the
		lines are one device pixel wide).

        @param xPolyPolygon
        The poly-polygon to draw.

        @param aViewState
        The viewstate to be used when drawing this polygon.

        @param aRenderState
        The renderstate to be used when drawing this polygon.

        @return a handle to the cached rendering output.
        
        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	XCachedPrimitive	drawPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Stroke each polygon of the provided poly-polygon with the
		specified stroke attributes.<p>

        This method considers the stroking of all polygons as an
        atomic operation in relation to the <type>RenderState</type>'s
        <type>CompositeOperationy</type> operation. That means,
        overlapping strokes from distinct polygons will look exactly
        as overlapping segments of the same polygon, even with
        transparency.<p>

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when stroking this polygon.

        @param aRenderState
        The renderstate to be used when stroking this polygon.

        @param aStrokeAttributes
        Further attributes used to parameterize the stroking.

        @return a handle to the cached rendering output.
        
        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	XCachedPrimitive	strokePolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] StrokeAttributes aStrokeAttributes )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Stroke each polygon of the provided poly-polygon with the
		specified stroke attributes, fill the stroked outline
		with the specified texture graphics.<p>

        This method considers the stroking of all polygons as an
        atomic operation in relation to the <type>RenderState</type>'s
        <type>CompositeOp</type> operation. That means, overlapping
        strokes from distinct polygons will look exactly as
        overlapping segments of the same polygon, even with
        transparency.<p>

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when strokes this polygon.

        @param aRenderState
        The renderstate to be used when stroking this polygon.

        @param aTextures
        A sequence of texture definitions, with which to fill the
        stroked area.

        @param aStrokeAttributes
        Further attributes used to parameterize the stroking.

        @return a handle to the cached rendering output.
        
        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        

        @throws VolatileContentDestroyedException
        if a texture bitmap was volatile, and the content was
        destroyed before the rendering could take place.
	 */
	XCachedPrimitive	strokeTexturedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> aTextures, [in] StrokeAttributes aStrokeAttributes )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException); 

	//-------------------------------------------------------------------------

	/** Stroke each polygon of the provided poly-polygon with the
		specified stroke attributes, fill the stroked outline
		with the specified texture graphics, map the texture to the
		outline via the specified texture mapping.<p>

        This method considers the stroking of all polygons as an
        atomic operation in relation to the <type>RenderState</type>'s
        <type>CompositeOp</type> operation. That means, overlapping
        strokes from distinct polygons will look exactly as
        overlapping segments of the same polygon, even with
        transparency.

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when stroking this polygon.

        @param aRenderState
        The renderstate to be used when stroking this polygon.

        @param aTextures
        A sequence of texture definitions, with which to fill the
        stroked area.

        @param xMapping
        A bilinear mapping function which defines the warping of the
        textures on the output area.

        @param aStrokeAttributes
        Further attributes used to parameterize the stroking.

        @return a handle to the cached rendering output.
        
        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        

        @throws VolatileContentDestroyedException
        if a texture bitmap was volatile, and the content was
        destroyed before the rendering could take place.
	 */
	XCachedPrimitive	strokeTextureMappedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> aTextures, [in] ::com::sun::star::geometry::XMapping2D xMapping, [in] StrokeAttributes aStrokeAttributes )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException); 

	//-------------------------------------------------------------------------

    //  [TODO: Method misplaced at this interface?]

	/** Query the polygonal representation of the stroke outlines, as
		it would be generated by the strokePolyPolygon methods.<p>

        This method can be used to e.g. set a clipping which covers the same
        area as a stroke.<p>

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when generating the outline.

        @param aRenderState
        The renderstate to be used when generating the outline.
        
        @param aStrokeAttributes
        Further attributes used to parameterize the stroking.

        @return a poly-polygon describing the outline of the stroked
        area.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	XPolyPolygon2D 		queryStrokeShapes( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] StrokeAttributes aStrokeAttributes )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Fill the given poly-polygon.<p>

    	This method fills the given poly-polygon according to the
    	<type>RenderState</type>'s color and the poly-polygon's fill
    	rule.<p>

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when filling this polygon.

        @param aRenderState
        The renderstate to be used when filling this polygon.
        
        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.                
	 */
	XCachedPrimitive	fillPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Fill the given poly-polygon with a texture.<p>

    	This method fills the given poly-polygon according to the
    	<type>RenderState</type>'s color, the given textures and
    	poly-polygon's fill rule.<p>

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when filling this polygon.

        @param aRenderState
        The renderstate to be used when filling this polygon.
        
        @param aTextures
        A sequence of texture definitions, with which to fill the
        polygonal area.

        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        

        @throws VolatileContentDestroyedException
        if a texture bitmap was volatile, and the content was
        destroyed before the rendering could take place.
    */
	XCachedPrimitive	fillTexturedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> xTextures )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException); 

	//-------------------------------------------------------------------------

	/** Fill the given poly-polygon with a mapped texture.<p>

    	This method fills the given poly-polygon according to the
    	<type>RenderState</type>'s color, the given textures and
    	poly-polygon's fill rule. The texture is mapped to the
    	poly-polygon's interior via the given texture mapping.<p>

        @param xPolyPolygon
        The poly-polygon to render.

        @param aViewState
        The viewstate to be used when filling this polygon.

        @param aRenderState
        The renderstate to be used when filling this polygon.
        
        @param aTextures
        A sequence of texture definitions, with which to fill the
        polygonal area.

        @param xMapping
        A bilinear mapping function which defines the warping of the
        textures on the output area.

        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        

        @throws VolatileContentDestroyedException
        if a texture bitmap was volatile, and the content was
        destroyed before the rendering could take place.
     */
	XCachedPrimitive	fillTextureMappedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> xTextures, [in] ::com::sun::star::geometry::XMapping2D xMapping )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException); 

	//-------------------------------------------------------------------------

	/** Create a suitable font for the specified font description.

    	@param aFontRequest

        @param aExtraFontProperties
        Additional font properties to be applied when selecting this
        font. Normally, you should not need this parameter. Currently,
        the following properties are recognized: 
        <ul>

        	<il>Kerning: a <type>double</type> between 0 and 1, where
        	0 completely disables kerning. Whether kerning is on or
        	off by default is font-dependent.</il>

        	<il>IsEmphasisMarks: a <type>boolean</type>, where <TRUE>
        	enables automatic placements of emphasis marks, e.g. for
        	Hebrew. The default value, if this property is not
        	specified, is <FALSE>.</il>

        	<il>ExpandedSpacing: a <type>double</type> value which is added 
            between all cell distances for this font. The default value for 
            this property is zero. Use negative values for condensed output, 
            and positive values for expanded output.</il>

        	<il>OptionalLayoutFeatures: a sequence of <type
        	scope=::com::sun::star::beans>PropertyValue</type> listing
        	font-specific optional layout features, like glyph
        	variants.</il>

        </ul>

        @param aFontMatrix
        Font-specific transformation matrix, which affects both the
        glyphs as well as the advancement.

        @returns the requested font, or an invalid reference, if the
        request failed.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the parameters is not within the allowed range.
	 */
	XCanvasFont				createFont( [in] FontRequest aFontRequest, [in] sequence< ::com::sun::star::beans::PropertyValue > aExtraFontProperties, [in] ::com::sun::star::geometry::Matrix2D aFontMatrix )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Query font information, specific to this canvas.<p>

    	@param aFilter
        Filter parameter to reduce the list of returned fonts. Every
        member of <type>FontInfo</type> that is not the empty string
        or the "don't care" value restricts the list of returned fonts
        to contain only those that have the specified attribute.

        @param xFontProperties
        This interface can provide additional font properties to
        filter the list of available fonts against.

        @returns the list of fonts matching the filter set.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the font properties are invalid or not recognized,
        or if one of the <type>FontInfo</type> members is not within
        the permitted range.
	 */
	sequence< FontInfo >	queryAvailableFonts( [in] FontInfo aFilter, [in] sequence< ::com::sun::star::beans::PropertyValue > aFontProperties )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Draw the text given by the substring of the specified string
		with the given font.<p>

        The local origin of this output operation is either the left
        end of the text baseline, for textDirection equal
        LEFT_TO_RIGHT, or the right end of the baseline, for
        textDirection equal to RIGHT_TO_LEFT, respectively.<p>

        @param aText
        The text to output.

        @param xFont
        The font retrieved from this canvas to be used when drawing
        the text.

        @param aViewState
        The viewstate to be used when drawing this text.

        @param aRenderState
        The renderstate to be used when drawing this text.
        
        @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.

        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	XCachedPrimitive		drawText( [in] StringContext aText, [in] XCanvasFont xFont, [in] ViewState aViewState, [in] RenderState aRenderState, [in] byte nTextDirection )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Draw the formatted text given by the text layout.<p>

    	The glyphs as represented by the text layout are always output
    	with the reference position being the leftmost edge of the
    	layout object's baseline. If the layout contains more than one
    	baseline, the baseline of the first strong character in
    	logical order is used here (strong in this context means that
    	the character can be unambiguously assigned to a unicode
    	script).<p>

        @param xLayoutetText
        An interface to the readily layouted text, obtained from a
        <type>XCanvasFont</type> created at this canvas. The text
        layout already carries intrinsic font information.

        @param aViewState
        The viewstate to be used when drawing this text.

        @param aRenderState
        The renderstate to be used when drawing this text.

        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        
	 */
	XCachedPrimitive		drawTextLayout( [in] XTextLayout xLayoutetText, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException); 

	//-------------------------------------------------------------------------

	/** Render the given bitmap.<p>

    	This method renders the bitmap, at a position and shape as
    	specified by the combined view and render transformations. For
    	fast render speed, the bitmap should be created by the
    	corresponding <type>XGraphicDevice</type>'s
    	<member>XGraphicDevice::createCompatibleBitmap()</member>
    	method.<p>

        @param xBitmap
        The bitmap to render.

        @param aViewState
        The viewstate to be used when drawing this text.

        @param aRenderState
        The renderstate to be used when drawing this text.

        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        

        @throws VolatileContentDestroyedException
        if a texture bitmap was volatile, and the content was
        destroyed before the rendering could take place.
	 */
	XCachedPrimitive		drawBitmap( [in] XBitmap xBitmap, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException); 

	/** Render the given bitmap, with a global color modulation.<p>

    	This method renders the bitmap, at a position and shape as
    	specified by the combined view and render transformations. For
    	fast render speed, the bitmap should be created by the
    	corresponding <type>XGraphicDevice</type>'s
    	<member>XGraphicDevice::createCompatibleBitmap()</member>
    	method. The bitmap's color channel values are multiplied with
    	the device color values as specified in the render state.<p>

        @param xBitmap
        The bitmap to render.

        @param aViewState
        The viewstate to be used when drawing this text.

        @param aRenderState
        The renderstate to be used when drawing this text. The device
        color entry in the renderstate is multiplied with every pixel
        color value, and only the result is rendered into the
        canvas. If, for example, the bitmap should be rendered with
        increased global transparency, set all device color channels
        to 1.0, except for the alpha channel, which should be set to
        the desired transparency.

        @return a handle to the cached rendering output.

        @throws com::sun::star::lang::IllegalArgumentException
        if one of the view and renderstate parameters are outside the 
        specified range.        

        @throws VolatileContentDestroyedException
        if a texture bitmap was volatile, and the content was
        destroyed before the rendering could take place.
	 */
	XCachedPrimitive		drawBitmapModulated( [in] XBitmap xBitmap, [in] ViewState aViewState, [in] RenderState aRenderState )
        raises (com::sun::star::lang::IllegalArgumentException,
                VolatileContentDestroyedException); 

	//-------------------------------------------------------------------------

	/** 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.

    	@return the associated <type>XGraphicDevice</type>.
	 */
	XGraphicDevice			getDevice();
};

//=============================================================================

service Canvas: XCanvas;

}; }; }; };

#endif
