See also: Changing Structure Permissions. For a list of all Structure functions and related topics, see Structures.
Structure permissions provide a mechanism for performance optimization by allowing the implementation to perform various transformations on a structure that improve performance. Some structure permissions restrict the operations you are allowed to perform on a structure. Structure Permissions and Operations table lists the structure requests allowed for each permission. You may perform all rendering and picking requests on structures of any permission with the following exception:
A structure's permission defaults to PEXStructureReadWrite when you create it. Use the PEXSetStructurePermission function to change the permission of the structure.
Structure Permissions and Operations
-----------------------------------------------------------------------------
Permission Allowed Structure Operations
-----------------------------------------------------------------------------
PEXStructureReadWrite All.
PEXStructureWriteOnly All but PEXFetchElements
PEXCopyElements
PEXCopyStructure
PEXStructureLocked PEXChangeStructureReferences,
PEXDestroyStructures,
PEXGetAncestors,
PEXGetDescendants,
PEXGetStructureInfo,
PEXGetStructuresInNetwork.
-----------------------------------------------------------------------------
When a structure's permission is StructureWriteOnly you cannot read the structure's elements using the PEXFetchElements function or copy its elements to a structure which has a permission of PEXStructureReadWrite. If you try any of these operations, you may receive a structure permission error. The PEX implementation is free to modify an individual element as long as the structure network, the element's type, and the element's effect during rendering and picking is maintained. Maintaining the structure network implies that structure referencing output commands (e.g., Execute Structure) retain their positions in the structure as the structure's permission is changed.
You cannot edit, read, or copy elements from a structure that has its permission set to PEXStructureLocked.
If you lock a structure that contains Execute Structure, Conditional Execute Structure, Include Structure, or Conditional Include Structure output commands, the operation does not modify the permissions of the referenced structures. Locked structures may include references to other structures. The PEX implementation is free to modify the structure's elements as long as the structure network, the elements' types, and the elements' effects during rendering and picking are maintained. Maintaining the structure network implies that structure-referencing output commands (e.g., Execute Structure) retain their positions in the structure as the structure's permission is changed. Note that these references are updated by the implementation in response to PEXChangeStructureRefs requests or the deletion of the referenced structure as if the structure were not locked. As an example, if locked structure "A" contained an Execute Structure OC for structure "B" at offset 4 and an Execute Structure OC for structure "C" at offset 6, and you destroy structure "B", the Execute Structure OC at offset 4 is deleted and the Execute Structure for structure "C" at offset 6 moves to offset 5. For the purposes of rendering and picking, the only valid element positions in a locked structure are position 0 and the positions of structure references. When you use functions that require specific element positions, such as picking, searching, partial traversals, and structure editing on locked structures, you are restricted to using element positions that refer to position 0 or to positions that contain structure referencing output commands.
See also: Structure Permissions. For a list of all Structure functions and related topics, see Structures.
You can change the permission of a newly created structure, or a structure whose permission has not yet been modified, to the permissions PEXStructureWriteOnly or PEXStructureLocked. If you change a structure's permission to PEXStructureWriteOnly, you can only change it to the permission PEXStructureLocked. If you change a structure's permission to PEXStructureLocked then you can no longer alter that structure's permission. Note that it is an error to attempt to change the permission of a structure to the structure's current permission.
Allowed Structure Permission Changes ---------------------------------------------------------- Current Permission PEXStructureWriteOnly PEXStructureLocked ---------------------------------------------------------- PEXStructureReadWrite OK OK PEXStructureWriteOnly Error OK PEXStructureLocked Error Error ------------------------------------------