1  .TH MiniLibX 3 "September 19, 2002"
  2  .SH NAME
  3  MiniLibX - Manipulating images
  4  .SH SYNOPSYS
  5  
  6  .nf
  7  .I void *
  8  .fi
  9  .B mlx_new_image
 10  (
 11  .I void *mlx_ptr, int width, int height
 12  );
 13  
 14  .nf
 15  .I char *
 16  .fi
 17  .B mlx_get_data_addr
 18  (
 19  .I void *img_ptr, int *bits_per_pixel, int *size_line, int *endian
 20  );
 21  
 22  .nf
 23  .I int
 24  .fi
 25  .B mlx_put_image_to_window
 26  (
 27  .I void *mlx_ptr, void *win_ptr, void *img_ptr, int x, int y
 28  );
 29  
 30  .nf
 31  .I unsigned int
 32  .fi
 33  .B mlx_get_color_value
 34  (
 35  .I void *mlx_ptr, int color
 36  );
 37  
 38  .nf
 39  .I void *
 40  .fi
 41  .B mlx_xpm_to_image
 42  (
 43  .I void *mlx_ptr, char **xpm_data, int *width, int *height
 44  );
 45  
 46  .nf
 47  .I void *
 48  .fi
 49  .B mlx_xpm_file_to_image
 50  (
 51  .I void *mlx_ptr, char *filename, int *width, int *height
 52  );
 53  
 54  .nf
 55  .I void *
 56  .fi
 57  .B mlx_png_file_to_image
 58  (
 59  .I void *mlx_ptr, char *filename, int *width, int *height
 60  );
 61  
 62  .nf
 63  .I int
 64  .fi
 65  .B mlx_destroy_image
 66  (
 67  .I void *mlx_ptr, void *img_ptr
 68  );
 69  
 70  
 71  .SH DESCRIPTION
 72  
 73  .B mlx_new_image
 74  () creates a new image in memory. It returns a
 75  .I void *
 76  identifier needed to manipulate this image later. It only needs
 77  the size of the image to be created, using the
 78  .I width
 79  and
 80  .I height
 81  parameters, and the
 82  .I mlx_ptr
 83  connection identifier (see the
 84  .B mlx
 85  manual).
 86  
 87  The user can draw inside the image (see below), and
 88  can dump the image inside a specified window at any time to
 89  display it on the screen. This is done using
 90  .B mlx_put_image_to_window
 91  (). Three identifiers are needed here, for the connection to the
 92  display, the window to use, and the image (respectively
 93  .I mlx_ptr
 94  ,
 95  .I win_ptr
 96  and
 97  .I img_ptr
 98  ). The (
 99  .I x
100  ,
101  .I y
102  ) coordinates define where the image should be placed in the window.
103  
104  .B mlx_get_data_addr
105  () returns information about the created image, allowing a user
106  to modify it later. The
107  .I img_ptr
108  parameter specifies the image to use. The three next parameters should
109  be the addresses of three different valid integers.
110  .I bits_per_pixel
111  will be filled with the number of bits needed to represent a pixel color
112  (also called the depth of the image).
113  .I size_line
114  is the number of bytes used to store one line of the image in memory.
115  This information is needed to move from one line to another in the image.
116  .I endian
117  tells you wether the pixel color in the image needs to be stored in
118  little endian (
119  .I endian
120  == 0), or big endian (
121  .I endian
122  == 1).
123  
124  .B mlx_get_data_addr
125  returns a
126  .I char *
127  address that represents the begining of the memory area where the image
128  is stored. From this adress, the first
129  .I bits_per_pixel
130  bits represent the color of the first pixel in the first line of
131  the image. The second group of
132  .I bits_per_pixel
133  bits represent the second pixel of the first line, and so on.
134  Add
135  .I size_line
136  to the adress to get the begining of the second line. You can reach any
137  pixels of the image that way.
138  
139  .B mlx_destroy_image
140  destroys the given image (
141  .I img_ptr
142  ).
143  
144  .SH STORING COLOR INSIDE IMAGES
145  
146  Depending on the display, the number of bits used to store a pixel color
147  can change. The user usually represents a color in RGB mode, using
148  one byte for each component (see
149  .B mlx_pixel_put
150  manual). This must be translated to fit the
151  .I bits_per_pixel
152  requirement of the image, and make the color understandable to the display.
153  That is the purpose of the
154  .B mlx_get_color_value
155  () function. It takes a standard RGB
156  .I color
157  parameter, and returns an
158  .I unsigned int
159  value.
160  The
161  .I bits_per_pixel
162  least significant bits of this value can be stored in the image. You can
163  avoid using this function if there is no conversion needed (eg. in case of
164  24 bits depth, or 32 bits depth).
165  
166  Keep in mind that the least significant bits position depends on the local
167  computer's endian. If the endian of the image differs from the local endian
168  (which shoud only occurs in a X11 network environment), then the value should
169  be transformed before being used.
170  
171  .SH XPM AND PNG IMAGES
172  
173  The
174  .B mlx_xpm_to_image
175  () ,
176  .B mlx_xpm_file_to_image
177  () and
178  .B mlx_png_file_to_image
179  () functions will create a new image the same way.
180  They will fill it using the specified
181  .I xpm_data
182  or
183  .I filename
184  , depending on which function is used.
185  Note that MiniLibX does not use the standard
186  Xpm and png libraries to deal with xpm and png images. You may not be able to
187  read all types of xpm and png images. It however handles transparency.
188  
189  .SH RETURN VALUES
190  The four functions that create images,
191  .B mlx_new_image()
192  ,
193  .B mlx_xpm_to_image()
194  ,
195  .B mlx_xpm_file_to_image()
196  and
197  .B mlx_png_file_to_image()
198  , will return NULL if an error occurs. Otherwise they return a non-null pointer
199  as an image identifier.
200  
201  
202  .SH SEE ALSO
203  mlx(3), mlx_new_window(3), mlx_pixel_put(3), mlx_loop(3)
204  
205  .SH AUTHOR
206  Copyright ol@ - 2002-2019 - Olivier Crouzet