offapi/com/sun/star/rendering/XBufferController.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_rendering_XBufferController_idl__
  28 #define __com_sun_star_rendering_XBufferController_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  34 #include <com/sun/star/lang/IllegalArgumentException.idl>
  35 #endif
  36
  37 module com { module sun { module star { module rendering {
  38
  39 /** Interface providing access to double/multi-buffer facilities of
  40     screen devices.<p>
  41
  42     This interface provides methods to enable and control
  43     double/multi-buffering facilities on screen devices.<p>
  44
  45     @since OOo 2.0.0
  46  */
  47 interface XBufferController : ::com::sun::star::uno::XInterface
  48 {
  49     /** Create the given number of background buffers.<p>
  50
  51         There's one buffer implicitely available, which is the canvas
  52         surface itself. Thus, calling <code>createBuffers(1)</code>
  53         creates a double-buffered object.<p>
  54
  55         @param nBuffers
  56         The number of background&lt;buffers requested. Must be greater
  57         than 0.
  58
  59         @return the number of actually generated buffers, which might
  60         be between 0 (no double-buffering available) and nBuffers.
  61
  62         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
  63         if nBuffers is smaller than one.
  64       */
  65     long    createBuffers( [in] long nBuffers )
  66         raises (com::sun::star::lang::IllegalArgumentException);
  67
  68     //-------------------------------------------------------------------------
  69
  70     /** Destroy all buffers generated via this object.
  71      */
  72     void    destroyBuffers();
  73
  74     //-------------------------------------------------------------------------
  75
  76     /** Switch the display to show the specified buffer.<p>
  77
  78         The method returns, when the switch is performed and the
  79         selected buffer is shown on screen, or immediately when an
  80         error occurs. If the switch was successful, subsequent render
  81         operations will be directed to the new backbuffer.<p>
  82
  83         Use this method if you need your screen display to be in sync
  84         with other things, e.g. sound playback.<p>
  85
  86         @param bUpdateAll
  87         When <TRUE/>, update the whole screen. When <FALSE/>,
  88         implementation is permitted to restrict update to areas the
  89         canvas itself changed (e.g. because of render operations, or
  90         changes on the sprites). The former is useful for updates
  91         after window expose events, the latter for animation display.
  92
  93         @return whether the switch was performed successfully.
  94
  95         @throws <type>com::sun::star::lang::IllegalArgumentException</type>
  96         if nBuffer is outside the permissible range.
  97      */
  98     boolean showBuffer( [in] boolean bUpdateAll );
  99
 100     //-------------------------------------------------------------------------
 101
 102     /** Schedule the display of the specified buffer.<p>
 103
 104         The method returns, when the switching of the buffer is
 105         successfully scheduled, or immediately when an error
 106         occurs. If the switch was successful, subsequent render
 107         operations will be directed to the new backbuffer. Note that,
 108         if the buffer switching is exceedingly slow, or the frequency
 109         of switchBuffer() is exceedingly high, the buffer scheduled
 110         for display here might become the current render target
 111         <em>before</em> it is fully displayed on screen. In this case,
 112         any rendering operation to this buffer will block, until it is
 113         safe to perform the operation without visible cluttering.<p>
 114
 115         Use this method if you favor maximal render speed, but don't
 116         necessarily require your screen display to be in sync with
 117         other things, e.g. sound playback.<p>
 118
 119         @param bUpdateAll
 120         When <TRUE/>, update the whole screen. When <FALSE/>,
 121         implementation is permitted to restrict update to areas the
 122         canvas itself changed (e.g. because of render operations, or
 123         changes on the sprites). The former is useful for updates
 124         after window expose events, the latter for animation display.
 125
 126         @return whether the switch was performed successfully.
 127      */
 128     boolean switchBuffer( [in] boolean bUpdateAll );
 129
 130 };
 131
 132 }; }; }; };
 133
 134 #endif