What is CanvasGroup?
CanvasGroup is an instance that allows you to specify a sub-tree of UI instances as a group and render them together like one item. Transparency and color tint can be applied to the whole group through GroupTransparency and GroupColor properties on CanvasGroup.
How do I use it?
After enabling Canvas Group in Studio Beta features with the following steps:
Below is an example of the new CanvasGroup instance to create a semi-transparent prompt:
-
Insert a ScreenGui. Make sure its
ZIndexBehavior
is set to Sibling.
-
Insert a CanvasGroup, you can configure it the same way as configuring a GuiObject.
-
Insert all children as usual.
-
Insert UICorner under CanvasGroup to apply round corner for the whole group.
-
Change GroupTransparency to make the whole prompt semi-transparent.
The Example Place
- This example place is available at:
ExamplePlace - Roblox - You can check it out by directly copying the place:
Special Notes
- CanvasGroup ONLY works if the ancestor ScreenGui/SurfaceGui/BillboardGui is in Sibling ZIndex behavior.
- CanvasGroup always ClipsDescendants.
- If you encounter any issue related to blinking/corrupted display result, we would like to know the following specs of your development device:
- CPU
- GPU
- Display Resolution (all of connected displays)
- Display Window Scale (if applicable)
Known Issues
Pending shipping bug-fixes/features:
CanvasGroup will respect the dpi scale of the screen.GroupColor
will be renamed toGroupColor3
MakeClipDescendants
always set totrue
to reduce confusion.-
Text is blurry under CanvasGroups. CanvasGroup’s behavior(update fps/resolution) will respect graphics settings of user.Rotated text objects with gradient have rendering artifacts.Image asset update should immediately trigger a canvas update.Crash when typing into TextBoxes under CanvasGroups.
WIP
- AutoButtonColor for buttons does not get stably triggered under canvas group.
FAQ
Why CanvasGroup only works with ZIndexBehavior-Sibling?
- When ZIndexBehavior is Global, there could be situations where some of the children render before the parent and some of the children render after the parent. In order to use CanvasGroup, the parent-children order must be determined, as all the children are rendered as one group.
- For detailed information about ZIndexBehavior and render order of instances, check out this place: Beautiful World - Roblox
Why is CanvasGroup always ClipsDescendants?
- CanvasGroup utilizes its own GUI rectangle as a viewport when rendering its child content. The resulting texture is the exact size of its own absolute size.
I am a developer that cares more about performance, what should I know about this feature?
- While it could be used to achieve effects like GroupTransaprency/ColorTint/Group Effects, it is used with extra time and memory cost. For developers concerned with performance, consider the following memory and operation requirements for each CanvasGroup used:
- An extra texture of size
AbsoluteSize.x * AbsoluteSize.y
(with DPI scaling applied) will be allocated to achieve the final result.
What will happen with different graphics settings or the device is out of memory?
- CanvasGroup items will be subjected to down-res fallbacks when the system is high on texture memory pressure, which means there could be appearance (resolution) differences depending on system memory conditions.
References of different quality levels:
- High Quality Reference
- Medium Quality Reference
- Low Quality Reference
- When the device completely fails to allocate the necessary memory, the item will be displayed as a blank texture.