mirror of
https://github.com/wiiu-env/wut.git
synced 2025-01-06 02:08:22 +01:00
include/proc_ui: Polish off most of the Doxygen documentation
This might not be 100% accurate, feel free to update and overwrite and whatever.
This commit is contained in:
Ash
parent
c2df6eab3b
commit
b37c405af8
@ -4,6 +4,35 @@
|
||||
/**
|
||||
* \defgroup proc_ui_procui ProcUI
|
||||
* \ingroup proc_ui
|
||||
*
|
||||
* The ProcUI group of functions provide an interface to manage transitions
|
||||
* between the different states of an application.
|
||||
*
|
||||
* After calling ProcUIInit() or ProcUIInitEx(), an application may call
|
||||
* ProcUIProcessMessages() to process and update its state. These states may
|
||||
* include:
|
||||
* - #PROCUI_STATUS_IN_FOREGROUND - The default state of an application. All
|
||||
* system resources and hardware is available, and the application runs
|
||||
* without any serious restrictions.
|
||||
* - #PROCUI_STATUS_IN_BACKGROUND - When the user instructs the OS to switch
|
||||
* to a secondary application (HOME menu overlay, Internet Browser, etc.) the
|
||||
* application enters this background state. Background applications are
|
||||
* heavily restricted - they get a small amount of CPU time on core 2 (all
|
||||
* other threads are suspended), access to filesystems, and some network IO.
|
||||
* They have no access to graphics, inputs or user interaction of any kind.
|
||||
* - #PROCUI_STATUS_RELEASE_FOREGROUND - The user has requested a foreground
|
||||
* switch. The current application must release all foreground-only resources,
|
||||
* calling ProcUIDrawDoneRelease() when it's ready to go into the background.
|
||||
* - #PROCUI_STATUS_EXITING - The application must release all resources, call
|
||||
* ProcUIShutdown(), and exit.
|
||||
*
|
||||
* An application can determine its state by either examining
|
||||
* ProcUIProcessMessages()'s return value, or using callbacks via
|
||||
* ProcUIRegisterCallback().
|
||||
*
|
||||
* \if false
|
||||
* todo: flesh out exactly what is/isn't allowed in background
|
||||
* \endif
|
||||
* @{
|
||||
*/
|
||||
|
||||
@ -28,34 +57,96 @@ typedef uint32_t (*ProcUICallback)(void *);
|
||||
|
||||
typedef enum ProcUICallbackType
|
||||
{
|
||||
//! Application acquires the foreground
|
||||
PROCUI_CALLBACK_ACQUIRE,
|
||||
//! Application must release the foreground
|
||||
PROCUI_CALLBACK_RELEASE,
|
||||
//! Application must exit
|
||||
PROCUI_CALLBACK_EXIT,
|
||||
//! Application may start using networking
|
||||
PROCUI_CALLBACK_NET_IO_START,
|
||||
//! Application must stop using networking
|
||||
PROCUI_CALLBACK_NET_IO_STOP,
|
||||
//! The user attempted to press the HOME button but was denied
|
||||
PROCUI_CALLBACK_HOME_BUTTON_DENIED,
|
||||
} ProcUICallbackType;
|
||||
|
||||
typedef enum ProcUIStatus
|
||||
{
|
||||
//! The application is in the foreground. All resources may be used.
|
||||
PROCUI_STATUS_IN_FOREGROUND,
|
||||
//! The application is in the background, only limited resources are usable.
|
||||
PROCUI_STATUS_IN_BACKGROUND,
|
||||
//! The application must relelase the foregound - see ProcUIDrawDoneRelease()
|
||||
PROCUI_STATUS_RELEASE_FOREGROUND,
|
||||
//! The application must release all resources (including ProcUI) and quit
|
||||
PROCUI_STATUS_EXITING,
|
||||
} ProcUIStatus;
|
||||
|
||||
uint32_t
|
||||
ProcUICalcMemorySize(uint32_t unk);
|
||||
|
||||
/**
|
||||
* Unregister all ProcUI callbacks.
|
||||
*
|
||||
* \sa
|
||||
* - ProcUIRegisterCallback()
|
||||
*
|
||||
* \if false
|
||||
* Would a currently executing async operation keep or lose the callbacks?
|
||||
* does this block?
|
||||
* \endif
|
||||
*/
|
||||
void
|
||||
ProcUIClearCallbacks();
|
||||
|
||||
/**
|
||||
* Signifies to ProcUI that the current application has released all foreground
|
||||
* resources, drawn its last frame, and is ready to be moved into the
|
||||
* background. Should only be called when the application is in the
|
||||
* #PROCUI_STATUS_RELEASE_FOREGROUND state.
|
||||
*
|
||||
* \note
|
||||
* Upon calling this function, all application threads on cores 0 or 1 are
|
||||
* suspended as soon as possible - see coreinit/Thread for information on when
|
||||
* threads are suspended.
|
||||
*
|
||||
* \warning
|
||||
* Do not attempt to use foreground-only resources after calling this function.
|
||||
* You should wait until ProcUI indicates #PROCUI_STATUS_IN_FOREGROUND.
|
||||
*
|
||||
* \if false
|
||||
* meta: Does the context switch occur before this function returns? the next
|
||||
* ProcessMessages call? how does SubProcessMessages fit in?
|
||||
* doxy: how do you link to the description of coreinit/thread?
|
||||
* \endif
|
||||
*/
|
||||
void
|
||||
ProcUIDrawDoneRelease();
|
||||
|
||||
/**
|
||||
* Determines whether the application is in the foreground.
|
||||
*
|
||||
* \returns
|
||||
* \c true if the application status is #PROCUI_STATUS_IN_FOREGROUND.
|
||||
*
|
||||
* \sa
|
||||
* - #PROCUI_STATUS_IN_FOREGROUND
|
||||
* - ProcUIRegisterCallback()
|
||||
*/
|
||||
BOOL
|
||||
ProcUIInForeground();
|
||||
|
||||
/**
|
||||
* Determines whether the application is in shutdown and should quit.
|
||||
*
|
||||
* \returns
|
||||
* \c true if the application status is #PROCUI_STATUS_EXITING.
|
||||
*
|
||||
* \sa
|
||||
* - #PROCUI_STATUS_EXITING
|
||||
* - ProcUIRegisterCallback()
|
||||
*/
|
||||
BOOL
|
||||
ProcUIInShutdown();
|
||||
|
||||
@ -68,6 +159,8 @@ ProcUIInShutdown();
|
||||
*
|
||||
* \sa
|
||||
* - OSSavesDone_ReadyToRelease()
|
||||
* - ProcUISetSaveCallback()
|
||||
* - ProcUIShutdown()
|
||||
*/
|
||||
void
|
||||
ProcUIInit(ProcUISaveCallback saveCallback);
|
||||
@ -85,11 +178,23 @@ ProcUIInit(ProcUISaveCallback saveCallback);
|
||||
*
|
||||
* \sa
|
||||
* - OSSavesDone_ReadyToRelease()
|
||||
* - ProcUISetSaveCallback()
|
||||
* - ProcUIShutdown()
|
||||
*/
|
||||
void
|
||||
ProcUIInitEx(ProcUISaveCallbackEx saveCallback,
|
||||
void *arg);
|
||||
|
||||
/**
|
||||
* Determines whether the application is running.
|
||||
*
|
||||
* \returns
|
||||
* \c true if the application is running.
|
||||
*
|
||||
* \if false
|
||||
* running? what does that actually mean? any state except exiting?
|
||||
* \endif
|
||||
*/
|
||||
BOOL
|
||||
ProcUIIsRunning();
|
||||
|
||||
@ -100,22 +205,23 @@ ProcUIIsRunning();
|
||||
*
|
||||
* \param block
|
||||
* Determines whether the function should block before returning. If \c false,
|
||||
* the function returns immediately.
|
||||
* the function returns immediately and all messages and callbacks are processed
|
||||
* asynchronously.
|
||||
*
|
||||
* \return
|
||||
* The current state of the program. See #ProcUIStatus.
|
||||
* The current state of the program. See #ProcUIStatus. If block is \c false,
|
||||
* this value is undefined and should be ignored.
|
||||
*
|
||||
* \warning
|
||||
* At this time, using ProcUI's non-blocking mode is not recommended as not much
|
||||
* is known about it. Instead, set block to \c true and examine the return
|
||||
* value.
|
||||
* ProcUI's non-blocking mode is not widely used and may have undocumented
|
||||
* behaviour. Be careful with callbacks and the return value.
|
||||
*
|
||||
* \note
|
||||
* This function should only be called from the main core. See OSIsMainCore().
|
||||
* This function should only be called from the main core. See OSIsMainCore()
|
||||
* and ProcUISubProcessMessages().
|
||||
*
|
||||
* \if false
|
||||
* meta: what happens when block=false? is the return value trustworthy? how
|
||||
* does it interact with ProcUIRegisterCallback?
|
||||
* Assuming
|
||||
* \endif
|
||||
*/
|
||||
ProcUIStatus
|
||||
@ -136,6 +242,9 @@ ProcUIProcessMessages(BOOL block);
|
||||
* \param priority
|
||||
* The priority of the callback.
|
||||
*
|
||||
* \sa
|
||||
* - ProcUIRegisterCallbackCore()
|
||||
*
|
||||
* \if false
|
||||
* higher-priority callbacks exec first? dunno
|
||||
* \endif
|
||||
@ -146,6 +255,29 @@ ProcUIRegisterCallback(ProcUICallbackType type,
|
||||
void *param,
|
||||
uint32_t priority);
|
||||
|
||||
/**
|
||||
* Register a callback for certain ProcUI events on the given core.
|
||||
*
|
||||
* \param type
|
||||
* The event to register a callback for. See #ProcUICallbackType.
|
||||
*
|
||||
* \param callback
|
||||
* Function pointer for the callback to call when the given event occurs.
|
||||
*
|
||||
* \param param
|
||||
* Argument for the callback. This will be passed in as the *second* argument.
|
||||
*
|
||||
* \param priority
|
||||
* The priority of the callback.
|
||||
*
|
||||
* \param core
|
||||
* The core to register the callback for.
|
||||
*
|
||||
* \if false
|
||||
* is core the core that the callback executes on? or is it about having
|
||||
* different callbacks for each core
|
||||
* \false
|
||||
*/
|
||||
void
|
||||
ProcUIRegisterCallbackCore(ProcUICallbackType type,
|
||||
ProcUICallback callback,
|
||||
@ -153,10 +285,33 @@ ProcUIRegisterCallbackCore(ProcUICallbackType type,
|
||||
uint32_t priority,
|
||||
uint32_t core);
|
||||
|
||||
/**
|
||||
* Sets the save callback. Unlike ProcUIInitEx(), this function can be called
|
||||
* while ProcUI is already running.
|
||||
*
|
||||
* \param saveCallback
|
||||
* A callback to be called when the application needs to save. The callback
|
||||
* cannot be NULL and it must call OSSavesDone_ReadyToRelease().
|
||||
*
|
||||
* \param arg
|
||||
* An argument to pass into saveCallbackEx.
|
||||
*
|
||||
* \sa
|
||||
* - OSSavesDone_ReadyToRelease()
|
||||
* - ProcUIInitEx()
|
||||
*/
|
||||
void
|
||||
ProcUISetSaveCallback(ProcUISaveCallbackEx saveCallback,
|
||||
void *arg);
|
||||
|
||||
/**
|
||||
* Shut down the ProcUI library for the current application. This should be
|
||||
* called before the app exits.
|
||||
*
|
||||
* \note
|
||||
* Do not attempt to use any ProcUI library functions after calling this
|
||||
* function, except for ProcUIInit() or ProcUIInitEx().
|
||||
*/
|
||||
void
|
||||
ProcUIShutdown();
|
||||
|
||||
@ -165,12 +320,16 @@ ProcUIShutdown();
|
||||
*
|
||||
* \param block
|
||||
* Determines whether the function should block before returning. If \c false,
|
||||
* the function returns immediately.
|
||||
* the function returns immediately and all messages and callbacks are processed
|
||||
* asynchronously.
|
||||
*
|
||||
* \returns
|
||||
* The current state of the program - see #ProcUIStatus. If block is \c false,
|
||||
* this value is undefined and should be ignored.
|
||||
*
|
||||
* \warning
|
||||
* At this time, using ProcUI's non-blocking mode is not recommended as not much
|
||||
* is known about it. Instead, set block to \c true and examine the return
|
||||
* value.
|
||||
* ProcUI's non-blocking mode is not widely used and may have undocumented
|
||||
* behaviour. Be careful with callbacks and the return value.
|
||||
*
|
||||
* \if false
|
||||
* didn't know what this did, only seen it in the else{} from OSIsMainCore...
|
||||
|
||||
Loading…
Reference in New Issue
Block a user