/src/wrappers/cairo/library/cairo_image_surface.e

  1note
  2	description: "Cairo Image Surface: Cairo surfaces that represent data in memory."
  3	copyright: "[
  4					Copyright (C) 2007-2017: Soluciones Informaticas Libres S.A. (Except),
  5					                   Cairo team
  6					
  7					This library is free software; you can redistribute it and/or
  8					modify it under the terms of the GNU Lesser General Public License
  9					as published by the Free Software Foundation; either version 2.1 of
 10					the License, or (at your option) any later version.
 11					
 12					This library is distributed in the hope that it will be useful, but
 13					WITHOUT ANY WARRANTY; without even the implied warranty of
 14					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 15					Lesser General Public License for more details.
 16
 17					You should have received a copy of the GNU Lesser General Public
 18					License along with this library; if not, write to the Free Software
 19					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 20					02110-1301 USA
 21			]"
 22	date: "$Date:$"
 23	revision: "$Revision:$"
 24	wrapped_version: "1.2.4"
 25
 26class CAIRO_IMAGE_SURFACE
 27	-- Image surfaces provide the ability to render to memory buffers either
 28	-- allocated by cairo or by the calling code. The supported image formats
 29	-- are those defined in CAIRO_FORMAT.
 30
 31inherit
 32	CAIRO_SURFACE
 33
 34insert
 35	CAIRO_FORMAT
 36	CAIRO_IMAGE_SURFACE_EXTERNALS
 37
 38create {ANY}
 39	make, for_data, from_png
 40
 41feature {} -- Creation
 42
 43	make (a_format, a_width, a_height: INTEGER)
 44			-- Creates an image surface of the specified format and dimensions.
 45			-- Initially the surface contents are all 0. (Specifically, within
 46			-- each pixel, each color or alpha channel belonging to format will
 47			-- be 0. The contents of bits within a pixel, but not belonging to
 48			-- the given format are undefined).
 49			-- a_format: format of pixels in the surface to create
 50			-- a_width: width of the surface, in pixels
 51			-- a_height: height of the surface, in pixels
 52			-- Returns: A pointer to the newly created surface. The caller owns
 53			-- the surface and should call cairo_surface_destroy when done with
 54			-- it. This function always returns a valid pointer, but it will
 55			-- return a pointer to a "nil" surface if an error such as out of
 56			-- memory occurs. Always check 'status' to check for this.
 57
 58		require
 59			is_valid_cairo_format (a_format)
 60		do
 61			from_external_pointer (cairo_image_surface_create (a_format, a_width, a_height))
 62		end
 63
 64	for_data (some_data: POINTER; a_format, a_width, a_height, a_stride: INTEGER)
 65			-- Creates an image surface for the provided pixel data.
 66			-- The output buffer must be kept around until the CAIRO_SURFACE is
 67			-- destroyed or 'finish' is called on the surface. The initial
 68			-- contents of buffer will be used as the initial image contents;
 69			-- you must explicitly clear the buffer, using, for example,
 70			-- 'rectangle()' and 'fill()' if you want it cleared.
 71			--
 72			--  data: a pointer to a buffer supplied by the application in which
 73			--        to write contents.
 74			--  format: the format of pixels in the buffer
 75			--  width: the width of the image to be stored in the buffer
 76			--  height: the height of the image to be stored in the buffer
 77			--  stride: the number of bytes between the start of rows in the
 78			--          buffer. Having this be specified separate from width
 79			--          allows for padding at the end of rows, or for writing to
 80			--          a subportion of a larger image.
 81		require
 82			is_valid_cairo_format (a_format)
 83		do
 84			from_external_pointer (cairo_image_surface_create_for_data (some_data,
 85			                       a_format, a_width, a_height, a_stride))
 86		end
 87
 88	from_png (a_filename: STRING)
 89			-- Creates a new image surface and initializes the contents to the
 90			-- given PNG file.
 91			-- Creates a CAIRO_SURFACE initialized with the contents of the
 92			-- PNG file, or a "nil" surface if any error occurred. A nil surface
 93			-- can be checked for with 'status' which may return one of the
 94			-- following values: cairo_status_no_memory,
 95			--                   cairo_status_file_not_found,
 96			--                   cairo_status_read_error
 97		require
 98			a_filename /= Void
 99		do
100			from_external_pointer (cairo_image_surface_create_from_png (
101			                       a_filename.to_external))
102		end
103
104feature {ANY} -- Access
105
106	data: POINTER
107			--Get a pointer to the data of the image surface, for direct
108			-- inspection or modification.
109		do
110			Result := cairo_image_surface_get_data (handle)
111		end
112
113	format: INTEGER
114		--Get the format of the surface.
115		do
116			Result := cairo_image_surface_get_format (handle)
117		ensure
118			is_valid_cairo_format (Result)
119		end
120
121	width: INTEGER
122			--Get the width of the image surface in pixels.
123		do
124			Result := cairo_image_surface_get_width (handle)
125		end
126
127	height: INTEGER
128			--Get the height of the image surface in pixels.
129		do
130			Result := cairo_image_surface_get_height (handle)
131		end
132
133	stride: INTEGER
134			--Get the stride of the image surface in bytes
135		do
136			Result := cairo_image_surface_get_stride (handle)
137		end
138
139feature {ANY} -- Operations
140
141	write_to_png (a_filename: STRING): INTEGER
142			-- Writes the contents of surface to a new file filename as a PNG
143			-- image.
144			-- filename: the name of a file to write to
145			-- Returns: cairo_status_success if the PNG file was written successfully.
146			-- Otherwise, cairo_status_no_memory if memory could not be allocated
147			-- for the operation or cairo_status_surface_type_mismatch if the
148			-- surface does not have pixel contents, or cairo_status_write_error
149			-- if an I/O error occurs while attempting to write the file.
150		require
151			a_filename /= Void
152		do
153			Result := cairo_surface_write_to_png (handle, a_filename.to_external)
154		ensure
155			is_valid_cairo_status (Result)
156		end
157
158end -- class CAIRO_IMAGE_SURFACE