diff options
Diffstat (limited to 'minilibx_beta/man')
| -rw-r--r-- | minilibx_beta/man/man3/mlx.3 | 110 | ||||
| -rw-r--r-- | minilibx_beta/man/man3/mlx_loop.3 | 144 | ||||
| -rw-r--r-- | minilibx_beta/man/man3/mlx_new_image.3 | 206 | ||||
| -rw-r--r-- | minilibx_beta/man/man3/mlx_new_window.3 | 79 | ||||
| -rw-r--r-- | minilibx_beta/man/man3/mlx_pixel_put.3 | 85 |
5 files changed, 624 insertions, 0 deletions
diff --git a/minilibx_beta/man/man3/mlx.3 b/minilibx_beta/man/man3/mlx.3 new file mode 100644 index 0000000..4c7e29b --- /dev/null +++ b/minilibx_beta/man/man3/mlx.3 @@ -0,0 +1,110 @@ +.TH MiniLibX 3 "September 19, 2002" +.SH NAME +MiniLibX - Simple Window Interface Library for students +.SH SYNOPSYS +#include <mlx.h> + +.nf +.I void * +.fi +.B mlx_init +(); + +.SH DESCRIPTION +MiniLibX is an easy way to create graphical software, +without any X-Window/X11 programming knowledge under Unix/Linux, nor +any AppKit programming knowledge under MacOS. It provides +simple window creation, a drawing tool, image and basic events +management. + +.SH Unix/Linux: X-WINDOW CONCEPT + +X-Window is a network-oriented graphical system for Unix. +It is based on two main parts: +.br +On one side, your software wants to draw something on the screen and/or +get keyboard & mouse entries. +.br +On the other side, the X-Server manages the screen, keyboard and mouse +(It is often refered to as a "display"). +.br +A network connection must be established between these two entities to send +drawing orders (from the software to the X-Server), and keyboard/mouse +events (from the X-Server to the software). +.br +Nowadays, most of the time, both run on the same computer. + +.SH MacOS: WINDOW SERVER AND GPU + +Your software interacts directly with the Window server who handles the +cohabitation on the screen with other software and the event system, +and interacts with the GPU to handle all drawing stuff. + +.SH INCLUDE FILE +.B mlx.h +should be included for a correct use of the MiniLibX API. +It only contains function prototypes, no structure is needed. + +.SH LIBRARY FUNCTIONS +.P +First of all, you need to initialize the connection +between your software and the display. +Once this connection is established, you'll be able to +use other MiniLibX functions to send and receive the messages from +the display, like "I want to draw a yellow pixel in this window" or +"did the user hit a key?". +.P +The +.B mlx_init +function will create this connection. No parameters are needed, ant it will +return a +.I "void *" +identifier, used for further calls to the library routines. +.P +All other MiniLibX functions are described in the following man pages: + +.TP 20 +.B mlx_new_window +: manage windows +.TP 20 +.B mlx_pixel_put +: draw inside window +.TP 20 +.B mlx_new_image +: manipulate images +.TP 20 +.B mlx_loop +: handle keyboard or mouse events + +.SH LINKING MiniLibX +To use MiniLibX functions, you may need to link +your software with several libraries, including the MiniLibX library itself. +On Unix/Linux, simply add the following arguments at linking time: + +.B -lmlx -lXext -lX11 + +On MacOS, the dynamic Metal library will find on its own the missing components: + +.B -lmlx + +and still on MacOS, the static OpenGL version will need: + +.B -lmlx -framework OpenGL -framework AppKit -lz + +You may also need to specify the path to these libraries, using +the +.B -L +flag. + + +.SH RETURN VALUES +If +.B mlx_init() +fails to set up the connection to the display, it will return NULL, otherwise +a non-null pointer is returned as a connection identifier. + +.SH SEE ALSO +mlx_new_window(3), mlx_pixel_put(3), mlx_new_image(3), mlx_loop(3) + +.SH AUTHOR +Copyright ol@ - 2002-2019 - Olivier Crouzet diff --git a/minilibx_beta/man/man3/mlx_loop.3 b/minilibx_beta/man/man3/mlx_loop.3 new file mode 100644 index 0000000..ab3798c --- /dev/null +++ b/minilibx_beta/man/man3/mlx_loop.3 @@ -0,0 +1,144 @@ +.TH MiniLibX 3 "September 19, 2002" +.SH NAME +MiniLibX - Handle events +.SH SYNOPSYS + +.nf +.I int +.fi +.B mlx_loop +( +.I void *mlx_ptr +); + +.nf +.I int +.fi +.B mlx_key_hook +( +.I void *win_ptr, int (*funct_ptr)(), void *param +); + +.nf +.I int +.fi +.B mlx_mouse_hook +( +.I void *win_ptr, int (*funct_ptr)(), void *param +); + +.nf +.I int +.fi +.B mlx_expose_hook +( +.I void *win_ptr, int (*funct_ptr)(), void *param +); + +.nf +.I int +.fi +.B mlx_loop_hook +( +.I void *mlx_ptr, int (*funct_ptr)(), void *param +); + +.SH EVENTS + +The graphical system is bi-directionnal. On one hand, the program sends orders to +the screen to display pixels, images, and so on. On the other hand, +it can get information from the keyboard and mouse associated to +the screen. To do so, the program receives "events" from the keyboard or the +mouse. + +.SH DESCRIPTION + +To receive events, you must use +.B mlx_loop +(). This function never returns. It is an infinite loop that waits for +an event, and then calls a user-defined function associated with this event. +A single parameter is needed, the connection identifier +.I mlx_ptr +(see the +.B mlx manual). + +You can assign different functions to the three following events: +.br +- A key is pressed +.br +- The mouse button is pressed +.br +- A part of the window should be re-drawn +(this is called an "expose" event, and it is your program's job to handle it in the +Unix/Linux X11 environment, but at the opposite it never happens on MacOS). +.br + +Each window can define a different function for the same event. + +The three functions +.B mlx_key_hook +(), +.B mlx_mouse_hook +() and +.B mlx_expose_hook +() work exactly the same way. +.I funct_ptr +is a pointer to the function you want to be called +when an event occurs. This assignment is specific to the window defined by the +.I win_ptr +identifier. The +.I param +adress will be passed to the function everytime it is called, and should be +used to store the parameters it might need. + +The syntax for the +.B mlx_loop_hook +() function is identical to the previous ones, but the given function will be +called when no event occurs. + +When it catches an event, the MiniLibX calls the corresponding function +with fixed parameters: +.nf + + expose_hook(void *param); + key_hook(int keycode, void *param); + mouse_hook(int button, int x, int y, void *param); + loop_hook(void *param); + +.fi +These function names are arbitrary. They here are used to distinguish +parameters according to the event. These functions are NOT part of the +MiniLibX. + +.I param +is the address specified in the mlx_*_hook calls. This address is never +used nor modified by the MiniLibX. On key and mouse events, additional +information is passed: +.I keycode +tells you which key is pressed (with X11, look for the include file "keysymdef.h", +with MacOS, just try :) ), +( +.I x +, +.I y +) are the coordinates of the mouse click in the window, and +.I button +tells you which mouse button was pressed. + +.SH GOING FURTHER WITH EVENTS +The MiniLibX provides a much generic access to other available events. The +.I mlx.h +include define +.B mlx_hook() +in the same manner mlx_*_hook functions work. The event and mask values +will be taken from the X11 include file "X.h". Some MacOS events are mapped +to these values, when it makes sense, and the mask is not used in MacOS. + +See source code of the MiniLibX to find out how it will +call your own function for a specific event. + +.SH SEE ALSO +mlx(3), mlx_new_window(3), mlx_pixel_put(3), mlx_new_image(3) + +.SH AUTHOR +Copyright ol@ - 2002-2019 - Olivier Crouzet diff --git a/minilibx_beta/man/man3/mlx_new_image.3 b/minilibx_beta/man/man3/mlx_new_image.3 new file mode 100644 index 0000000..ecea0ee --- /dev/null +++ b/minilibx_beta/man/man3/mlx_new_image.3 @@ -0,0 +1,206 @@ +.TH MiniLibX 3 "September 19, 2002" +.SH NAME +MiniLibX - Manipulating images +.SH SYNOPSYS + +.nf +.I void * +.fi +.B mlx_new_image +( +.I void *mlx_ptr, int width, int height +); + +.nf +.I char * +.fi +.B mlx_get_data_addr +( +.I void *img_ptr, int *bits_per_pixel, int *size_line, int *endian +); + +.nf +.I int +.fi +.B mlx_put_image_to_window +( +.I void *mlx_ptr, void *win_ptr, void *img_ptr, int x, int y +); + +.nf +.I unsigned int +.fi +.B mlx_get_color_value +( +.I void *mlx_ptr, int color +); + +.nf +.I void * +.fi +.B mlx_xpm_to_image +( +.I void *mlx_ptr, char **xpm_data, int *width, int *height +); + +.nf +.I void * +.fi +.B mlx_xpm_file_to_image +( +.I void *mlx_ptr, char *filename, int *width, int *height +); + +.nf +.I void * +.fi +.B mlx_png_file_to_image +( +.I void *mlx_ptr, char *filename, int *width, int *height +); + +.nf +.I int +.fi +.B mlx_destroy_image +( +.I void *mlx_ptr, void *img_ptr +); + + +.SH DESCRIPTION + +.B mlx_new_image +() creates a new image in memory. It returns a +.I void * +identifier needed to manipulate this image later. It only needs +the size of the image to be created, using the +.I width +and +.I height +parameters, and the +.I mlx_ptr +connection identifier (see the +.B mlx +manual). + +The user can draw inside the image (see below), and +can dump the image inside a specified window at any time to +display it on the screen. This is done using +.B mlx_put_image_to_window +(). Three identifiers are needed here, for the connection to the +display, the window to use, and the image (respectively +.I mlx_ptr +, +.I win_ptr +and +.I img_ptr +). The ( +.I x +, +.I y +) coordinates define where the image should be placed in the window. + +.B mlx_get_data_addr +() returns information about the created image, allowing a user +to modify it later. The +.I img_ptr +parameter specifies the image to use. The three next parameters should +be the addresses of three different valid integers. +.I bits_per_pixel +will be filled with the number of bits needed to represent a pixel color +(also called the depth of the image). +.I size_line +is the number of bytes used to store one line of the image in memory. +This information is needed to move from one line to another in the image. +.I endian +tells you wether the pixel color in the image needs to be stored in +little endian ( +.I endian +== 0), or big endian ( +.I endian +== 1). + +.B mlx_get_data_addr +returns a +.I char * +address that represents the begining of the memory area where the image +is stored. From this adress, the first +.I bits_per_pixel +bits represent the color of the first pixel in the first line of +the image. The second group of +.I bits_per_pixel +bits represent the second pixel of the first line, and so on. +Add +.I size_line +to the adress to get the begining of the second line. You can reach any +pixels of the image that way. + +.B mlx_destroy_image +destroys the given image ( +.I img_ptr +). + +.SH STORING COLOR INSIDE IMAGES + +Depending on the display, the number of bits used to store a pixel color +can change. The user usually represents a color in RGB mode, using +one byte for each component (see +.B mlx_pixel_put +manual). This must be translated to fit the +.I bits_per_pixel +requirement of the image, and make the color understandable to the display. +That is the purpose of the +.B mlx_get_color_value +() function. It takes a standard RGB +.I color +parameter, and returns an +.I unsigned int +value. +The +.I bits_per_pixel +least significant bits of this value can be stored in the image. You can +avoid using this function if there is no conversion needed (eg. in case of +24 bits depth, or 32 bits depth). + +Keep in mind that the least significant bits position depends on the local +computer's endian. If the endian of the image differs from the local endian +(which shoud only occurs in a X11 network environment), then the value should +be transformed before being used. + +.SH XPM AND PNG IMAGES + +The +.B mlx_xpm_to_image +() , +.B mlx_xpm_file_to_image +() and +.B mlx_png_file_to_image +() functions will create a new image the same way. +They will fill it using the specified +.I xpm_data +or +.I filename +, depending on which function is used. +Note that MiniLibX does not use the standard +Xpm and png libraries to deal with xpm and png images. You may not be able to +read all types of xpm and png images. It however handles transparency. + +.SH RETURN VALUES +The four functions that create images, +.B mlx_new_image() +, +.B mlx_xpm_to_image() +, +.B mlx_xpm_file_to_image() +and +.B mlx_png_file_to_image() +, will return NULL if an error occurs. Otherwise they return a non-null pointer +as an image identifier. + + +.SH SEE ALSO +mlx(3), mlx_new_window(3), mlx_pixel_put(3), mlx_loop(3) + +.SH AUTHOR +Copyright ol@ - 2002-2019 - Olivier Crouzet diff --git a/minilibx_beta/man/man3/mlx_new_window.3 b/minilibx_beta/man/man3/mlx_new_window.3 new file mode 100644 index 0000000..cdfc098 --- /dev/null +++ b/minilibx_beta/man/man3/mlx_new_window.3 @@ -0,0 +1,79 @@ +.TH MiniLibX 3 "September 19, 2002" +.SH NAME +MiniLibX - Managing windows +.SH SYNOPSYS + +.nf +.I void * +.fi +.B mlx_new_window +( +.I void *mlx_ptr, int size_x, int size_y, char *title +); + +.nf +.I int +.fi +.B mlx_clear_window +( +.I void *mlx_ptr, void *win_ptr +); + +.nf +.I int +.fi +.B mlx_destroy_window +( +.I void *mlx_ptr, void *win_ptr +); + + +.SH DESCRIPTION +The +.B mlx_new_window +() function creates a new window on the screen, using the +.I size_x +and +.I size_y +parameters to determine its size, and +.I title +as the text that should be displayed in the window's title bar. +The +.I mlx_ptr +parameter is the connection identifier returned by +.B mlx_init +() (see the +.B mlx +man page). +.B mlx_new_window +() returns a +.I void * +window identifier that can be used by other MiniLibX calls. +Note that the MiniLibX +can handle an arbitrary number of separate windows. + +.B mlx_clear_window +() and +.B mlx_destroy_window +() respectively clear (in black) and destroy the given window. They both have +the same parameters: +.I mlx_ptr +is the screen connection identifier, and +.I win_ptr +is a window identifier. + +.SH RETURN VALUES +If +.B mlx_new_window() +fails to create a new window (for wathever reason), it will return NULL, +otherwise a non-null pointer is returned as a window identifier. +.B mlx_clear_window +and +.B mlx_destroy_window +right now return nothing. + +.SH SEE ALSO +mlx(3), mlx_pixel_put(3), mlx_new_image(3), mlx_loop(3) + +.SH AUTHOR +Copyright ol@ - 2002-2019 - Olivier Crouzet diff --git a/minilibx_beta/man/man3/mlx_pixel_put.3 b/minilibx_beta/man/man3/mlx_pixel_put.3 new file mode 100644 index 0000000..52670a6 --- /dev/null +++ b/minilibx_beta/man/man3/mlx_pixel_put.3 @@ -0,0 +1,85 @@ +.TH MiniLibX 3 "September 19, 2002" +.SH NAME +MiniLibX - Drawing inside windows +.SH SYNOPSYS + +.nf +.I int +.fi +.B mlx_pixel_put +( +.I void *mlx_ptr, void *win_ptr, int x, int y, int color +); + +.nf +.I int +.fi +.B mlx_string_put +( +.I void *mlx_ptr, void *win_ptr, int x, int y, int color, char *string +); + + +.SH DESCRIPTION +The +.B mlx_pixel_put +() function draws a defined pixel in the window +.I win_ptr +using the ( +.I x +, +.I y +) coordinates, and the specified +.I color +\&. The origin (0,0) is the upper left corner of the window, the x and y axis +respectively pointing right and down. The connection +identifier, +.I mlx_ptr +, is needed (see the +.B mlx +man page). + +Parameters for +.B mlx_string_put +() have the same meaning. Instead of a simple pixel, the specified +.I string +will be displayed at ( +.I x +, +.I y +). + +Both functions will discard any display outside the window. This makes +.B mlx_pixel_put +slow. Consider using images instead. + +.SH COLOR MANAGEMENT +The +.I color +parameter has an integer type. The displayed color needs to be encoded +in this integer, following a defined scheme. All displayable colors +can be split in 3 basic colors: red, green and blue. Three associated +values, in the 0-255 range, represent how much of each color is mixed up +to create the original color. Theses three values must be set inside the +integer to display the right color. The three least significant bytes of +this integer are filled as shown in the picture below: + +.nf + | 0 | R | G | B | color integer + +---+---+---+---+ +.fi + + +While filling the integer, make sure you avoid endian problems. Remember +that the "blue" byte should always be the least significant one. + +Depending on hardware capabilities, the most significant bit can handle +transparency. Beware, at the opposite of the OpenGL classics, it does +not represent opacity. + +.SH SEE ALSO +mlx(3), mlx_new_window(3), mlx_new_image(3), mlx_loop(3) + + +.SH AUTHOR +Copyright ol@ - 2002-2019 - Olivier Crouzet |