## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --               GtkAda - Ada95 binding for Gtk+/Gnome               --

3.     --                                                                   --

4.     --                    Copyright (C) 2010, AdaCore                    --

5.     --                                                                   --

6.     -- This library is free software; you can redistribute it and/or     --

7.     -- modify it under the terms of the GNU General Public               --

8.     -- License as published by the Free Software Foundation; either      --

9.     -- version 2 of the License, or (at your option) any later version.  --

10.     --                                                                   --

11.     -- This library is distributed in the hope that it will be useful,   --

12.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

13.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

14.     -- General Public License for more details.                          --

15.     --                                                                   --

16.     -- You should have received a copy of the GNU General Public         --

17.     -- License along with this library; if not, write to the             --

18.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

19.     -- Boston, MA 02111-1307, USA.                                       --

20.     --                                                                   --

21.     -- As a special exception, if other files instantiate generics from  --

22.     -- this unit, or you link this unit with other files to produce an   --

23.     -- executable, this  unit  does not  by itself cause  the resulting  --

24.     -- executable to be covered by the GNU General Public License. This  --

25.     -- exception does not however invalidate any other reasons why the   --

26.     -- executable file  might be covered by the  GNU Public License.     --

27.     -----------------------------------------------------------------------

29.     --  <description>

30.     --  Image surfaces provide the ability to render to memory buffers either

31.     --  allocated by Cairo or by the calling code. The supported image formats are

32.     --  those defined in Cairo_Format.

33.     --  </description>

34.     --

35.     --  <c_version>1.8.8</c_version>

36.     --  <group>Cairo</group>

38.     package Cairo.Image_SurfaceTo API docTo specTo body is

40.        --  Cairo_Format is used to identify the memory format of

41.        --  image data.

42.        --

43.        --  New entries may be added in future versions.

44.        type Cairo_Format is

45.          (Cairo_Format_ARGB32,

46.           --  Each pixel is a 32-bit quantity, with

47.           --  alpha in the upper 8 bits, then red, then green, then blue.

48.           --  The 32-bit quantities are stored native-endian. Pre-multiplied

49.           --  alpha is used. (That is, 50 transparent red is 0x80800000,

50.           --  not 0x80ff0000.)

52.           Cairo_Format_RGB24,

53.           --  Each pixel is a 32-bit quantity, with

54.           --  the upper 8 bits unused. Red, Green, and Blue are stored

55.           --  in the remaining 24 bits in that order.

57.           Cairo_Format_A8,

58.           --  Each pixel is a 8-bit quantity holding an alpha value.

60.           Cairo_Format_A1,

61.           --  Each pixel is a 1-bit quantity holding

62.           --  an alpha value. Pixels are packed together into 32-bit

63.           --  quantities. The ordering of the bits matches the

64.           --  endianess of the platform. On a big-endian machine, the

65.           --  first pixel is in the uppermost bit, on a little-endian

66.           --  machine the first pixel is in the least-significant bit.

68.           CAIRO_FORMAT_RGB16_565_Deprecated_Do_Not_Use

69.           --  This value is deprecated

70.          );

71.        pragma Convention (C, Cairo_FormatTo API docTo spec);

73.        type Byte is range 0 .. 255;

75.        type ARGB32_Data is record

76.           Alpha : ByteTo API docTo spec;

77.           Red   : ByteTo API docTo spec;

78.           Green : ByteTo API docTo spec;

79.           Blue  : ByteTo API docTo spec;

80.        end record;

81.        --  One pixel in ARGB32 format

83.        type RGB24_Data is record

84.           Red   : ByteTo API docTo spec;

85.           Green : ByteTo API docTo spec;

86.           Blue  : ByteTo API docTo spec;

87.        end record;

88.        --  One pixel in RGB24 format

90.        type ARGB32_Array is array (Natural range <>) of ARGB32_DataTo API docTo spec;

91.        type ARGB32_Array_Access is access ARGB32_ArrayTo API docTo spec;

93.        type RGB24_Array is array (Natural range <>) of RGB24_DataTo API docTo spec;

94.        type RGB24_Array_Access is access RGB24_ArrayTo API docTo spec;

96.        type Byte_Array is array (Natural range <>) of ByteTo API docTo spec;

97.        type Byte_Array_Access is access Byte_ArrayTo API docTo spec;

99.        function CreateTo API docTo body

100.          (Format : Cairo_FormatTo API docTo spec;

101.           Width  : GintTo API docTo spec;

102.           Height : GintTo API docTo spec)

