Docs: formalize naming for generic callbacks in BKE_callbacks.h
Add a doc-string explaining the purpose of each call back and how they should be used. Also add a currently unused callback 'POST_FAIL' that is to be used in cases the action fails - giving script authors, a guarantee that a call to `pre` will always have a matching `post/post_fail` call. - D11422: adds a callback that can use 'post_fail'. - T88696: proposed these conventions.
This commit is contained in:
parent
3b3742c75f
commit
507c19c0f7
Notes:
blender-bot
2023-02-14 07:39:44 +01:00
Referenced by issue #88696, Formalize naming conventions for "bpy.app.handlers" / BKE_callbacks
|
@ -30,11 +30,60 @@ struct Main;
|
|||
struct PointerRNA;
|
||||
|
||||
/**
|
||||
* Common suffix uses:
|
||||
* - ``_PRE/_POST``:
|
||||
* For handling discrete non-interactive events.
|
||||
* - ``_INIT/_COMPLETE/_CANCEL``:
|
||||
* For handling jobs (which may in turn cause other handlers to be called).
|
||||
Callbacks for One Off Actions
|
||||
* =============================
|
||||
*
|
||||
* - `{ACTION}` use in cases where only a single callback is required,
|
||||
* `VERSION_UPDATE` and `RENDER_STATS` for example.
|
||||
*
|
||||
* \note avoid single callbacks if there is a chance `PRE/POST` are useful to differentiate
|
||||
* since renaming callbacks may break Python scripts.
|
||||
*
|
||||
* Callbacks for Common Actions
|
||||
* ============================
|
||||
*
|
||||
* - `{ACTION}_PRE` run before the action.
|
||||
* - `{ACTION}_POST` run after the action.
|
||||
*
|
||||
* Optional Additional Callbacks
|
||||
* -----------------------------
|
||||
*
|
||||
* - `{ACTION}_INIT` when the handler may manipulate the context used to run the action.
|
||||
*
|
||||
* Examples where `INIT` functions may be useful are:
|
||||
*
|
||||
* - When rendering, an `INIT` function may change the camera or render settings,
|
||||
* things which a `PRE` function can't support as this information has already been used.
|
||||
* - When saving an `INIT` function could temporarily change the preferences.
|
||||
*
|
||||
* - `{ACTION}_POST_FAIL` should be included if the action may fail.
|
||||
*
|
||||
* Use this so a call to the `PRE` callback always has a matching call to `POST` or `POST_FAIL`.
|
||||
*
|
||||
* \note in most cases only `PRE/POST` are required.
|
||||
*
|
||||
* Callbacks for Background/Modal Tasks
|
||||
* ====================================
|
||||
*
|
||||
* - `{ACTION}_INIT`
|
||||
* - `{ACTION}_COMPLETE` when a background job has finished.
|
||||
* - `{ACTION}_CANCEL` When a background job is canceled partway through.
|
||||
*
|
||||
* While cancellation may be caused by any number of reasons, common causes may include:
|
||||
*
|
||||
* - Explicit user cancellation.
|
||||
* - Exiting Blender.
|
||||
* - Failure to acquire resources (such as disk-full, out of memory ... etc).
|
||||
*
|
||||
* \note `PRE/POST` handlers may be used along side modal task handlers
|
||||
* as is the case for rendering, where rendering an animation uses modal task handlers,
|
||||
* rendering a single frame has `PRE/POST` handlers.
|
||||
*
|
||||
* Python Access
|
||||
* =============
|
||||
*
|
||||
* All callbacks here must be exposed via the Python module `bpy.app.handlers`,
|
||||
* see `bpy_app_handlers.c`.
|
||||
*/
|
||||
typedef enum {
|
||||
BKE_CB_EVT_FRAME_CHANGE_PRE,
|
||||
|
|
|
@ -43,6 +43,9 @@ void bpy_app_generic_callback(struct Main *main,
|
|||
|
||||
static PyTypeObject BlenderAppCbType;
|
||||
|
||||
/**
|
||||
* See `BKE_callbacks.h` #eCbEvent declaration for the policy on naming.
|
||||
*/
|
||||
static PyStructSequence_Field app_cb_info_fields[] = {
|
||||
{"frame_change_pre",
|
||||
"Called after frame change for playback and rendering, before any data is evaluated for the "
|
||||
|
|
Loading…
Reference in New Issue