MLX42 1.0
MLX42
|
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
Go to the source code of this file.
Data Structures | |
struct | mlx_texture |
struct | xpm |
struct | mlx_instance |
struct | mlx_key_data |
struct | mlx_image |
struct | mlx |
Variables | |
mlx_errno_t | mlx_errno |
MLX42 is a cross-platform low level and simple graphics library written in C and uses OpenGL and GLFW for it's underlying windowing and rendering system.
It's a much more up-to-date alternative to the miniLibX which has been extensively proven to be fragile, unmaintained, deprecated and just plain painfully bad to work with. Also its code quality is dubious.
Some structs contain potential void* which are to be ignored as they simply represent points of abstraction to the hidden internal header. This abstraction is crucial as the whole point of this lib so to hide all the bells and whistles in the "engine". Most user's have no need for the inner workings eitherway (shaders, vertex buffer, ...).
The input key codes are copied straight from GLFW. Any new entries should have the exact same values as defined in the glfw3.h. A key action such as pressing or releasing a key.
RELEASE | Execute when the key is being released. |
PRESS | Execute when the key is being pressed. |
REPEAT | Execute when the key is being held down. |
Various cursors that are standard.
ARROW | The regular arrow cursor. |
IBEAM | The text input I-beam cursor shape. |
CROSSHAIR | The crosshair shape cursor. |
HAND | The hand shape cursor. |
HRESIZE | The horizontal resize arrow shape. |
VRESIZE | The vertical resize arrow shape. |
An image with an individual buffer that can be rendered. Any value can be modified except the width/height and context.
width | The width of the image. |
height | The height of the image. |
pixels | The literal pixel data. |
instances | An instance carrying the X, Y and Z location data. |
count | The element count of the instances array. |
enabled | If true the image is drawn onto the screen, else it's not. |
context | Abstracted OpenGL data. |
An image instance can be summarized as just a simple x, y & z coordinate.
Coordinates start from the top left of the screen at 0,0 and increase towards the bottom right.
NOTE: To change the z value, use mlx_set_instance_depth!
x | The x location. |
y | The y location. |
z | The z depth, controls if the image is on the fore or background. |
enabled | If true, the instance is drawn, else it's not. |
Key function callback data. Data related to the mlx_key_hook function
key | The key that was pressed. |
action | The action that was done with the key. |
os_key | The os_key is unique for every key, and will have a different value/keycode depending on the platform. They may be consistent on different platforms. |
modifier | The modifier key that was pressed, 0 if no key was pressed. |
typedef void(* mlx_mousefunc) (mouse_key_t button, action_t action, modifier_key_t mods, void *param) |
Callback function used to handle mouse actions.
[in] | button | The mouse button/key pressed. |
[in] | action | The mouse action that took place. |
[in] | mods | The modifier keys pressed together with the mouse key. |
[in] | param | Additional parameter to pass on to the function. |
Callback function used to handle window resizing.
WARNING: The function is called every frame during which the window is being resized, be aware!
[in] | width | The new width of the window. |
[in] | height | The new height of the window. |
[in] | param | Additional parameter to pass on to the function. |
Main MLX handle, carries important data in regards to the program.
window | The window itself. |
context | Abstracted opengl data. |
width | The width of the window. |
height | The height of the window. |
delta_time | The time difference between the previous frame and the current frame. |
Base object for disk loaded textures. It contains rudementary information about the texture.
width | The width of the texture. |
height | The height of the texture. |
pixels | The literal pixel data. |
bytes_per_pixel | The amount of bytes in a pixel, always 4. |
Typedef for a window cursor object, these eventually expand to the native cursor object, but are hidden from the user.
Under GLFW they are named GLFWcursor and have a wrapper for each implementation. You can find the ACTUAL cursor in the following files at GLFW named under *_platform.h
Key modifiers, such as shift, control or alt. These keys are flags meaning you can combine them to detect key combinations such as CTRL + ALT so CTRL | ALT.
SHIFT | The shift key. |
CONTROL | The control key. |
ALT | The alt key. |
SUPERKEY | The Superkey such as the Windows Key or Command. |
CAPSLOCK | The capslock key. |
NUMLOCK | The numlock key. |
The mouse button keycodes.
LEFT | The left mouse button. |
RIGHT | The right mouse button. |
MIDDLE | The middle mouse button, aka the Scrollwheel. |
Various mouse/cursor states.
NORMAL | Simple visible default cursor. |
HIDDEN | The cursor is not rendered but still functions. |
DISABLED | The cursor is not rendered, nor is it functional. |
Struct containing data regarding an XPM image.
texture | The texture data of the XPM. |
color_count | The amount of colors available. |
cpp | The amount of characters per pixel. |
mode | The color mode, either (c)olor or (m)onochrome. |
MLX42 is a cross-platform low level and simple graphics library written in C and uses OpenGL and GLFW for it's underlying windowing and rendering system.
It's a much more up-to-date alternative to the miniLibX which has been extensively proven to be fragile, unmaintained, deprecated and just plain painfully bad to work with. Also its code quality is dubious.
Some structs contain potential void* which are to be ignored as they simply represent points of abstraction to the hidden internal header. This abstraction is crucial as the whole point of this lib so to hide all the bells and whistles in the "engine". Most user's have no need for the inner workings eitherway (shaders, vertex buffer, ...).
The input key codes are copied straight from GLFW. Any new entries should have the exact same values as defined in the glfw3.h. A key action such as pressing or releasing a key.
RELEASE | Execute when the key is being released. |
PRESS | Execute when the key is being pressed. |
REPEAT | Execute when the key is being held down. |
Enumerator | |
---|---|
MLX_RELEASE | |
MLX_PRESS | |
MLX_REPEAT |
Various cursors that are standard.
ARROW | The regular arrow cursor. |
IBEAM | The text input I-beam cursor shape. |
CROSSHAIR | The crosshair shape cursor. |
HAND | The hand shape cursor. |
HRESIZE | The horizontal resize arrow shape. |
VRESIZE | The vertical resize arrow shape. |
Enumerator | |
---|---|
MLX_CURSOR_ARROW | |
MLX_CURSOR_IBEAM | |
MLX_CURSOR_CROSSHAIR | |
MLX_CURSOR_HAND | |
MLX_CURSOR_HRESIZE | |
MLX_CURSOR_VRESIZE |
Definition at line 117 of file MLX42.h.
All sorts of keyboard keycodes.
KP = Keypad.
Definition at line 132 of file MLX42.h.
Enumerator | |
---|---|
MLX_STRETCH_IMAGE | |
MLX_FULLSCREEN | |
MLX_MAXIMIZED | |
MLX_DECORATED | |
MLX_HEADLESS | |
MLX_SETTINGS_MAX |
Definition at line 397 of file MLX42.h.
Key modifiers, such as shift, control or alt. These keys are flags meaning you can combine them to detect key combinations such as CTRL + ALT so CTRL | ALT.
SHIFT | The shift key. |
CONTROL | The control key. |
ALT | The alt key. |
SUPERKEY | The Superkey such as the Windows Key or Command. |
CAPSLOCK | The capslock key. |
NUMLOCK | The numlock key. |
Enumerator | |
---|---|
MLX_SHIFT | |
MLX_CONTROL | |
MLX_ALT | |
MLX_SUPERKEY | |
MLX_CAPSLOCK | |
MLX_NUMLOCK |
Definition at line 72 of file MLX42.h.
The mouse button keycodes.
LEFT | The left mouse button. |
RIGHT | The right mouse button. |
MIDDLE | The middle mouse button, aka the Scrollwheel. |
Enumerator | |
---|---|
MLX_MOUSE_BUTTON_LEFT | |
MLX_MOUSE_BUTTON_RIGHT | |
MLX_MOUSE_BUTTON_MIDDLE |
Definition at line 88 of file MLX42.h.
Various mouse/cursor states.
NORMAL | Simple visible default cursor. |
HIDDEN | The cursor is not rendered but still functions. |
DISABLED | The cursor is not rendered, nor is it functional. |
Enumerator | |
---|---|
MLX_MOUSE_NORMAL | |
MLX_MOUSE_HIDDEN | |
MLX_MOUSE_DISABLED |
Definition at line 101 of file MLX42.h.
void mlx_close_hook | ( | mlx_t * | mlx, |
mlx_closefunc | func, | ||
void * | param | ||
) |
This function sets the close callback, which is called in attempt to close the window device such as a close window widget used in the window bar.
[in] | mlx | The MLX instance handle. |
[in] | func | The close callback function. |
[in] | param | An additional optional parameter. |
Definition at line 63 of file mlx_window.c.
Notifies MLX that it should stop rendering and exit the main loop. This is not the same as terminate, this simply tells MLX to close the window.
[in] | mlx | The MLX instance handle. |
Definition at line 26 of file mlx_exit.c.
mlx_win_cursor_t * mlx_create_cursor | ( | mlx_texture_t * | texture | ) |
Allows for the creation of custom cursors with a given texture.
Use mlx_set_cursor to select the specific cursor. Cursors are destroyed at mlx_terminate().
[in] | texture | The texture to use as cursor. |
Definition at line 27 of file mlx_cursor.c.
mlx_win_cursor_t * mlx_create_std_cursor | ( | cursor_t | type | ) |
Retrieves the system standard cursor.
[in] | type | The standard cursor type to create. |
Definition at line 17 of file mlx_cursor.c.
void mlx_cursor_hook | ( | mlx_t * | mlx, |
mlx_cursorfunc | func, | ||
void * | param | ||
) |
This function sets the cursor callback, which is called when the mouse position changes. Position is relative to the window.
[in] | mlx | The MLX instance handle. |
[in] | func | The cursor callback function. |
[in] | param | An additional optional parameter. |
Definition at line 65 of file mlx_mouse.c.
void mlx_delete_image | ( | mlx_t * | mlx, |
mlx_image_t * | image | ||
) |
Deleting an image will remove it from the render queue as well as any and all instances it might have. Additionally, just as extra measures sets all the data to NULL.
If you simply wish to stop rendering an image without de-allocation set the 'enabled' boolean in the image struct.
[in] | mlx | The MLX instance handle. |
[in] | image | The image to delete. |
Definition at line 204 of file mlx_images.c.
void mlx_delete_texture | ( | mlx_texture_t * | texture | ) |
Deletes a texture by freeing its allocated data.
[in] | texture | The texture to free. |
Definition at line 37 of file mlx_texture.c.
Deletes an XPM42 texture by freeing its allocated data.
This will not remove any already drawn XPMs, it simply deletes the XPM buffer.
[in] | xpm | The xpm texture to delete. |
Definition at line 203 of file mlx_xpm42.c.
void mlx_destroy_cursor | ( | mlx_win_cursor_t * | cursor | ) |
Destroys the given cursor object.
[in] | cursor | The cursor object to destroy. |
Definition at line 43 of file mlx_cursor.c.
This function brings the specified window to front and sets input focus.
Do not use this function to steal focus from other applications unless you are certain that is what the user wants. Focus stealing can be extremely disruptive.
[in] | mlx | The MLX instance handle. |
Definition at line 126 of file mlx_utils.c.
const mlx_texture_t * mlx_get_font | ( | void | ) |
Retrieve the texture data for the built-in font.
Definition at line 46 of file mlx_font.c.
Gets the size of the specified monitor.
[in] | index | Normally 0, in case of multiple windows, can be specified |
[in] | width | The width of the window. |
[in] | height | The height of the window. |
Definition at line 17 of file mlx_monitor.c.
Returns the current, relative, mouse cursor position on the window, starting from the top left corner.
Negative values or values greater than window width or height indicate that it is outside the window.
[in] | mlx | The MLX instance handle. |
[out] | x | The position. |
[out] | y | The position. |
Definition at line 90 of file mlx_mouse.c.
This function lets you retrieve the X offset of the given char in the font texture.
NOTE: A single character is 10 * 20 in pixels!
[in] | c | The character to get the offset from. |
Definition at line 51 of file mlx_font.c.
Gets the elapsed time since MLX was initialized.
Definition at line 121 of file mlx_utils.c.
Gets the window's position.
[in] | mlx | The MLX instance handle. |
[out] | xpos | The x position. |
[out] | ypos | The y position. |
Definition at line 106 of file mlx_window.c.
int32_t mlx_image_to_window | ( | mlx_t * | mlx, |
mlx_image_t * | img, | ||
int32_t | x, | ||
int32_t | y | ||
) |
Draws a new instance of an image, it will then share the same pixel buffer as the image.
NOTE: Keep in mind that the instance array gets reallocated, try to store the return value to the instance! NOT the pointer! It will become invalid!
WARNING: Try to display as few images on the window as possible, drawing too many images will cause a loss in performance!
[in] | mlx | The MLX instance handle. |
[in] | img | The image to draw on the screen. |
[in] | x | The X position. |
[in] | y | The Y position. |
Definition at line 121 of file mlx_images.c.
Initializes a new MLX42 Instance.
[in] | width | The width of the window. |
[in] | height | The height of the window. |
[in] | title | The title of the window. |
[in] | resize | Enable window resizing. |
Definition at line 164 of file mlx_init.c.
Returns true or false if the key is down or not.
[in] | mlx | The MLX instance handle. |
[in] | key | The keycode to check, use MLX_KEY_... to specify! |
Definition at line 44 of file mlx_keys.c.
bool mlx_is_mouse_down | ( | mlx_t * | mlx, |
mouse_key_t | key | ||
) |
Checks whether a mouse button is pressed or not.
[in] | mlx | The MLX instance handle. |
[in] | key | A specific mouse key. e.g MLX_MOUSE_BUTTON_0 |
Definition at line 76 of file mlx_mouse.c.
void mlx_key_hook | ( | mlx_t * | mlx, |
mlx_keyfunc | func, | ||
void * | param | ||
) |
This function sets the key callback, which is called when a key is pressed on the keyboard. Useful for single keypress detection.
[in] | mlx | The MLX instance handle. |
[in] | func | The keypress callback function. |
[in] | param | An additional optional parameter. |
Definition at line 33 of file mlx_keys.c.
mlx_texture_t * mlx_load_png | ( | const char * | path | ) |
Decode/load a PNG file into a buffer.
[in] | path | Path to the PNG file. |
Definition at line 17 of file mlx_png.c.
Loads an XPM42 texture from the given file path.
[in] | path | The file path to the XPM texture. |
Definition at line 181 of file mlx_xpm42.c.
Initializes the rendering of MLX, this function won't return until mlx_close_window is called, meaning it will loop until the user requests that the window should close.
[in] | mlx | The MLX instance handle. |
In Emscripten the lood is defined differently, there the this function is passed to the while loop instead
Definition at line 97 of file mlx_loop.c.
Generic loop hook for any custom hooks to add to the main loop. Executes a function per frame, so be careful.
[in] | mlx | The MLX instance handle. |
[in] | f | The function. |
[in] | param | The parameter to pass on to the function. |
Definition at line 70 of file mlx_loop.c.
void mlx_mouse_hook | ( | mlx_t * | mlx, |
mlx_mousefunc | func, | ||
void * | param | ||
) |
This function sets the mouse callback, which is called when a mouse does any sort of action such as pressing a key.
[in] | mlx | The MLX instance handle. |
[in] | func | The mouse callback function. |
[in] | param | An additional optional parameter. |
Definition at line 54 of file mlx_mouse.c.
mlx_image_t * mlx_new_image | ( | mlx_t * | mlx, |
uint32_t | width, | ||
uint32_t | height | ||
) |
Creates and allocates a new image buffer.
[in] | mlx | The MLX instance handle. |
[in] | width | The desired width of the image. |
[in] | height | The desired height of the image. |
Definition at line 161 of file mlx_images.c.
void mlx_put_pixel | ( | mlx_image_t * | image, |
uint32_t | x, | ||
uint32_t | y, | ||
uint32_t | color | ||
) |
Sets / puts a pixel onto an image.
NOTE: It is considered undefined behaviour when putting a pixel beyond the bounds of an image.
[in] | image | The MLX instance handle. |
[in] | x | The X coordinate position. |
[in] | y | The Y coordinate position. |
[in] | color | The color value to put. |
Definition at line 26 of file mlx_put_pixel.c.
Draws a string on an image and then outputs it to the window.
[in] | mlx | The MLX instance handle. |
[in] | str | The string to draw. |
[in] | x | The X location. |
[in] | y | The Y location. |
Definition at line 60 of file mlx_font.c.
void mlx_resize_hook | ( | mlx_t * | mlx, |
mlx_resizefunc | func, | ||
void * | param | ||
) |
This function sets the resize callback, which is called when the window is resized
[in] | mlx | The MLX instance handle. |
[in] | func | The resize callback function. |
[in] | param | An additional optional parameter. |
Definition at line 74 of file mlx_window.c.
bool mlx_resize_image | ( | mlx_image_t * | img, |
uint32_t | nwidth, | ||
uint32_t | nheight | ||
) |
Allows you to resize an image, a new pixel buffer is allocated to fit & the previous data is scaled to fit the new size.
[in] | img | The image to resize. |
[in] | nwidth | The new width. |
[in] | nheight | The new height. |
Definition at line 224 of file mlx_images.c.
void mlx_scroll_hook | ( | mlx_t * | mlx, |
mlx_scrollfunc | func, | ||
void * | param | ||
) |
This function sets the scroll callback, which is called when a scrolling device is used, such as a mouse wheel.
[in] | mlx | The MLX instance handle. |
[in] | func | The scroll wheel callback function. |
[in] | param | An additional optional parameter. |
Definition at line 43 of file mlx_mouse.c.
void mlx_set_cursor | ( | mlx_t * | mlx, |
mlx_win_cursor_t * | cursor | ||
) |
Sets the current cursor to the given custom cursor.
[in] | mlx | The MLX instance handle. |
[in] | cursor | The cursor object to display, if null default cursor is selected. |
Definition at line 50 of file mlx_cursor.c.
void mlx_set_cursor_mode | ( | mlx_t * | mlx, |
mouse_mode_t | mode | ||
) |
Defines the state for the cursor.
[in] | mlx | The MLX instance handle. |
[in] | mode | A specified mouse mode. |
Definition at line 58 of file mlx_cursor.c.
void mlx_set_icon | ( | mlx_t * | mlx, |
mlx_texture_t * | image | ||
) |
Lets you set a custom image as the program icon.
NOTE: In MacOS this function does nothing, you should use the bundles icon to set the dock bar icon.
[in] | mlx | The MLX instance handle. |
[in] | image | The image to use as icon. |
Definition at line 85 of file mlx_window.c.
void mlx_set_instance_depth | ( | mlx_instance_t * | instance, |
int32_t | zdepth | ||
) |
Sets the depth / Z axis value of an instance.
NOTE: Keep in mind that images that are on the same Z layer cut each other off. so if you don't see your image anymore make sure it's not conflicting by being on the same layer as another image.
[in] | instance | The instance on which to change the depth. |
[in] | zdepth | The new depth value. |
NOTE: The reason why we don't sort directly is that the user might call this function multiple times in a row and we don't want to sort for every change. Pre-loop wise that is.
Definition at line 105 of file mlx_images.c.
Sets the mouse position.
[in] | mlx | The MLX instance handle. |
[in] | pos | The position. |
Definition at line 83 of file mlx_mouse.c.
void mlx_set_setting | ( | mlx_settings_t | setting, |
int32_t | value | ||
) |
Set a setting for MLX42. Settings can manipulate the core behaviour of the engine.
[in] | setting | The settings value, See mlx_settings_t type. |
[in] | value | Settings value to determine the state of the setting. Can be a boolean or an enum / macro. |
Definition at line 213 of file mlx_init.c.
void mlx_set_window_limit | ( | mlx_t * | mlx, |
int32_t | min_w, | ||
int32_t | min_h, | ||
int32_t | max_w, | ||
int32_t | max_h | ||
) |
Sets the size limits of the specified window. Will force the window to not be resizable past or below the given values.
Pass -1 for no limit to any of the min/max parameters to ignore that boundary. For instance if you want a min window size but the max window size can be whatever.
[in] | mlx | The MLX instance handle. |
[in] | min_w | The min width of the window. |
[in] | max_w | The max width of the window. |
[in] | min_h | The min height of the window. |
[in] | max_h | The max height of the window. |
Definition at line 124 of file mlx_window.c.
Sets the window's position.
Do not use this function to move an already visible window unless you have very good reasons for doing so, as it will confuse and annoy the user.
[in] | mlx | The MLX instance handle. |
[in] | xpos | The x position. |
[in] | ypos | The y position. |
Definition at line 99 of file mlx_window.c.
Changes the window size to the newly specified values. Use this to update the window width and height values in the mlx handle.
[in] | mlx | The MLX instance handle. |
[in] | new_width | The new desired width. |
[in] | new_height | The new desired height. |
Definition at line 115 of file mlx_window.c.
Sets the title of the window.
[in] | mlx | The MLX instance handle. |
[in] | title | The window title. |
Definition at line 131 of file mlx_window.c.
const char * mlx_strerror | ( | mlx_errno_t | val | ) |
Gets the english description of the error code.
[in] | val | The error code. |
Definition at line 54 of file mlx_error.c.
Terminates MLX and cleans up any of its used resources. Using any functions that require mlx afterwards will be considered undefined behaviour, beware of segfaults.
[in] | mlx | The MLX instance handle. |
All of glfw & glads resources are cleaned up by the terminate function. Now it's time to clean up our own mess.
Definition at line 36 of file mlx_exit.c.
mlx_image_t * mlx_texture_to_image | ( | mlx_t * | mlx, |
mlx_texture_t * | texture | ||
) |
Converts a given texture to an image.
[in] | mlx | The MLX instance handle. |
[in] | texture | The texture to use to create the image from. |
Definition at line 17 of file mlx_texture.c.
|
extern |
Definition at line 161 of file mlx_init.c.