/src/wrappers/cairo/library/cairo_surface.e

  1note
  2	description: "cairo_surface_t: base class for Cairo surfaces."
  3	copyright: "[
  4					Copyright (C) 2007-2017: Paolo Redaelli,
  5											 Soluciones Informaticas Libres S.A. (Except),
  6											 Cairo team
  7					
  8					This library is free software; you can redistribute it and/or
  9					modify it under the terms of the GNU Lesser General Public License
 10					as published by the Free Software Foundation; either version 2.1 of
 11					the License, or (at your option) any later version.
 12					
 13					This library is distributed in the hope that it will be useful, but
 14					WITHOUT ANY WARRANTY; without even the implied warranty of
 15					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 16					Lesser General Public License for more details.
 17
 18					You should have received a copy of the GNU Lesser General Public
 19					License along with this library; if not, write to the Free Software
 20					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 21					02110-1301 USA
 22			]"
 23	date: "$Date:$"
 24	revision: "$Revision:$"
 25	wrapped_version: "1.2.4"
 26
 27class CAIRO_SURFACE
 28	-- A cairo_surface_t represents an image, either as the destination
 29	-- of a drawing operation or as source when drawing onto another
 30	-- surface. There are different subtypes of CAIRO_SURFACE for
 31	-- different drawing backends; for example, CAIRO_IMAGE_SURFACE is
 32	-- a bitmap image in memory.
 33
 34inherit
 35	C_STRUCT 
 36	REFERENCE_COUNTED 
 37
 38insert
 39	CAIRO_SURFACE_EXTERNALS
 40	CAIRO_SURFACE_TYPE
 41	CAIRO_STATUS
 42	CAIRO_CONTENT
 43
 44create {ANY} make_similar, from_external_pointer
 45
 46feature {ANY} -- Creation
 47
 48	make_similar (another: CAIRO_SURFACE; a_content: INTEGER; a_width, an_height: INTEGER)
 49			-- Create a new surface that is as compatible as possible
 50			-- with an existing surface. For example the new surface will
 51			-- have the same fallback resolution and font options as
 52			-- other. Generally, the new surface will also use the same
 53			-- backend as other, unless that is not possible for some
 54			-- reason. The type of the returned surface may be examined
 55			-- with `type'.
 56
 57			-- Initially the surface contents are all 0 (transparent if
 58			-- contents have transparency, black otherwise.)
 59
 60			-- `another': an existing surface used to select the backend
 61			-- of the new surface
 62
 63			-- content : the content for the new surface
 64
 65			-- a_width:   width of the new surface, (in device-space
 66			-- units)
 67
 68			-- an_height :  height of the new surface (in device-space units)
 69		do
 70			from_external_pointer(cairo_surface_create_similar
 71										 (another.handle, a_content, a_width, an_height))
 72			-- cairo_surface_create_similar returns a pointer to the
 73			-- newly allocated surface. The caller owns the surface and
 74			-- should call cairo_surface_destroy when done with it.  This
 75			-- function always returns a valid pointer, but it will
 76			-- return a pointer to a "nil" surface if other is already in
 77			-- an error state or any other error occurs.
 78		end
 79
 80feature {ANY} -- Operations
 81
 82	finish
 83			-- Finishes the surface and drops all references to external
 84			-- resources. For example, for the Xlib backend it means that
 85			-- cairo will no longer access the drawable, which can be
 86			-- freed. After calling `finish' the only valid operations on
 87			-- a surface are getting and setting user data and
 88			-- referencing and destroying it. Further drawing to the
 89			-- surface will not affect the surface but will instead
 90			-- trigger a `cairo_status_surface_finished' error.
 91
 92			-- When the last call to `destroy' decreases the reference
 93			-- count to zero, cairo will call `finish' if it hasn't been
 94			-- called already, before freeing the resources associated
 95			-- with the surface.
 96		do
 97			cairo_surface_finish(handle)
 98		end
 99
