1*b1cdbd2cSJim Jagielski/************************************************************** 2*b1cdbd2cSJim Jagielski * 3*b1cdbd2cSJim Jagielski * Licensed to the Apache Software Foundation (ASF) under one 4*b1cdbd2cSJim Jagielski * or more contributor license agreements. See the NOTICE file 5*b1cdbd2cSJim Jagielski * distributed with this work for additional information 6*b1cdbd2cSJim Jagielski * regarding copyright ownership. The ASF licenses this file 7*b1cdbd2cSJim Jagielski * to you under the Apache License, Version 2.0 (the 8*b1cdbd2cSJim Jagielski * "License"); you may not use this file except in compliance 9*b1cdbd2cSJim Jagielski * with the License. You may obtain a copy of the License at 10*b1cdbd2cSJim Jagielski * 11*b1cdbd2cSJim Jagielski * http://www.apache.org/licenses/LICENSE-2.0 12*b1cdbd2cSJim Jagielski * 13*b1cdbd2cSJim Jagielski * Unless required by applicable law or agreed to in writing, 14*b1cdbd2cSJim Jagielski * software distributed under the License is distributed on an 15*b1cdbd2cSJim Jagielski * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16*b1cdbd2cSJim Jagielski * KIND, either express or implied. See the License for the 17*b1cdbd2cSJim Jagielski * specific language governing permissions and limitations 18*b1cdbd2cSJim Jagielski * under the License. 19*b1cdbd2cSJim Jagielski * 20*b1cdbd2cSJim Jagielski *************************************************************/ 21*b1cdbd2cSJim Jagielski 22*b1cdbd2cSJim Jagielski 23*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_rendering_XSprite_idl__ 24*b1cdbd2cSJim Jagielski#define __com_sun_star_rendering_XSprite_idl__ 25*b1cdbd2cSJim Jagielski 26*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_uno_XInterface_idl__ 27*b1cdbd2cSJim Jagielski#include <com/sun/star/uno/XInterface.idl> 28*b1cdbd2cSJim Jagielski#endif 29*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ 30*b1cdbd2cSJim Jagielski#include <com/sun/star/lang/IllegalArgumentException.idl> 31*b1cdbd2cSJim Jagielski#endif 32*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_geometry_RealPoint2D_idl__ 33*b1cdbd2cSJim Jagielski#include <com/sun/star/geometry/RealPoint2D.idl> 34*b1cdbd2cSJim Jagielski#endif 35*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_geometry_AffineMatrix2D_idl__ 36*b1cdbd2cSJim Jagielski#include <com/sun/star/geometry/AffineMatrix2D.idl> 37*b1cdbd2cSJim Jagielski#endif 38*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_rendering_ViewState_idl__ 39*b1cdbd2cSJim Jagielski#include <com/sun/star/rendering/ViewState.idl> 40*b1cdbd2cSJim Jagielski#endif 41*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_rendering_RenderState_idl__ 42*b1cdbd2cSJim Jagielski#include <com/sun/star/rendering/RenderState.idl> 43*b1cdbd2cSJim Jagielski#endif 44*b1cdbd2cSJim Jagielski 45*b1cdbd2cSJim Jagielskimodule com { module sun { module star { module rendering { 46*b1cdbd2cSJim Jagielski 47*b1cdbd2cSJim Jagielski/** Interface to control a sprite object.<p> 48*b1cdbd2cSJim Jagielski 49*b1cdbd2cSJim Jagielski This is the basic interface to control a sprite object on a 50*b1cdbd2cSJim Jagielski <type>XSpriteCanvas</type>. Sprites are moving, back-buffered 51*b1cdbd2cSJim Jagielski objects.<p> 52*b1cdbd2cSJim Jagielski */ 53*b1cdbd2cSJim Jagielskipublished interface XSprite : ::com::sun::star::uno::XInterface 54*b1cdbd2cSJim Jagielski{ 55*b1cdbd2cSJim Jagielski /** Set overall transparency of the sprite.<p> 56*b1cdbd2cSJim Jagielski 57*b1cdbd2cSJim Jagielski This method is useful for e.g. fading in/out of animations.<p> 58*b1cdbd2cSJim Jagielski 59*b1cdbd2cSJim Jagielski Please note that if this sprite is not animated, the 60*b1cdbd2cSJim Jagielski associated <type>XSpriteCanvas</type> does not update changed 61*b1cdbd2cSJim Jagielski sprites automatically, but has to be told to do so via 62*b1cdbd2cSJim Jagielski <member>XSpriteCanvas::updateScreen()</member>.<p> 63*b1cdbd2cSJim Jagielski 64*b1cdbd2cSJim Jagielski @param nAlpha 65*b1cdbd2cSJim Jagielski New global alpha value to composite this sprite with the 66*b1cdbd2cSJim Jagielski background. Valid range is [0,1]. 67*b1cdbd2cSJim Jagielski 68*b1cdbd2cSJim Jagielski @throws <type>com::sun::star::lang::IllegalArgumentException</type> 69*b1cdbd2cSJim Jagielski if nAlpha is not within the permissible range. 70*b1cdbd2cSJim Jagielski */ 71*b1cdbd2cSJim Jagielski void setAlpha( [in] double nAlpha ) 72*b1cdbd2cSJim Jagielski raises (com::sun::star::lang::IllegalArgumentException); 73*b1cdbd2cSJim Jagielski 74*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 75*b1cdbd2cSJim Jagielski 76*b1cdbd2cSJim Jagielski /** Move sprite to the specified position.<p> 77*b1cdbd2cSJim Jagielski 78*b1cdbd2cSJim Jagielski The position specified here is first transformed by the 79*b1cdbd2cSJim Jagielski combined view and render transformation. The resulting 80*b1cdbd2cSJim Jagielski position is then used as the output position (also in device 81*b1cdbd2cSJim Jagielski coordinates) of the rendered sprite content.<p> 82*b1cdbd2cSJim Jagielski 83*b1cdbd2cSJim Jagielski Please note that if this sprite is not animated, the 84*b1cdbd2cSJim Jagielski associated <type>XSpriteCanva</type> does not update changed sprites 85*b1cdbd2cSJim Jagielski automatically, but has to be told to do so via 86*b1cdbd2cSJim Jagielski <member>XSpriteCanvas::updateScreen()</member>.<p> 87*b1cdbd2cSJim Jagielski 88*b1cdbd2cSJim Jagielski @param aNewPos 89*b1cdbd2cSJim Jagielski The new position, in user coordinate space, to move the sprite to. 90*b1cdbd2cSJim Jagielski 91*b1cdbd2cSJim Jagielski @param aViewState 92*b1cdbd2cSJim Jagielski The viewstate to be used when interpreting aNewPos. 93*b1cdbd2cSJim Jagielski 94*b1cdbd2cSJim Jagielski @param aRenderState 95*b1cdbd2cSJim Jagielski The renderstate to be used when interpreting aNewPos. 96*b1cdbd2cSJim Jagielski 97*b1cdbd2cSJim Jagielski @throws <type>com::sun::star::lang::IllegalArgumentException</type> 98*b1cdbd2cSJim Jagielski if one of the view and renderstate parameters are outside the 99*b1cdbd2cSJim Jagielski specified range. 100*b1cdbd2cSJim Jagielski */ 101*b1cdbd2cSJim Jagielski void move( [in] ::com::sun::star::geometry::RealPoint2D aNewPos, [in] ViewState aViewState, [in] RenderState aRenderState ) 102*b1cdbd2cSJim Jagielski raises (com::sun::star::lang::IllegalArgumentException); 103*b1cdbd2cSJim Jagielski 104*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 105*b1cdbd2cSJim Jagielski 106*b1cdbd2cSJim Jagielski /** Apply a local transformation to the sprite.<p> 107*b1cdbd2cSJim Jagielski 108*b1cdbd2cSJim Jagielski The given transformation matrix locally transforms the sprite 109*b1cdbd2cSJim Jagielski shape. If this transformation contains translational 110*b1cdbd2cSJim Jagielski components, be aware that sprite content moved beyond the 111*b1cdbd2cSJim Jagielski sprite area (a box from (0,0) to (spriteWidth,spriteHeight)) 112*b1cdbd2cSJim Jagielski might (but need not) be clipped. Use 113*b1cdbd2cSJim Jagielski <member>XSprite::move</member> to change the sprite location 114*b1cdbd2cSJim Jagielski on screen. The canvas implementations are free, if they have a 115*b1cdbd2cSJim Jagielski cached representation of the sprite at hand, to transform only 116*b1cdbd2cSJim Jagielski this cached representation (e.g. a bitmap), instead of 117*b1cdbd2cSJim Jagielski re-rendering the sprite from first principles. This is usually 118*b1cdbd2cSJim Jagielski the case for an implementation of a <type>XCustomSprite</type> 119*b1cdbd2cSJim Jagielski interface, since it typically has no other cached pictorial 120*b1cdbd2cSJim Jagielski information at hand.<p> 121*b1cdbd2cSJim Jagielski 122*b1cdbd2cSJim Jagielski Please note that if this sprite is not animated, the 123*b1cdbd2cSJim Jagielski associated <type>XSpriteCanvas</type> does not update changed 124*b1cdbd2cSJim Jagielski sprites automatically, but has to be told to do so via 125*b1cdbd2cSJim Jagielski <member>XSpriteCanvas::updateScreen()</member>.<p> 126*b1cdbd2cSJim Jagielski 127*b1cdbd2cSJim Jagielski @param aTransformation 128*b1cdbd2cSJim Jagielski The transformation to apply to the sprite shape. 129*b1cdbd2cSJim Jagielski 130*b1cdbd2cSJim Jagielski @throws <type>com::sun::star::lang::IllegalArgumentException</type> 131*b1cdbd2cSJim Jagielski if the given transformation matrix is singular. 132*b1cdbd2cSJim Jagielski */ 133*b1cdbd2cSJim Jagielski void transform( [in] com::sun::star::geometry::AffineMatrix2D aTransformation ) 134*b1cdbd2cSJim Jagielski raises (com::sun::star::lang::IllegalArgumentException); 135*b1cdbd2cSJim Jagielski 136*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 137*b1cdbd2cSJim Jagielski 138*b1cdbd2cSJim Jagielski /** Apply a clipping to the shape output.<p> 139*b1cdbd2cSJim Jagielski 140*b1cdbd2cSJim Jagielski The given clip poly-polygon is always interpreted in device 141*b1cdbd2cSJim Jagielski coordinate space. As the sprite has its own local coordinate 142*b1cdbd2cSJim Jagielski system, with its origin on screen being equal to its current 143*b1cdbd2cSJim Jagielski position, the clip poly-polygon's origin will always coincide 144*b1cdbd2cSJim Jagielski with the sprite's origin. Furthermore, if any sprite 145*b1cdbd2cSJim Jagielski transformation is set via transform(), the clip is subject to 146*b1cdbd2cSJim Jagielski this transformation, too. The implementation is free, if it 147*b1cdbd2cSJim Jagielski has a cached representation of the sprite at hand, to 148*b1cdbd2cSJim Jagielski clip-output only this cached representation (e.g. a bitmap), 149*b1cdbd2cSJim Jagielski instead of re-rendering the sprite from first principles. This 150*b1cdbd2cSJim Jagielski is usually the case for an implementation of a 151*b1cdbd2cSJim Jagielski <type>XCustomSprite</type> interface, since it typically has 152*b1cdbd2cSJim Jagielski no other cached pictorial information at hand.<p> 153*b1cdbd2cSJim Jagielski 154*b1cdbd2cSJim Jagielski Please note that if this sprite is not animated, the 155*b1cdbd2cSJim Jagielski associated <type>XSpriteCanvas</type> does not update changed 156*b1cdbd2cSJim Jagielski sprites automatically, but has to be told to do so via 157*b1cdbd2cSJim Jagielski <member>XSpriteCanvas::updateScreen()</member>.<p> 158*b1cdbd2cSJim Jagielski 159*b1cdbd2cSJim Jagielski Specifying an empty interface denotes no clipping, 160*b1cdbd2cSJim Jagielski i.e. everything contained in the sprite will be visible 161*b1cdbd2cSJim Jagielski (subject to device-dependent constraints, of 162*b1cdbd2cSJim Jagielski course). Specifying an empty XPolyPolygon2D, i.e. a 163*b1cdbd2cSJim Jagielski poly-polygon containing zero polygons, or an XPolyPolygon2D 164*b1cdbd2cSJim Jagielski with any number of empty sub-polygons, denotes the NULL 165*b1cdbd2cSJim Jagielski clip. That means, nothing from the sprite will be visible.<p> 166*b1cdbd2cSJim Jagielski 167*b1cdbd2cSJim Jagielski @param aClip 168*b1cdbd2cSJim Jagielski The clip poly-polygon to apply. 169*b1cdbd2cSJim Jagielski */ 170*b1cdbd2cSJim Jagielski void clip( [in] XPolyPolygon2D aClip ); 171*b1cdbd2cSJim Jagielski 172*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 173*b1cdbd2cSJim Jagielski 174*b1cdbd2cSJim Jagielski /** Set sprite priority.<p> 175*b1cdbd2cSJim Jagielski 176*b1cdbd2cSJim Jagielski The sprite priority determines the order of rendering relative 177*b1cdbd2cSJim Jagielski to all other sprites of the associated canvas. The higher the 178*b1cdbd2cSJim Jagielski priority, the later will the sprite be rendered, or, in other 179*b1cdbd2cSJim Jagielski words, the closer to the screen surface the sprite is shown.<p> 180*b1cdbd2cSJim Jagielski 181*b1cdbd2cSJim Jagielski @param nPriority 182*b1cdbd2cSJim Jagielski New sprite priority value to serve as the sort key when 183*b1cdbd2cSJim Jagielski determining sprite rendering order. Avoid NaNs and other 184*b1cdbd2cSJim Jagielski irregular floating point values here, the order position for 185*b1cdbd2cSJim Jagielski sprites with such a priority value is undefined. 186*b1cdbd2cSJim Jagielski */ 187*b1cdbd2cSJim Jagielski void setPriority( [in] double nPriority ); 188*b1cdbd2cSJim Jagielski 189*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 190*b1cdbd2cSJim Jagielski 191*b1cdbd2cSJim Jagielski /** Make the sprite visible.<p> 192*b1cdbd2cSJim Jagielski 193*b1cdbd2cSJim Jagielski This method makes the sprite visible on the canvas it was 194*b1cdbd2cSJim Jagielski created on.<p> 195*b1cdbd2cSJim Jagielski */ 196*b1cdbd2cSJim Jagielski void show(); 197*b1cdbd2cSJim Jagielski 198*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------- 199*b1cdbd2cSJim Jagielski 200*b1cdbd2cSJim Jagielski /** Make the sprite invisible.<p> 201*b1cdbd2cSJim Jagielski 202*b1cdbd2cSJim Jagielski This method makes the sprite invisible.<p> 203*b1cdbd2cSJim Jagielski */ 204*b1cdbd2cSJim Jagielski void hide(); 205*b1cdbd2cSJim Jagielski 206*b1cdbd2cSJim Jagielski}; 207*b1cdbd2cSJim Jagielski 208*b1cdbd2cSJim Jagielski}; }; }; }; 209*b1cdbd2cSJim Jagielski 210*b1cdbd2cSJim Jagielski#endif 211