3. Concepts
3.1. Basic Object Creation and Deletion
All objects shared using this toolkit must be created and deleted through designated toolkit methods rather than Unity’s Instantiate and Destroy methods.
3.1.1. Object Creation
Objects are created via the InstantiateShared method. The method takes a Unity prefab to create the shared object from (this prefab must include a SharedObject.cs script component -- see Section 2.1), a user ID to automatically share this object with, the permissions to offer that user ID upon sharing it, and a boolean for whether the object should be shared in a location-decoupled way with that user ID. It returns the created GameObject. For example, creating an object from myPrefab and offering VIEW permissions to a co-located user with an ID of 42 is achieved as follows:
GameObject newObject = PermissionSystem.Instance.InstantiateShared(myPrefab, 42,
PermissionSystem.Permission.VIEW, false);
To offer the given permissions to all other participating users instead of only a single one, the constant -1 can be used.
3.1.2. Object Deletion
Objects shared in the default location-coupled way (see Section 3.4 for alternatives) are deleted using the DeleteShared method. Deleting an object myObject for one user only, with all other sufficiently permissioned users still able to access the object, is achieved by setting the scope parameter to 0, as follows:
PermissionSystem.Instance.DeleteShared(myObject, 0);
Deleting the object for all users is achieved by setting the scope parameter to 1, as follows:
PermissionSystem.Instance.DeleteShared(myObject, 1);
3.2. Permission Model
3.2.1. Preliminaries
ShareAR contains permission controls on both a per-object and a per-user basis. That is, whether a certain user has access to a certain object is a function of both the user and the object in question.
For a given object and a given user, the user may have a range of possible permissions on the object. The permissions currently supported by ShareAR, given in the Permission enum, are VIEWGHOST, VIEW, MOVE, COPY, EDIT, RESHARE, and OWN. (Please refer to Section 3.3 for further information on the VIEWGHOST permission.) Some permissions also imply other ones; notating X → Y to mean that a user with permission X on an object must also have permission Y on the object, the permission hierarchy can be diagrammed in the following graph:
Sections 3.2.2 and 3.2.3 discuss how to set defaults for these permissions and how to change these permissions, respectively. Please also refer to Section 3.3 for recommended practices for co-located users, and to Section 3.4 for further information on sharing content with users who may not be co-located.
3.2.2. Default Permissions
ShareAR also supports default permission settings that determine the initial permission state when a new object is created or a new user joins.
There are two default axes that define default behavior:
- New-user defaults. This axis specifies for each object what permissions a newly-joined user should have on that object.
- New-object defaults. This axis specifies for each user what permissions the user should have initially on a new object.
When a new object is created, existing users’ initial permissions on that object are automatically set to be those of the new-object defaults. When a new user joins, their initial permissions on existing objects are automatically set to be those of the new-user defaults.
Both new-user and new-object defaults are initialized with a private access control setting. Applications may override this behavior using the SetDefaultUserPermissions, SetDefaultObjectPermissions, and SetDefaultUserDefaultObjectPermissions methods. However, to minimize unintended information leakage, it is recommended that applications do so cautiously, auto-applying the most restrictive permission settings that are expected to arise realistically in the context of the application.
3.2.3. Changing Permissions
To change a user’s permission on a specific object, ShareAR provides a TryChangePermission method. Permission revocation calls take effect immediately. Importantly, though, a granted permission does not take effect immediately, but rather must be approved by the user being offered the permission; this allows for the receiving user to manage how their reality is augmented. An example call of TryChangePermission, to revoke view permissions on a GameObject variable myObject to a user with an ID of 42, is shown below:
bool success = PermissionSystem.Instance.TryChangePermission(42,
myObject, false, PermissionSystem.Permission.VIEW);
A permission change message from another user is received via either the PermissionChanged event or the NewDiscoverable event. Changes that are auto-processed are relayed to the application via the PermissionChanged event; these include (1) permission revocation messages, (2) permission grants to which preconfigured acceptance rules apply, and (3) permission changes for a third party regarding an object that the current user has permissions on. Offered permission grants that are not yet handled are communicated to the application via the NewDiscoverable event, and it is the responsibility of the application to either accept, ignore, or decline the offer, as detailed below.
- Accepting an offer. This operation, done via the Accept method, enacts the offered permission change. The device offering the permission is notified (via an Accepted event) that the offer has been accepted, and all other devices with permissions on that object are notified (via a PermissionChanged event) that the permissions on the object have changed.
- Ignoring an offer. This operation, done via the Ignore method, frees all resources associated with the pending offer without enacting the offered change and without notifying any other device about the decision.
- Declining an offer. This operation, done via the Decline method, frees all resources associated with the pending offer without enacting the offered change; the device offering the permission is notified (via a Declined event) that the offer has been declined.
3.3. Intuitive Sharing with Co-Located Users
Studies of users’ expectations of AR technologies indicate that users tend to draw a strong analogy between shared AR experiences and the shared physical world: notably, users often expect that AR objects in a shared physical space are also shared. However, some content -- such as a private messaging window -- is expected by users to remain visibility-restricted.
ShareAR’s principle of ghosting is a solution to this paradox. Its main idea is to share with other users that an access-restricted object is present in the shared physical space without revealing what sensitive information the object contains. It does so by enabling developer-defined “ghost” objects that serve as location-accurate placeholders for access-restricted objects. Users without permission to view a ghosting-enabled object see instead the ghost object in the same location that the original object is.
Consider, by way of analogy, the scenario of a user interacting with a mobile phone. Even without seeing what is displayed on the phone screen, the visual cue of the phone in the user’s hands (rather than empty air) signals that the user is busy with the device as well as where in physical space the user’s attention is directed, thus allowing other users to scaffold their behavior around that information. Likewise, an AR user who sees another user interacting with a ghost object receives the busy cue and social signal, thereby preserving the user’s intuition about the shared physical world without revealing the sensitive information.
To configure a ghost version of an object in ShareAR, make a prefab for the ghost version and register that prefab with ObjectIDManager.cs just as you would with a non-ghost prefab; then add a reference to the ghost prefab in the original object’s ghostPrefab field in the Unity editor. The ghost prefab should also have a SharedObject.cs script attached.
Once a ghost counterpart to an object prefab pf has been configured, a newly created object myObject with that prefab can be shared in a ghost-only manner by granting all users VIEWGHOST permissions upon myObject’s instantiation as follows:
GameObject myObject =
PermissionSystem.Instance.InstantiateShared(pf, AllUsers(),
(int)PermissionSystem.Permission.VIEWGHOST, false);
For this policy to apply to all newly joining users, a default permission can be set for the object:
PermissionSystem.Instance.SetDefaultUserPermissions(myObject,
(int)PermissionSystem.Permission.VIEWGHOST);
Please refer to Section 3.2.2 for further detail on setting default permissions.
3.4. Intuitive Sharing with Remotely Located Users
User studies have shown that users often expect that AR objects in a shared physical space obey physical-world intuitions: notably, multiple users all expect to see the same object in the same location. When sharing an object with a co-located user, then, it is ideal that both users see the object in the same location in physical space, and that if one user moves the object then the other users also see the object move. For remotely located users sharing AR content, however, this location-coupling property is impractical; the two users have two separate location-dependent instantiations of the same object, both with the same permissions and the same non-location data.
If two users change their location in the physical world, though, they may become co-located when previously they were not. Under this circumstance, ShareAR ensures that both users see both instantiations of the object such that each instantiation appears in the same physical location to both users. This is shown in the following diagram:
Left: A naive solution for location decoupling; C is not in synch with A and B after moving into the same space. Right: ShareAR’s solution; all users are now in synch.
Creating a location-decoupled object from a prefab pf is done by setting the isRemote parameter in the InstantiateShared method to true, as shown in the following example:
GameObject myObject =
PermissionSystem.Instance.InstantiateShared(pf, AllUsers(),
PermissionSystem.Permission.VIEW, true);
Sharing myObject in a location-decoupled way with user ID 42 is likewise done by setting the isRemote parameter to true, as follows:
bool success = PermissionSystem.Instance.TryChangePermission(42, myObject,
true, PermissionSystem.Permission.EDIT, true);
As with location-coupled object deletion, location-decoupled object deletion is done using the DeleteShared method. It is recommended that this be done in one of two ways. If only the current user’s instantiation of an object myObject is intended to be deleted, leaving all other users’ instantiations intact, then deletion can be done by setting the scope parameter to 1:
PermissionSystem.Instance.DeleteShared(myObject, 1);
If instead myObject is intended to be deleted for all users, destroying all users’ instantiations of the object, then deletion can be done by setting the scope parameter to 2:
PermissionSystem.Instance.DeleteShared(myObject, 2);
This toolkit does not yet support splitting an object into two instantiations of the same object or merging two users’ instantiations into one.