100	flush
101			-- Do any pending drawing for the surface and also restore
102			-- any temporary modification's cairo has made to the
103			-- surface's state. This function must be called before
104			-- switching from drawing on the surface with cairo to
105			-- drawing on it directly with native APIs. If the surface
106			-- doesn't support direct access, then this function does
107			-- nothing.
108		do
109			cairo_surface_flush(handle)
110		end
111
112	font_options: CAIRO_FONT_OPTIONS
113			-- the default font rendering options for the surface. This
114			-- allows display surfaces to report the correct subpixel
115			-- order for rendering on them, print surfaces to disable
116			-- hinting of metrics and so forth. The result can then be
117			-- used to create a CAIRO_SCALED_FONT.
118		do
119			create Result.make
120			cairo_surface_get_font_options (handle, Result.handle)
121		end
122
123	content: INTEGER
124			-- The content type of surface which indicates whether the
125			-- surface contains color and/or alpha information. See
126			-- CAIRO_CONTENT.
127		do
128			Result := cairo_surface_get_content (handle)
129		ensure
130			valid: is_valid_content (Result)
131		end
132	
133	-- TODO: cairo_surface_set_user_data ()
134
135	-- cairo_status_t cairo_surface_set_user_data  (cairo_surface_t *surface,
136	--                                              const cairo_user_data_key_t *key,
137	--                                              void *user_data,
138	--                                              cairo_destroy_func_t destroy);
139
140	--   Attach user data to surface. To remove user data from a surface, call this
141	--   function with the key that was used to set it and NULL for data.
142
143	--   surface :   a cairo_surface_t
144	--   key :       the address of a cairo_user_data_key_t to attach the user data
145	--               to
146	--   user_data : the user data to attach to the surface
147	--   destroy :   a cairo_destroy_func_t which will be called when the surface
148	--               is destroyed or when new user data is attached using the same
149	--               key.
150	--   Returns :   CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could
151	--               not be allocated for the user data.
152
153	--   --------------------------------------------------------------------------
154
155	-- TODO:  cairo_surface_get_user_data ()
156
157	-- void*       cairo_surface_get_user_data     (cairo_surface_t *surface,
158	--                                              const cairo_user_data_key_t *key);
159
160	--   Return user data previously attached to surface using the specified key.
161	--   If no user data has been attached with the given key this function returns
162	--   NULL.
163
164	--   surface : a cairo_surface_t
165	--   key :     the address of the cairo_user_data_key_t the user data was
166	--             attached to
167	--   Returns : the user data previously attached or NULL.
168
169	mark_dirty
170			-- Tells cairo that drawing has been done to surface using
171			-- means other than cairo, and that cairo should reread any
172			-- cached areas. Note that you must call `flush' before doing
173			-- such drawing.
174		do
175			cairo_surface_mark_dirty (handle)
176		end
177
178	mark_dirty_rectangle (an_x, an_y, a_width, an_height: INTEGER)
179			-- Like `mark_dirty', but drawing has been done only to the
180			-- specified rectangle, so that cairo can retain cached
181			-- contents for other parts of the surface.
182
183			-- Any cached clip set on the surface will be reset by this
184			-- function, to make sure that future cairo calls have the
185			-- clip set that they expect.
186
187			-- `an_x': X coordinate of dirty rectangle
188			-- `an_y': Y coordinate of dirty rectangle
189			-- `a_width': width of dirty rectangle
190			-- `an_height': height of dirty rectangle
191		do
192			cairo_surface_mark_dirty_rectangle (handle, an_x, an_y, a_width, an_height)
193		end
194
195	set_device_offset (an_offset: CAIRO_POINT)
196			-- Sets an offset that is added to the device coordinates
197			-- determined by the CTM when drawing to surface. One use
198			-- case for this function is when we want to create a
199			-- cairo_surface_t that redirects drawing for a portion of an
200			-- onscreen surface to an offscreen surface in a way that is
201			-- completely invisible to the user of the cairo API. Setting
202			-- a transformation via `translate' isn't sufficient to do
203			-- this, since functions like `device_to_user' will expose
204			-- the hidden offset.
205
206			-- Note that the offset affects drawing to the surface as
207			-- well as using the surface in a source pattern.
208		require
209			offset_not_void: an_offset /= Void
210		do
211			cairo_surface_set_device_offset (handle, an_offset.x, an_offset.y)
212		end
213
214	device_offset: CAIRO_POINT
215		-- the device offset as set by `set_device_offset'.
216		local
217			an_x, an_y: REAL
218		do
219			cairo_surface_get_device_offset (handle, $an_x, $an_y)
220			create Result.make(an_x,an_y)
221		end
222
223	set_fallback_resolution (x_pixels_per_inch, y_pixels_per_inch: REAL)
224			-- Set the horizontal and vertical resolution for image
225			-- fallbacks.
226
227			-- When certain operations aren't supported natively by a
228			-- backend, cairo will fallback by rendering operations to an
229			-- image and then overlaying that image onto the output. For
230			-- backends that are natively vector-oriented, this function
231			-- can be used to set the resolution used for these image
232			-- fallbacks, (larger values will result in more detailed
233			-- images, but also larger file sizes).
234
235			-- Some examples of natively vector-oriented backends are the
236			-- ps, pdf, and svg backends.
237
238			-- For backends that are natively raster-oriented, image
239			-- fallbacks are still possible, but they are always
240			-- performed at the native device resolution.  So this
241			-- function has no effect on those backends.
242
243			-- NOTE: The fallback resolution only takes effect at the
244			-- time of completing a page (with `show_page' or
245			-- `copy_page') so there is currently no way to have more
246			-- than one fallback resolution in effect on a single page.
247
248			--   x_pixels_per_inch : horizontal setting for pixels per inch
249			--   y_pixels_per_inch : vertical setting for pixels per inch
250		do
251			cairo_surface_set_fallback_resolution (handle, x_pixels_per_inch, y_pixels_per_inch)
252		end
253
254	status: INTEGER
255			-- Checks whether an error has previously occurred for this surface.
256		do
257			Result := cairo_surface_status (handle)
258		ensure
259			valid_result: is_valid_cairo_status (Result)
260		end
261
262feature {ANY} -- Memory handling
263	ref
264			-- Increases the reference count on surface by one. This
265			-- prevents surface from being destroyed until a matching
266			-- call to `destroy' is made.
267		local
268			p: POINTER
269		do
270			p := cairo_surface_reference (handle)
271			check p=handle end
272		end
273
274	unref
275			-- Decreases the reference count on surface by one. If the
276			-- result is zero, then surface and all associated resources
277			-- are freed. See `reference'.
278		do
279			cairo_surface_destroy(handle)
280		end
281
282feature {WRAPPER, WRAPPER_HANDLER} -- Low-level features
283		type: INTEGER
284			-- the type of the backend used to create a surface.  See
285			-- CAIRO_SURFACE_TYPE for available types.
286		do
287			Result := cairo_surface_get_type (handle)
288		ensure
289			is_valid_surface_type (Result)
290		end
291
292end -- class CAIRO_SURFACE