Mercurial > molko
changeset 569:e13d79a14791
man: remove for now
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 09 Mar 2023 13:48:08 +0100 |
parents | 2b2844ab4e6b |
children | aaf518c87628 |
files | man/mlk-action.3 man/mlk-alloc.3 man/mlk-err.3 man/mlk_action_draw.3 man/mlk_action_end.3 man/mlk_action_finish.3 man/mlk_action_handle.3 man/mlk_action_start.3 man/mlk_action_update.3 man/mlk_alloc_array.3 man/mlk_alloc_new.3 man/mlk_alloc_set.3 man/mlk_err_string.3 |
diffstat | 13 files changed, 0 insertions(+), 697 deletions(-) [+] |
line wrap: on
line diff
--- a/man/mlk-action.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,85 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK-ACTION 3 -.Os -.Sh NAME -.Nm mlk-action -.Nd generic in game actions -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Sh DESCRIPTION -Generic updatable and drawable actions. -.Pp -This module help creating user interaction within the gameplay by adding -actions. They have the following properties: -.Pp -.Bl -dash -compact -.It -Can handle user input and events, -.It -Can be updated through the game loop, -.It -Can be drawn. -.El -.Pp -Most more high level objects can handle actions to add flexibility (like in -battles, maps, etc). -.Pp -This header defines the -.Vt "struct mlk_action" : -.Bd -literal -struct mlk_action { - void *data; - void (*start)(struct mlk_action *self); - void (*handle)(struct mlk_action *self, const union mlk_event *ev); - int (*update)(struct mlk_action *self, unsigned int ticks); - void (*draw)(struct mlk_action *self); - void (*end)(struct mlk_action *self); - void (*finish)(struct mlk_action *self); -}; -.Ed -.Pp -Each member function takes the original action as first argument and other -arguments after. Its fields are: -.Bl -tag -.It Va data -Optional user data. -.It Va start -This function is called when the action is going to start. User can set a -function to prepare the action especially in a sequence (see -.Xr mlk-action-script 3 -for example). -.It Va handle -Handle the event -.Fa ev . -.It Va update -Update the action with the -.Fa ticks -since last frame expressed as milliseconds. The callback should return non-zero -if it is considered complete. -.It Va draw -Draw the action. -.It Va end -Called when the action was completed. -.Pp -This callback is mostly provided to allow the user doing something else once an -action is complete. Predefined actions from the framework should not use this -callback by themselves. -.It Va finish -Destroy internal resources for this action. -.Pp -Close the action before removal. This function should be used to deallocate -memory if necessary. -.El -.Sh SEE ALSO -.Xr mlk_action_draw 3 , -.Xr mlk_action_end 3 , -.Xr mlk_action_finish 3 , -.Xr mlk_action_handle 3 , -.Xr mlk_action_update 3 -.Sh AUTHORS -The -.Nm -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk-alloc.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,248 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK-ALLOC 3 -.Os -.Sh NAME -.Nm mlk-alloc -.Nd allocation routines -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/alloc.h -.Ft void * -.Fn mlk_alloc_dup "const void *ptr" "size_t size" -.Ft char * -.Fn mlk_alloc_sdup "const char *src" -.Ft char * -.Fn mlk_alloc_sdupf "const char *fmt" ... -.Ft void -.Fn mlk_alloc_free "void *ptr" -.Ft void -.Fn mlk_alloc_pool_init "struct mlk_alloc_pool *pool" "size_t elemsize" "void (*finalizer)(void *)" -.Ft void * -.Fn mlk_alloc_pool_new "struct mlk_alloc_pool *pool" -.Ft void * -.Fn mlk_alloc_pool_get "const struct mlk_alloc_pool *pool, size_t index" -.Ft void * -.Fn mlk_alloc_pool_shrink "struct mlk_alloc_pool *pool" -.Ft void -.Fn mlk_alloc_pool_finish "struct mlk_alloc_pool *pool" -.Sh DESCRIPTION -The allocation strategy in the mlk framework is to call -.Xr mlk-panic 3 -in case of memory exhaustion. It is designed in mind that recovering of lack of -memory in a game is usually impossible. However, the user can still change the -allocation functions to perform custom actions but it should be noted that mlk -framework don't except any of the function to return NULL in case of memory -exhaustion. -.Pp -The user should use its own functions when memory exhaustion has to be tested. -.Pp -The -.Vt "struct mlk_alloc_funcs" -type is defined as: -.Bd -literal -struct mlk_alloc_funcs { - void *(*alloc)(size_t size); - void *(*realloc)(void *ptr, size_t newsize); - void (*free)(void *ptr); -}; -.Pp -.Ed -Its fields are defined as following: -.Bl -tag -.It Va alloc -This function is called to allocate new memory, it takes the memory -.Fa size -as argument and must return a non-NULL value. -.It Va realloc -This function must reallocate the memory region pointed by -.Fa ptr -with its new size given by -.Fa newsize . -The original -.Fa ptr -may be NULL. The function must not return a non-NULL value. -.It Va free -This function must free the pointer specified by -.Fa ptr . -.El -.Pp -The -.Vt "struct mlk_alloc_pool" -type is defined as: -.Bd -literal -struct mlk_alloc_pool { - void *data; - size_t elemsize; - size_t size; - size_t capacity; - void (*finalizer)(void *); -}; -.Ed -.Pp -Its fields are defined as following: -.Bl -tag -.It Va data -Pointer to the memory region. -.It Va elemsize -Size of individual element. -.It Va size -Number of items in array. -.It Va capacity -Current capacity which may be greater or equal to -.Va size . -.It Va finalizer -Optional finalizer function that should finalize the object pointed by -.Va data -for every element. This function is only called when the -.Fn mlk_alloc_pool_finish -function is used. -.El -.Pp -The -.Fn mlk_alloc_dup -function duplicates the pointer -.Fa ptr -with the given -.Fa size . -.Pp -The -.Fn mlk_alloc_sdup -function duplicates the string -.Fa src -and return it. -.Pp -The -.Fn mlk_alloc_sdupf -function creates a dynamically allocated string using printf(3) format like. -.Pp -the -.Fn mlk_alloc_free -function releases memory previously allocated. It must always be used instead of -C standard -.Xr free 3 -function if any function of this module was used to allocates the -.Fa ptr -memory region. -.Pp -The following functions can be used to increase a dynamically allocated array -automatically. It allocates twice as the current storage when size exceeds -capacity. -.Pp -It uses realloc mechanism to upgrade the new storage space so pointers returned -in -.Fn mlk_alloc_pool_new -may get invalided when this function is called. -.Pp -It is designed in mind to help allocating an array of elements when they can't -be determined at runtime (e.g. while reading a file) without the performance -cost of using -.Fn mlk_alloc_rearray -for every elements. -.Pp -The initial capacity is controlled by the -.Dv MLK_ALLOC_POOL_INIT_DEFAULT -macro and -.Em must -be a power of two. -.Pp -A custom finalizer function can be set to finalize each individual object if -necessary. -.Pp -The -.Fn mlk_alloc_pool_init -function initializes the -.Fa pool -as an array where elements have -.Fa elemsize -size. Optional -.Fa finalizer -argument can be passed to finalize every element when clearing the pool. This -will effectively create a initial storage according to -.Dv MLK_ALLOC_POOL_INIT_DEFAULT -value. -.Pp -The -.Fn mlk_alloc_pool_new -function requests a new slot from the -.Fa pool -and return it. If the current size has reached the capacity, it will be doubled -in that case it is possible that all previous pointer may be invalidated. -.Pp -The -.Fn mlk_alloc_pool_get -function returns the value at the given -.Fa index -from the -.Fa pool . -.Pp -The -.Fn mlk_alloc_pool_shrink -function shrink the -.Fa pool -data to the exact number of elements in the array and return the memory region -which user takes full ownership. Once returned data is no longer needed, it must -be released with -.Fn mlk_alloc_free . -.Pp -The pool is emptied and must be reinitialized using -.Fn mlk_alloc_pool_init -before reusing it. It is not necessary to call -.Fn mlk_alloc_pool_finish -but doing so is just no-op. -.Pp -The -.Fn mlk_alloc_pool_finish -function finalizes the -.Fa pool -and all individual elements if a finalizer was set. You must call -.Fn mlk_alloc_pool_init -again before reusing it. -.Sh EXAMPLES -.Ss Use a mlk_alloc_pool to increase an array while reading a file. -.Bd -literal -/* A structure defined line by line inside a file in the form "x|y" */ -struct point { - int x; - int y; -}; - -struct mlk_alloc_pool pool; -struct point *point, *points; -size_t pointsz; -int x, y; - -mlk_alloc_pool_init(&pool, sizeof (*point), NULL); - -/* Assume fp is a FILE pointer allocated by the user. */ -while (fscanf(fp, "%d|%d\\n", &x, &y) == 2) { - /* - * Returned pointer can be used to fill the region but must not be - * permanently referenced as it can get invalidated in the next - * iteration. - */ - point = mlk_alloc_pool_new(&pool); - point->x = x; - point->y = y; -} - -/* - * Shrink the data into the appropriate array length. The pool can be safely - * discarded. - */ -pointsz = pool.size; -points = mlk_alloc_pool_shrink(&pool); - -for (size_t i = 0; i < pointsz; ++i) - point_draw(&points[i]); -.Ed -.Sh SEE ALSO -.Xr mlk-panic 3 , -.Xr mlk_alloc_array.3 , -.Xr mlk_alloc_new.3 , -.Xr mlk_alloc_set.3 -.Sh AUTHORS -The -.Nm -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk-err.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK-ERR 3 -.Os -.Sh NAME -.Nm mlk-err -.Nd error management in mlk library -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/err.h -.Sh DESCRIPTION -This manual page describes error codes that may occur within the molko -framework. All errors are defined with negative numbers, the only exception -being -.Er MLK_ERR_NONE -which is equal to 0. -.Pp -The following macro constants are defined: -.Bl -tag -width Ds -.It Er MLK_ERR_NONE -Equal to 0, no error. -.It Er MLK_ERR_NO_MEM -No more memory available. -.It Er MLK_ERR_NO_SUPPORT -The file format or function is not supported. -.It Er MLK_ERR_FORMAT -The file is corrupt or invalid. -.El -.Pp -There are other private error codes that are internal to the framework and not -listed as they may change over time, if the caller inspects individual error -codes it should also be took in account which in this case the function -.Fn mlk_err_string -may comes handy. -.Sh SEE ALSO -.Xr mlk_err_string 3 -.Sh AUTHORS -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_action_draw.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,23 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ACTION_DRAW 3 -.Os -.Sh NAME -.Nm mlk_action_draw -.Nd draw an action -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Ft void -.Fn mlk_action_draw "struct mlk_action *self" -.Sh DESCRIPTION -Invoke the draw callback on the action -.Fa self -if it is not null. -.Sh SEE ALSO -.Xr mlk-action 3 -.Sh AUTHORS -The -.Nm -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_action_end.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,25 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ACTION_END 3 -.Os -.Sh NAME -.Nm mlk_action_end -.Nd terminate an action -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Ft void -.Fn mlk_action_end "struct mlk_action *self" -.Sh DESCRIPTION -Invoke the -.Va end -callback on the action -.Fa self -if it is not null. -.Sh SEE ALSO -.Xr mlk-action 3 -.Sh AUTHORS -The -.Nm mlk-core -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_action_finish.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,25 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ACTION_FINISH 3 -.Os -.Sh NAME -.Nm mlk_action_finish -.Nd cleanup action resources -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Ft void -.Fn mlk_action_finish "struct mlk_action *self" -.Sh DESCRIPTION -Invoke the -.Va finish -callback on the action -.Fa self -if it is not null. -.Sh SEE ALSO -.Xr mlk-action 3 -.Sh AUTHORS -The -.Nm mlk-core -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_action_handle.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,26 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ACTION_HANDLE 3 -.Os -.Sh NAME -.Nm mlk_action_handle -.Nd handle an event -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Ft void -.Fn mlk_action_handle "struct mlk_action *self, const union mlk_event *ev" -.Sh DESCRIPTION -Invoke the -.Va handle -callback on the action -.Fa self -if it is not null with the event -.Fa ev -.Sh SEE ALSO -.Xr mlk-action 3 -.Sh AUTHORS -The -.Nm mlk-core -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_action_start.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,23 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ACTION_START 3 -.Os -.Sh NAME -.Nm mlk_action_start -.Nd start an action -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Ft void -.Fn mlk_action_start "struct mlk_action *self" -.Sh DESCRIPTION -Invoke the start callback on the action -.Fa self -if it is not null. -.Sh SEE ALSO -.Xr mlk-action 3 -.Sh AUTHORS -The -.Nm -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_action_update.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ACTION_UPDATE 3 -.Os -.Sh NAME -.Nm mlk_action_update -.Nd update an action -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/action.h -.Ft void -.Fn mlk_action_update "struct mlk_action *self, unsigned int ticks" -.Sh DESCRIPTION -Invoke the update callback on the action -.Fa self -if it is not null. -.Sh RETURN VALUES -The functions return the same value as the -.Va update -callback from the action and it should be non-zero if the action is considered -complete. -.Sh SEE ALSO -.Xr mlk-action 3 -.Sh AUTHORS -The -.Nm mlk-core -library was written by -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_alloc_array.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,65 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ALLOC_ARRAY 3 -.Os -.Sh NAME -.Nm mlk_alloc_array , -.Nm mlk_alloc_array0 , -.Nm mlk_alloc_rearray , -.Nm mlk_alloc_rearray0 -.Nd safe array allocation -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/alloc.h -.Ft void * -.Fn mlk_alloc_array "size_t len, size_t elemsize" -.Ft void * -.Fn mlk_alloc_array0 "size_t len, size_t elemsize" -.Ft void * -.Fn mlk_alloc_rearray "void *ptr, size_t newlen, size_t elemsize" -.Ft void * -.Fn mlk_alloc_rearray0 "void *ptr, size_t oldlen, size_t newlen, size_t elemsize" -.Sh DESCRIPTION -These functions are designed to safely allocate arrays. They take an amount of -objects to allocate and their individual sizes, the function ensuress that the -multiplication does not overflow. -.Pp -The -.Fn mlk_alloc_array -and -.Fn mlk_alloc_array0 -functions allocate an array of -.Fa len -elements of -.Fa elemsize -individually. -The -.Fn mlk_alloc_array0 -variant ensure the data is being zero-initialized. -.Pp -The -.Fn mlk_alloc_rearray -function reallocates the pointer -.Fa ptr -(which may be NULL) as an array of -.Fa newlen -elements of -.Fa elemsize -individually. -.Pp -The -.Fn mlk_alloc_rearray0 -function is similar to -.Fn mlk_alloc_rearray -but zero-initialize the memory. It needs the previous length given in -.Fa oldlen -argument because the function would not know which memory region to zero -initialize when increasing the memory. -.Sh RETURN VALUES -All functions return a pointer to the memory according to the current -allocation strategy. -.Sh SEE ALSO -.Xr mlk-alloc 3 , -.Xr mlk_alloc_set 3 -.Sh AUTHORS -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_alloc_new.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,56 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ALLOC_NEW 3 -.Os -.Sh NAME -.Nm mlk_alloc_new , -.Nm mlk_alloc_new0 , -.Nm mlk_alloc_renew , -.Nm mlk_alloc_renew0 -.Nd allocate memory -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/alloc.h -.Ft void * -.Fn mlk_alloc_new "size_t size" -.Ft void * -.Fn mlk_alloc_new0 "size_t size" -.Ft void * -.Fn mlk_alloc_renew "void *ptr, size_t size" -.Ft void * -.Fn mlk_alloc_renew0 "void *ptr, size_t oldsize, size_t newsize" -.Sh DESCRIPTION -.Pp -The -.Fn mlk_alloc_new -and -.Fn mlk_alloc_new0 -functions allocate memory data of the given -.Fa size . -The -.Fn mlk_alloc_new0 -variant ensure the data is being zero-initialized. -.Pp -The -.Fn mlk_alloc_renew -function reallocates the pointer -.Fa ptr -according to its -.Fa size . -.Pp -The -.Fn mlk_alloc_renew0 -function is similar to -.Fn mlk_alloc_renew -but zero-initialize the memory. It needs the previous size given in -.Fa oldsize -argument because the function would not know which memory region to zero -initialize when increasing the memory. -.Sh RETURN VALUES -All functions return a pointer to the memory according to the current -allocation strategy. -.Sh SEE ALSO -.Xr mlk-alloc 3 , -.Xr mlk_alloc_set 3 -.Sh AUTHORS -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_alloc_set.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ALLOC_SET 3 -.Os -.Sh NAME -.Nm mlk_alloc_set -.Nd allocation routines -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/alloc.h -.Ft void -.Fn mlk_alloc_set "const struct mlk_alloc_funcs *funcs" -.Sh DESCRIPTION -Change allocation routines for the entire framework and its underlying -libraries. -.Pp -The -.Fn mlk_alloc_set -function changes allocator functions to -.Fa funcs -allocator routines. It must be kept valid until the program is no longer used. -See the -.Xr mlk-alloc 3 -manual page for the -.Vt mlk_alloc_funcs -type definition. -.Sh SEE ALSO -.Xr mlk-alloc 3 -.Sh AUTHORS -.An David Demelier Aq Mt markand@malikania.fr .
--- a/man/mlk_err_string.3 Wed Mar 08 21:30:32 2023 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,25 +0,0 @@ -.Dd $Mdocdate$ -.Dt MLK_ERR_STRING 3 -.Os -.Sh NAME -.Nm mlk_err_string -.Nd return human readable error string -.Sh LIBRARY -libmlk-core (-lmlk-core) -.Sh SYNOPSIS -.In mlk/core/err.h -.Ft "const char *" -.Fn mlk_err_string "int e" -.Sh DESCRIPTION -The function -.Fn mlk_err_string -returns a constant string description of the error code -.Fa e . -.Pp -See the -.Xr mlk-err 3 -manual page for a list of error codes. -.Sh SEE ALSO -.Xr mlk-err 3 -.Sh AUTHORS -.An David Demelier Aq Mt markand@malikania.fr .