103.           return   Cairo_SurfaceTo API docTo spec;

104.        --  Format: Format of pixels in the surface to create

105.        --  Width: Width of the surface, in pixels

106.        --  Height: Height of the surface, in pixels

107.        --

108.        --  Creates an image surface of the specified format and

109.        --  dimensions. Initially the surface contents are all

110.        --  0. (Specifically, within each pixel, each color or alpha channel

111.        --  belonging to format will be 0. The contents of bits within a pixel,

112.        --  but not belonging to the given format are undefined).

113.        --

114.        --  Return value: a pointer to the newly created surface. The caller

115.        --  owns the surface and should call Cairo.Surface.Destroy when done

116.        --  with it.

117.        --

118.        --  This function always returns a valid pointer, but it will return a

119.        --  pointer to a "nil" surface if an error such as out of memory

120.        --  occurs. You can use Cairo.Surface.Status to check for this.

122.        function Cairo_Format_Stride_For_WidthTo API docTo body

123.          (Format : Cairo_FormatTo API docTo spec;

124.           Width  : GintTo API docTo spec)

125.           return   GintTo API docTo spec;

126.        --  Format: A Cairo_Format value

127.        --  Width: The desired Width of an image surface to be created.

128.        --

129.        --  This function provides a stride value that will respect all

130.        --  alignment requirements of the accelerated image-rendering code

131.        --  within cairo.

132.        --

133.        --  Return value: the appropriate stride to use given the desired

134.        --  format and width, or -1 if either the format is invalid or the width

135.        --  too large.

136.        --

137.        --  Since: 1.6

139.        function Create_For_Data_GenericTo API docTo body

140.          (Data   : System.Address;

141.           Format : Cairo_FormatTo API docTo spec;

142.           Width  : GintTo API docTo spec;

143.           Height : GintTo API docTo spec;

144.           Stride : GintTo API docTo spec)

145.           return   Cairo_SurfaceTo API docTo spec;

146.        --  Data: a pointer to a buffer supplied by the application in which

147.        --      to write contents. This pointer must be suitably aligned for any

148.        --      kind of variable, (for example, a pointer returned by malloc).

149.        --  Format: the Format of pixels in the buffer

150.        --  Width: the Width of the image to be stored in the buffer

151.        --  Height: the Height of the image to be stored in the buffer

152.        --  Stride: the number of bytes between the start of rows in the

153.        --      buffer as allocated. This value should always be computed by

154.        --      Cairo_Format_Stride_For_Width before allocating the data

155.        --      buffer.

156.        --

157.        --  This function is a low-level binding to the C function: see also

158.        --  Create_For_Data_[ARGB32|RGB24|A8|A1]

159.        --

160.        --  Creates an image surface for the provided pixel data. The output

161.        --  buffer must be kept around until the Cairo_Surface is destroyed

162.        --  or Cairo.Surface.Finish is called on the surface.  The initial

163.        --  contents of data will be used as the initial image contents; you

164.        --  must explicitly clear the buffer, using, for example,

165.        --  Cairo.Rectangle and Cairo.Fill if you want it cleared.

166.        --

167.        --  Note that the stride may be larger than Width*bytes_per_pixel to provide

168.        --  proper alignment for each pixel and row. This alignment is required to

169.        --  allow high-performance rendering within cairo. The correct way to obtain

170.        --  a legal stride value is to call Cairo_Format_Stride_For_Width with the

171.        --  desired format and maximum image width value, and the use the resulting

172.        --  stride value to allocate the data and to create the image surface. See

173.        --  Cairo_Format_Stride_For_Width for example code.

174.        --

175.        --  Return value: a pointer to the newly created surface. The caller

176.        --  owns the surface and should call Cairo.Surface.Destroy when done

177.        --  with it.

178.        --

179.        --  This function always returns a valid pointer, but it will return a

180.        --  pointer to a "nil" surface in the case of an error such as out of

181.        --  memory or an invalid stride value. In case of invalid stride value

182.        --  the error status of the returned surface will be

183.        --  Cairo_Status_Invalid_Stride.  You can use

184.        --  Cairo.Surface.Status to check for this.

185.        --

186.        --  See Cairo.Surface.Set_User_Data for a means of attaching a

187.        --  destroy-notification fallback to the surface if necessary.

189.        function Create_For_Data_ARGB32To API docTo body

190.          (Data   : ARGB32_Array_AccessTo API docTo spec;

191.           Width  : GintTo API docTo spec;

192.           Height : GintTo API docTo spec)

