containment

Containment

Containment in uiz is making sure that objects don't draw outside the locations they are supposed to draw. < For example, you might have an object with a size of 500x500 inside a frame that is only 100x100. Uiz will then detect that there is a bigger object inside another smaller object. It will then make sure that the big object won't draw outside the canvas of the frame.

How does containment work?

First uiz checks if an object exceeds any boundaries. This check is partly done in the uiz_fix functions. If the object is completely outside of boundaries and shouldn't be visible, the drawing of the object is disabled. If the object is partly within boundaries, and partly outside of them, a containment method will be used. There are 2 ways of containing something in uiz: shaders and surfaces.

Shaders are the default way to handle containment as it is faster and doesn't use any extra ram. However, some systems don't support shaders or you are using code that isn't compatible with shaders. In such cases uiz will use surfaces instead of shaders to contain objects. Note that almost all testing has been done with shaders, and that the surface method is only included as a very, very last resort.

Manipulating containment.

The following functions are available to change the way containment is handled:

• uiz_shader_setEnabled(enabled): Globally enables or disabled the use of shaders by uiZ.

  • enabled[true]: Whether to have shaders enabled or disabled

• uiz_shader_object(instanceid, enabled): Enable or disable the use of shaders for a specific object.

  • instanceid: The instanceid of a uiZ object you want to modify.
  • enabled[true]: Whether to enabled the use of containment shaders for this object.

• uiz_shader_useFallbackShader(enabled): if this option is enabled, uiZ will not pass uniform values directly to fragment shaders, but will make uniforms pass trough the vertex shader. Some platforms have problems with passing uniforms directly to fragment shaders. you need to do a uiz_shader_update after calling this script.

  • enabled: Enable of disabled the use of the fallback shader.

your custom ui widgets

For containment to work, the code "if uiz_cntn() then{" at the beginning, and "uiz_containend()}" at the end of the user 0 event (the uiZ draw event) of an uiz object is needed. See the basic object template.

For your custom ui widgets, these functions are available:

• uiz_cntn(): To be called in the user 0 event to start uiZ containment functionality. Returns whether the object has to draw any code at all. (false if the object is outside of the view of the parent)

• uiz_containend(): To be placed at the end of the user 0 event to stop uiZ from containing drawn objects.

• uiz_contain_custom(x1, y1, x2, y2): Set a custom area in which to contain your drawing code. The area is given in pixel values as global gui coordinate (so not local to any parent).

  • x1: The x coordinate of the left side of your custom contain area.
  • y1: The y coordinate of the top side of your custom contain area.
  • x2: The x coordinate of the right side of your custom contain area.
  • y2: The y coordinate of the bottom side of your custom contain area.

• uiz_contain_custom_min(x1, y1, x2, y2): Set a custom area in which to contain your drawing code. However, the area is cut off if exceeds the boundaries of the original contain area as calculated by uiZ. The area is given in pixel values as global gui coordinate (so not local to any parent). This function needs to be called after calling uiz_cntn and before calling uiz_containend.

  • x1: The x coordinate of the left side of your custom contain area.
  • y1: The y coordinate of the top side of your custom contain area.
  • x2: The x coordinate of the right side of your custom contain area.
  • y2: The y coordinate of the bottom side of your custom contain area.

• uiz_contain_custom_min_left(x1): Allows you to make change the left coordinate of the uiZ contain area. The new coordinate may not be smaller than the original one. This function needs to be called after calling uiz_cntn and before calling uiz_containend.

  • x1: The x coordinate of the left side of your custom contain area.

• uiz_contain_custom_min_top(y1): Allows you to make change the top coordinate of the uiZ contain area. The new coordinate may not be smaller than the original one. This function needs to be called after calling uiz_cntn and before calling uiz_containend.

  • y1: The y coordinate of the top side of your custom contain area.

• uiz_contain_custom_min_right(x2): Allows you to make change the right coordinate of the uiZ contain area. The new coordinate may not be smaller than the original one. This function needs to be called after calling uiz_cntn and before calling uiz_containend.

  • x2: The x coordinate of the right side of your custom contain area.

• uiz_contain_custom_min_bottom(y2): Allows you to make change the bottom coordinate of the uiZ contain area. The new coordinate may not be smaller than the original one. This function needs to be called after calling uiz_cntn and before calling uiz_containend.

  • y2: The y coordinate of the bottom side of your custom contain area.