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_XIntegerReadOnlyBitmap_idl__
28#define __com_sun_star_rendering_XIntegerReadOnlyBitmap_idl__
29
30#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
31#include <com/sun/star/lang/IllegalArgumentException.idl>
32#endif
33#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
34#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
35#endif
36#ifndef __com_sun_star_geometry_IntegerPoint2D_idl__
37#include <com/sun/star/geometry/IntegerPoint2D.idl>
38#endif
39#ifndef __com_sun_star_geometry_IntegerRectangle2D_idl__
40#include <com/sun/star/geometry/IntegerRectangle2D.idl>
41#endif
42#ifndef __com_sun_star_rendering_IntegerBitmapLayout_idl__
43#include <com/sun/star/rendering/IntegerBitmapLayout.idl>
44#endif
45#ifndef __com_sun_star_rendering_XBitmap_idl__
46#include <com/sun/star/rendering/XBitmap.idl>
47#endif
48#ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
49#include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
50#endif
51
52
53module com { module sun { module star { module rendering {
54
55interface XBitmapPalette;
56
57/** This is a specialized interface for bitmaps having integer color
58    channels. In contrast to <type>XIntegerBitmap</type>, this
59    interface only permits read-only access.<p>
60
61    Use this interface for e.g. bitmaps that are calculated
62    on-the-fly, or that are pure functional, and thus cannot be
63    modified.<p>
64
65    If you get passed an instance of
66    <type>XIntegerReadOnlyBitmap</type> that also supports the
67    <type>XVolatileBitmap</type> interface, things become a bit more
68    complicated. When reading data, one has to check for both
69    <type>VolatileContentDestroyedException</type> and mismatching
70    <type>IntegerBitmapLayout</type> return values. If either of them
71    occurs, the whole bitmap read operation should be repeated, if you
72    need consistent information.<p>
73 */
74interface XIntegerReadOnlyBitmap : XBitmap
75{
76	/** Query the raw data of this bitmap.<p>
77
78    	Query the raw data of this bitmap, in the format as defined by
79    	getMemoryLayout(). With the given rectangle, a subset of the
80    	whole bitmap can be queried. If the internal data format's
81    	pixel are not integer multiples of bytes (i.e. if one pixel
82    	occupies less than a byte), the leftover content of the bytes
83    	at the right of each scanline is filled with zeros. The
84    	details of the scanline padding are to be retrieved from the
85    	passed bitmap layout.<p>
86
87        Note that the bitmap memory layout might change over time for
88        volatile bitmaps.<p>
89
90        @param bitmapLayout
91        The memory layout the returned data is in. Note that the color
92        space returned therein needs to always match the current color
93        space as would have been returned by getMemoryLayout(). This
94        is necessary to ensure correct operation under changing
95        <type>XVolatileBitmap</type>.
96
97        @param rect
98        A rectangle, within the bounds of the bitmap, to retrieve the
99        contens from.
100
101        @throws <type>VolatileContentDestroyedException</type>
102        if the bitmap is volatile, and the content has been destroyed by the system.
103
104        @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
105        if parts of the given rectangle are outside the permissible
106        bitmap area.
107	 */
108	sequence<byte> 		getData( [out] IntegerBitmapLayout bitmapLayout, [in] ::com::sun::star::geometry::IntegerRectangle2D rect )
109        raises (com::sun::star::lang::IndexOutOfBoundsException,
110                VolatileContentDestroyedException);
111
112	//-------------------------------------------------------------------------
113
114	/** Get a single pixel of the bitmap, returning its color
115		value.<p>
116
117		If the internal data format's pixel are not integer multiples
118		of bytes (i.e. if one pixel occupies less than a byte - the
119		case of more than one byte per pixel is not specified), the
120		color value is returned in the least significant bits of the
121		single byte returned as the color. The details of the returned
122		pixel data are to be retrieved from the passed bitmap layout.<p>
123
124        Note that the bitmap memory layout might change for volatile
125        bitmaps.<p>
126
127        @param bitmapLayout
128        The memory layout the returned data is in. Note that the color
129        space returned therein needs to always match the current color
130        space as would have been returned by getMemoryLayout(). This
131        is necessary to ensure correct operation under changing
132        <type>XVolatileBitmap</type>.
133
134        @param pos
135        A position, within the bounds of the bitmap, to retrieve the
136        color from.
137
138        @throws <type>VolatileContentDestroyedException</type>
139        if the bitmap is volatile, and the content has been destroyed by the system.
140
141        @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
142        if the given position is outside the permissible bitmap area.
143	 */
144	sequence<byte>		getPixel( [out] IntegerBitmapLayout bitmapLayout, [in] ::com::sun::star::geometry::IntegerPoint2D pos )
145        raises (com::sun::star::lang::IndexOutOfBoundsException,
146                VolatileContentDestroyedException);
147
148	//-------------------------------------------------------------------------
149
150	/** Query the memory layout for this bitmap.<p>
151
152    	Please note that for volatile bitmaps, the memory layout might
153    	change between subsequent calls.<p>
154	 */
155	IntegerBitmapLayout	getMemoryLayout();
156};
157
158}; }; }; };
159
160#endif
161