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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_rendering_XIntegerReadOnlyBitmap_idl__
  20 #define __com_sun_star_rendering_XIntegerReadOnlyBitmap_idl__
  21
  22 #include <com/sun/star/lang/IllegalArgumentException.idl>
  23 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  24 #include <com/sun/star/geometry/IntegerPoint2D.idl>
  25 #include <com/sun/star/geometry/IntegerRectangle2D.idl>
  26 #include <com/sun/star/rendering/IntegerBitmapLayout.idl>
  27 #include <com/sun/star/rendering/XBitmap.idl>
  28 #include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
  29
  30
  31 module com { module sun { module star { module rendering {
  32
  33 interface XBitmapPalette;
  34
  35 /** This is a specialized interface for bitmaps having integer color
  36     channels. In contrast to XIntegerBitmap, this
  37     interface only permits read-only access.<p>
  38
  39     Use this interface for e.g. bitmaps that are calculated
  40     on-the-fly, or that are pure functional, and thus cannot be
  41     modified.<p>
  42
  43     If you get passed an instance of
  44     XIntegerReadOnlyBitmap that also supports the
  45     XVolatileBitmap interface, things become a bit more
  46     complicated. When reading data, one has to check for both
  47     VolatileContentDestroyedException and mismatching
  48     IntegerBitmapLayout return values. If either of them
  49     occurs, the whole bitmap read operation should be repeated, if you
  50     need consistent information.<p>
  51  */
  52 interface XIntegerReadOnlyBitmap : XBitmap
  53 {
  54     /** Query the raw data of this bitmap.<p>
  55
  56         Query the raw data of this bitmap, in the format as defined by
  57         getMemoryLayout(). With the given rectangle, a subset of the
  58         whole bitmap can be queried. If the internal data format's
  59         pixel are not integer multiples of bytes (i.e. if one pixel
  60         occupies less than a byte), the leftover content of the bytes
  61         at the right of each scanline is filled with zeros. The
  62         details of the scanline padding are to be retrieved from the
  63         passed bitmap layout.<p>
  64
  65         Note that the bitmap memory layout might change over time for
  66         volatile bitmaps.<p>
  67
  68         @param bitmapLayout
  69         The memory layout the returned data is in. Note that the color
  70         space returned therein needs to always match the current color
  71         space as would have been returned by getMemoryLayout(). This
  72         is necessary to ensure correct operation under changing
  73         XVolatileBitmap.
  74
  75         @param rect
  76         A rectangle, within the bounds of the bitmap, to retrieve the
  77         consent from.
  78
  79         @throws VolatileContentDestroyedException
  80         if the bitmap is volatile, and the content has been destroyed by the system.
  81
  82         @throws com::sun::star::lang::IndexOutOfBoundsException
  83         if parts of the given rectangle are outside the permissible
  84         bitmap area.
  85      */
  86     sequence<byte>      getData( [out] IntegerBitmapLayout bitmapLayout, [in] ::com::sun::star::geometry::IntegerRectangle2D rect )
  87         raises (com::sun::star::lang::IndexOutOfBoundsException,
  88                 VolatileContentDestroyedException);
  89
  90
  91     /** Get a single pixel of the bitmap, returning its color
  92         value.<p>
  93
  94         If the internal data format's pixel are not integer multiples
  95         of bytes (i.e. if one pixel occupies less than a byte - the
  96         case of more than one byte per pixel is not specified), the
  97         color value is returned in the least significant bits of the
  98         single byte returned as the color. The details of the returned
  99         pixel data are to be retrieved from the passed bitmap layout.<p>
 100
 101         Note that the bitmap memory layout might change for volatile
 102         bitmaps.<p>
 103
 104         @param bitmapLayout
 105         The memory layout the returned data is in. Note that the color
 106         space returned therein needs to always match the current color
 107         space as would have been returned by getMemoryLayout(). This
 108         is necessary to ensure correct operation under changing
 109         XVolatileBitmap.
 110
 111         @param pos
 112         A position, within the bounds of the bitmap, to retrieve the
 113         color from.
 114
 115         @throws VolatileContentDestroyedException
 116         if the bitmap is volatile, and the content has been destroyed by the system.
 117
 118         @throws com::sun::star::lang::IndexOutOfBoundsException
 119         if the given position is outside the permissible bitmap area.
 120      */
 121     sequence<byte>      getPixel( [out] IntegerBitmapLayout bitmapLayout, [in] ::com::sun::star::geometry::IntegerPoint2D pos )
 122         raises (com::sun::star::lang::IndexOutOfBoundsException,
 123                 VolatileContentDestroyedException);
 124
 125
 126     /** Query the memory layout for this bitmap.<p>
 127
 128         Please note that for volatile bitmaps, the memory layout might
 129         change between subsequent calls.<p>
 130      */
 131     IntegerBitmapLayout getMemoryLayout();
 132 };
 133
 134 }; }; }; };
 135
 136 #endif
 137
 138 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */