CHANGELOG.md

@@ -4,4 +4,32 @@ All notable changes to this package will be documented in this file.
 
 ## [1.0.0]
 
-- Initial release.
+- Initial release.
+
+## [1.1.0]
+
+- **Improvement:** Improve the counter annotation API.
+- **Fix:** Added binding synchronization for multi-threaded usage.
+
+## [1.2.0]
+
+- **Improvement:** Added Unity profiler metrics as counters.
+
+## [1.3.0]
+
+- **Fix:** Added static annotation ID namespacing to avoid collisions with
+  other Arm tooling, such as the Performance Advisor layer driver.
+
+## [1.4.0]
+
+- **Fix:** Added 64-bit counter value support in the annotation API.
+
+## [1.5.0]
+
+- **Improvement:** Improved CAM annotation API to support track nesting.
+- **Improvement:** Improved CAM annotation API to support job dependencies.
+- **Fix:** Renamed counter `set_value()` to `setValue()`.
+
+- - -
+
+_Copyright © 2021-2024, Arm Limited and contributors. All rights reserved._

Documentation/Mobile-Studio.md → Documentation/Performance-Studio.md

@@ -1,31 +1,35 @@
-Unity Bindings for Mobile Studio
-================================
+Unity Bindings for Performance Studio
+=====================================
 
 Introduction
 ------------
 
 This package contains C# bindings needed to export application-generated
-counters and event annotations to the Mobile Studio Streamline profiler.
+counters and event annotations to the Performance Studio Streamline profiler.
 
 The Streamline profiler can collect and present application software profiling
 information alongside sample-based hardware performance counter data from both
 Arm CPUs and GPUs. Streamline has an *annotations* feature which allows the
 application being profiled to emit additional information that can be displayed
 alongside the other captured performance information.
 
+> **Note:** Performance Studio was formerly known as Mobile Studio. For API
+> backwards compatibility the package continues to use the `MobileStudio` file
+> name prefix and C# namespace.
+
 Installation
 ------------
 
 1) Open the package manager in Unity.
 2) Click `+` in the toolbar and select `Add package from git URL`.
-3) Import the Mobile Studio package from GitHub into your project.
+3) Import the Performance Studio package from GitHub into your project.
 
 It is recommended that you set up a define so you can easily remove the
 package from release builds without leaving errors in your code from package
 usage. To set up the define, follow these steps:
 
-4) If you do not have an asmdef file for scripts that reference the Mobile
-   Studio API, create one.
+4) If you do not have an asmdef file for scripts that reference the package
+   API, create one.
 5) In the asmdef file, under `Assembly Definition References`,
    add `MobileStudio.Runtime`.
 6) In the asmdef file, under `Version Defines`, add a rule:
@@ -34,7 +38,7 @@ usage. To set up the define, follow these steps:
       c) Set `Expression` to `1.0.0`
    This rule makes Unity define `MOBILE_STUDIO` if the `com.arm.mobile-studio`
    package is present in the project and if its version is greater than `1.0.0`.
-7) In your code, wrap `MOBILE_STUDIO` around the Mobile Studio API:
+7) In your code, wrap `MOBILE_STUDIO` around the package API use:
 
    #if MOBILE_STUDIO
       // Package usage
@@ -48,72 +52,75 @@ Usage
 
 ### Markers
 
-The simplest annotations are markers. To use them in a project into which you
-have included this package, simply call into the Mobile Studio library as
-follows:
+Markers are the simplest annotations, emitting a timestamped point indicator
+that will be shown along the top of the Streamline timeline view.
 
-    MobileStudio.Annotations.marker("Frame");
+To emit a marker, e.g:
 
-This will emit a timestamped marker with the label "Frame", which Streamline
-will show along the top of the timeline.
+    MobileStudio.Annotations.marker("Frame");
 
-You can also specify the color of the marker by passing an optional Color
-object, such as:
+You can also specify the color of the marker by passing an optional Unity
+`Color` object, e.g:
 
     MobileStudio.Annotations.marker("Frame", Color.green);
 
 ### Channels
 
-Channels are custom event timelines associated with a software thread. When a
-channel has been created, you can place annotations within it. A channel
-annotation has a text label and a color but, unlike markers, they span a range
-of time.
+Channels are custom event swimlanes that are associated with a software thread
+in the Streamline timeline. Once a channel has been created, you can place
+job annotations within it. A channel job annotation has a text label and a
+color but, unlike markers, they span a range of time.
 
-To create a channel:
+To create a channel, e.g.:
 
     channel = new MobileStudio.Annotations.Channel("AI");
 
-Annotations can be inserted into a channel easily:
+To insert an annotation time-box into the channel, e.g.:
 
+    // Trigger the start of the annotation
     channel.annotate("NPC AI", Color.red);
-    // Do work ...
+
+    // Do the work you want to time ...
+
+    // Trigger the end of the annotation
     channel.end();
 
 ### Counters
 
-Counters are numerical data points that can be plotted as a chart in the
+Counters are numerical data points that can be plotted as a chart series in the
 Streamline timeline view. Counters can be created as either absolute counters,
 where every value is an absolute value, or as a delta counter, where values are
 the number of instances of an event since the last value was emitted. All
 values are floats and will be presented to 2 decimal places.
 
-When charts are first defined the user can specify two strings, a title and
-series name. The title names the chart, the series names the data series.
-Multiple counter series can use the same title, which means that they will be
-plotted on the same chart in the Streamline timeline.
+When charts are first defined you can specify a title and a series name. The
+title names the chart, the series names the data series. Multiple counter
+series can use the same title, which means that they will be plotted on the
+same chart in the Streamline timeline.
 
 To create a counter, e.g.:
 
     counter = new MobileStudio.Annotations.Counter(
         "Title", "Series", MobileStudio.Annotations.CounterType.Absolute);
 
-Counter values are set easily:
+To set a value for a counter, e.g.:
 
     counter.setValue(42.2f);
 
 ### Custom Activity Maps
 
-Custom Activity Map (CAM) views allow execution information to be plotted on
-a hierarchical set of timelines. Like channel annotations, CAM views plot Jobs
-on tracks, but unlike channel annotations, CAM views are not associated with a
-specific thread. CAM Jobs can also be linked by dependency lines, allowing
-control flow between them to be visualized.
+Custom Activity Map (CAM) views allow job execution information to be plotted
+on a hierarchical set of swimlane tracks. Each CAM view defines a standalone
+visualization and, unlike channel annotations, tracks are not associated with
+with a specific calling thread. Dependency information between jobs within a
+single CAM view can also be defined, allowing the visualization to show
+control flow information if it is provided.
 
-To create a CAM view:
+To create a CAM view, e.g:
 
     gameCAM = new MobileStudio.Annotations.CAM("Game Activity");
 
-To add tracks to the CAM:
+To add tracks to the CAM, e.g:
 
     // Create root tracks in the view
     aiTrack = gameCAM.createTrack("AI activity");
@@ -154,11 +161,15 @@ Streamline visualization.
 Further Reading
 ---------------
 
-If you'd like to know more or raise any questions, please see the Mobile Studio
-developer pages at:
+If you'd like to know more or raise any questions, please see the Performance
+Studio developer pages at:
+
+  * https://developer.arm.com/performance-studio
+
+Community support is available from Arm's graphics forum at:
 
-  * https://developer.arm.com/mobile-studio
+  * https://community.arm.com/graphics
 
-Community support is available from Arm's Graphics and Multimedia forum at:
+  - - -
 
-  * https://community.arm.com/support-forums/f/graphics-gaming-and-vr-forum
+_Copyright © 2021-2024, Arm Limited and contributors. All rights reserve

LICENSE_UNITY.md

@@ -1,5 +1,9 @@
 Unity Native Plugin API copyright © 2015 Unity Technologies ApS
 
-Licensed under the Unity Companion License for Unity-dependent projects--see [Unity Companion License](http://www.unity3d.com/legal/licenses/Unity_Companion_License).
+Licensed under the Unity Companion License for Unity-dependent projects -- see
+[Unity Companion License](http://www.unity3d.com/legal/licenses/Unity_Companion_License).
 
-Unless expressly provided otherwise, the Software under this license is made available strictly on an “AS IS” BASIS WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. Please review the license for details on these and other terms and conditions.
+Unless expressly provided otherwise, the Software under this license is made
+available strictly on an “AS IS” BASIS WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. Please review the license for details on these and other terms and
+conditions.

README.md

@@ -1,22 +1,25 @@
-Mobile Studio Package
-======================
+Performance Studio Package
+==========================
 
-This project is a Unity package for integrating the Mobile Studio tool suite
-into game development workflows. This version of the package has the following
-features for integrating with the Streamline profiler.
+This project is a Unity package for integrating the Performance Studio tool
+suite into game development workflows. This version of the package has the
+following features for integrating with the Streamline profiler.
 
 * C# language bindings for emitting event annotations.
 * C# language bindings for emitting software counters.
 
+> **Note:** Performance Studio was formerly known as Mobile Studio. For API
+> backwards compatibility the package continues to use the `MobileStudio` file
+> name prefix and C# namespace.
+
 License
 =======
 
-Most files in this library are licensed under the BSD-3 Clause License,
-provided in [LICENSE.md](LICENSE.md).
+Most files in this library are licensed under the BSD-3 Clause License (see
+[LICENSE.md](LICENSE.md)).
 
 The Unity native plugin interface header, `IUnityInterface.h`, is licensed
-under the Unity Companion License, provided in
-[LICENSE_UNITY.md](LICENSE_UNITY.md).
+under the Unity Companion License (see [LICENSE_UNITY.md](LICENSE_UNITY.md)).
 
 Technical details
 =================
@@ -32,8 +35,8 @@ Building
 
 This package is built using the Unity bee compiler.
 
-1) Set the environment variable `ANDROID_NDK_ROOT`
-   to a local Android NDK install. Android NDK can usually be found in:
+1) Set the environment variable `ANDROID_NDK_ROOT` to a local Android NDK
+   install. Android NDK can usually be found in:
    `\Editor\Data\PlaybackEngines\AndroidPlayer\NDK`.
 2) Locate the bee compiler in your Unity install. It is usually found in:
    `\Editor\Data\il2cpp\build\BeeSettings\offline\bee.exe`.
@@ -51,7 +54,8 @@ Installing and using
 --------------------
 
 For instructions on how to install and use this package, see the
-[full documentation page](Documentation/Mobile-Studio.md).
-
+[full documentation page](Documentation/Performance-Studio.md).
 
+- - -
 
+_Copyright © 2021-2024, Arm Limited and contributors. All rights reserved._