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