Updater
To deliver great performance, uiZ uses it's own event system. This makes sure that every object is only updated when it needs to. This page tries to explain how the updater works internally.
UiZ Objects can contain the following User Defined events:
- User Defined 0: Put your draw code here. You may draw whatever you need from the coordinates rx,ry to rlx,rly (but not on rlx or rly itself). The ix,iy and ilx,ily refer to the inner coordinates of the object. Anything you draw here will be contained within a certain area.
- User Defined 1: Defines mouse behavior. By default this should contain uiz_mouse_docheck(). This event may change if you decide to use scrollbars for example. If this event is omitted, the object cannot interact with the mouse.
- User Defined 2: An event that is activate whenever the mouse state of the object changes. So for example when the mouse wasn't on the object before, but is now. Or when the mouse starts clicking the object. This event fires once per state change. The variable "kmouseover" can be read and compared to the constants uiz_nomouse, uiz_mouseover, uiz_mouseclick, uiz_mousepressed and uiz_mousereleased to determine what the mouse is doing.
- User Defined 3: An event which is continuously fired as long as the mouse is hovering over the object.
- User Defined 4: Works like a step event, but can be enabled or disabled on demand by using the uiz_updater_step() and uiz_updater_unstep() functions. Useful if an object does a temporary animation.
- User Defined 5: Used to run code once in the end step event. Use the function uiz_updater_step_endcheck() to run this event once.
- User Defined 6: Used to run code once in the begin step event. Use the function uiz_updater_step_beginCheck() to run this event once.
- User Defined 7: Used for scrollbar specific code. If your object uses a scrollbar, then this event is activated when the mouse hovers over your scrollable object. This differs from User Defined 3 in that objects that don't have a scrollbar are ignored. This means that if this object has scrollbars and User Defined 3 is firing, then User Defined 7 is also firing. If User Defined 7 is firing, this doesn't necessarily mean that User Defined 3 is also firing on this object. See obj_uiZ_template_scrollbar for an example.
- User Defined 8: Activated whenever the position or settings of the object change. (called during a "fix")
When the programmer (you) creates and fixes an uiZ object, it will tell uiZ that it needs to be redrawn. Sometimes, when the mouse or step events (like UD1, 2, 3, 4, 5, 6 or 7) are ran, they also tell uiZ that objects need to be redrawn. Sometimes objects only needs to be partially redrawn, in which case uiZ takes care of that as well.
Then, in the end step, uiZ checks what areas have to be updated. When an object updates, and there are multiple objects behind it, every object behind will also be marked for a redraw. This is done because uiZ doesn't take into account which objects are transparent on which area's.
Sometimes, when objects only have to partially be redrawn they will be "self marked". This is a special state of an object in which it knows it can redraw only a single part of itself. For example, when you hover your mouse over a slider, only the slider knob has to change. Then the object only needs to draw the knob. However, when a different object overlapping your slider updates at the same time as the slider does, the slider also has to redraw. UiZ only distinguishes between two states:
- self marked: draw a part of the object.
- not self marked: Draw the entire object.
Note that even when your object redraws completely, not everything is visible. Compare these two image:
The slider knows how it can only redraw the knob. So only that object has to be drawn. However, the slider has not been programmed to redraw only a small bottom-right corner piece of itself. Therefore when the green object also updates, the slider has no other option but to completely redraw itself. This is a waste of performance since the object hasn't actually changed. In fact, the area's of the slider than don't need to be updated but are redrawn anyway are thrown away by uiz containment functionality.
UiZ reuses the application surface after your game is done drawing a frame to make uiZ more (V)RAM efficient. However, if you are using this surface yourself, or are experiencing graphical issues, you may turn this off using:
-
uiz_updater_useApplicationSurface(bool): Allow or disallow uiZ to recycle the built in application_surface to make uiZ more (V)RAM efficient. IF you use the application_surface differently in your game, you need to turn this off.
- bool[true]: Whether to enable or disable the use of the application_surface by uiZ.
These functions can be used to utilize the updater:
-
uiz_updater_FixViews(): Fix the views for the current object. This reruns the draw event without checking if the position of the object has changed. This function has be called from a uiZ object. The position of the object will be updated, as well as the last position the object was in. (This is to prevent objects from having a ghosting "tail")
-
uiz_updater_FixView_NoMove(): Fix the views for the current object. This reruns the draw event without checking if the position of the object has changed. This function has be called from a uiZ object. Unlike the normal FixViews function, this function only updates the current position of the object.
-
uiz_updater_FixViews_area(x1, y1, x2, y2): A function to redraw uiZ objects within a certain area. This function has to be called from an uiZ object. The coordinates are screen coordinates, not relative to the caller.
- x1: The left side of your area.
- y1: The top side of your area.
- x2: The right side of your area.
- y2: The bottom side of your area.
-
uiz_updater_FixViews_area_selfmarked(x1, y1, x2, y2): A function to redraw uiZ objects within a certain area, while having them self marked. (See section above) This function has to be called from an uiZ object. The coordinates are screen coordinates, not relative to the caller.
- x1: The left side of your area.
- y1: The top side of your area.
- x2: The right side of your area.
- y2: The bottom side of your area.
-
uiz_updater_FixViews_inside(): A function to redraw the inside area of the object. (So between ix, iy, ilx and ily.)
-
uiz_updater_FixViews_with(instance_id): Execute uiz_updater_FixViews(), but with another instance. (which is also a uiZ object).
- instance_id: What uiZ object should have it's views updated.
-
return = uiz_updater_hasPositionChanged(): Returns whether the current object's position is different from the position last time it was fixed. Has to be called from an uiZ object.
- return: If the object's position is different.
-
uiz_updater_step(): Marks that code code specified in the user event 4 should be ran every step on the object. Has to be called from an uiZ object.
-
uiz_updater_unstep(): Marks that code code specified in the user event 4 should not be ran every step on the object anymore. Has to be called from an uiZ object.
-
uiz_updater_step_beginCheck(): Tell uiZ that code in the user 6 event should run once in the begin step event. Has to be called from an uiZ object.
-
uiz_updater_step_endCheck(): Tell uiZ that code in the user 5 event should run once in the end step event. Has to be called from an uiZ object.
-
uiz_updater_useApplicationSurface(bool): Allow or disallow uiZ to recycle the built in application_surface to make uiZ more (V)RAM efficient. IF you use the application_surface differently in your game, you need to turn this off.
- bool[true]: Whether to enable or disable the use of the application_surface by uiZ.