193.           return   Cairo_SurfaceTo API docTo spec;

194.        --  Same as above, working on ARGB32 format.

196.        function Create_For_Data_RGB24To API docTo body

197.          (Data   : RGB24_Array_AccessTo API docTo spec;

198.           Width  : GintTo API docTo spec;

199.           Height : GintTo API docTo spec)

200.           return   Cairo_SurfaceTo API docTo spec;

201.        --  Same as above, working on RGB24 format.

203.        function Create_For_Data_A8To API docTo body

204.          (Data   : Byte_Array_AccessTo API docTo spec;

205.           Width  : GintTo API docTo spec;

206.           Height : GintTo API docTo spec)

207.           return   Cairo_SurfaceTo API docTo spec;

208.        --  Same as above, working on A8 format.

210.        function Get_Data_GenericTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return System.Address;

211.        --  Surface: a Cairo_Image_Surface

212.        --

213.        --  Get a pointer to the data of the image surface, for direct

214.        --  inspection or modification.

215.        --

216.        --  Return value: a pointer to the image data of this surface or

217.        --  System.Null_Address if surface is not an image surface, or if

218.        --  Cairo.Surface.Finish has been called.

219.        --

220.        --  Since: 1.2

222.        function Get_FormatTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return Cairo_FormatTo API docTo spec;

223.        --  Surface: a Cairo_Image_Surface

224.        --

225.        --  Get the format of the surface.

226.        --

227.        --  Return value: the format of the surface

228.        --

229.        --  Since: 1.2

231.        function Get_WidthTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return GintTo API docTo spec;

232.        --  Surface: a Cairo_Image_Surface

233.        --

234.        --  Get the width of the image surface in pixels.

235.        --

236.        --  Return value: the width of the surface in pixels.

238.        function Get_HeightTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return GintTo API docTo spec;

239.        --  Surface: a Cairo_Image_Surface

240.        --

241.        --  Get the height of the image surface in pixels.

242.        --

243.        --  Return value: the height of the surface in pixels.

245.        function Get_StrideTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return GintTo API docTo spec;

246.        --  Surface: a Cairo_Image_Surface

247.        --

248.        --  Get the stride of the image surface in bytes

249.        --

250.        --  Return value: the stride of the image surface in bytes (or 0 if

251.        --  surface is not an image surface). The stride is the distance in

252.        --  bytes from the beginning of one row of the image data to the

253.        --  beginning of the next row.

254.        --

255.        --  Since: 1.2

257.     private

259.        for ByteTo API docTo spec'Size use 8;

261.        --  Representation working with all endiannesses

263.        BOP  : constant := System.Bit_Order'Pos (System.Default_Bit_Order);

264.        NBOP : constant := 1 - BOP;

266.        for ARGB32_DataTo API docTo spec use record

267.           Alpha at BOP * 3 + NBOP * 0 range 0 .. 7;

268.           Red   at BOP * 2 + NBOP * 1 range 0 .. 7;

269.           Green at BOP * 1 + NBOP * 2 range 0 .. 7;

270.           Blue  at BOP * 0 + NBOP * 3 range 0 .. 7;

271.        end record;

273.        for RGB24_DataTo API docTo spec use record

274.           Red   at BOP * 2 + NBOP * 1 range 0 .. 7;

275.           Green at BOP * 1 + NBOP * 2 range 0 .. 7;

276.           Blue  at BOP * 0 + NBOP * 3 range 0 .. 7;

277.        end record;

278.        for RGB24_DataTo API docTo spec'Size use 32;

280.        pragma Import (C, CreateTo API docTo spec, "cairo_image_surface_create");

281.        pragma Import

282.          (C, Cairo_Format_Stride_For_WidthTo API docTo spec, "cairo_format_stride_for_width");

284.        pragma Import

285.          (C, Create_For_Data_GenericTo API docTo spec, "cairo_image_surface_create_for_data");

287.        pragma Import (C, Get_Data_GenericTo API docTo spec, "cairo_image_surface_get_data");

288.        pragma Import (C, Get_FormatTo API docTo spec, "cairo_image_surface_get_format");

289.        pragma Import (C, Get_WidthTo API docTo spec, "cairo_image_surface_get_width");

290.        pragma Import (C, Get_HeightTo API docTo spec, "cairo_image_surface_get_height");

291.        pragma Import (C, Get_StrideTo API docTo spec, "cairo_image_surface_get_stride");

293.     end Cairo.Image_SurfaceTo API docTo specTo body;