IVROverlay:

* Added GetOverlayKey and GetOverlayName which return the key or name of an overlay from its handle.
* Added GetOverlayImageData which returns the current raw image data from an overlay.
* Improved reliability of SetOverlayRaw and SetOverlayFromFile.
* Added VREvent_ImageLoaded, which is sent when SetOverlayRaw or SetOverlayFromFile finish updating the overlay texture.
* Added VROverlayError_UnableToLoadFile, which may be returned if SetOverlayFromFile fails.
* Added ShowDashboard, which will make the dashboard visible if a dashboard manager is present. We aren’t shipping a dashboard manager quite yet, so this function currently does nothing.

IVRNotifications:
* This new interface allows applications to post notifications to the user. Details and documentation are coming soon.

[git-p4: depot-paths = "//vr/steamvr/sdk_release/": change = 2877976]

headers/openvr.h

@@ -277,6 +277,8 @@ enum EVREventType
 	VREvent_DashboardThumbSelected	= 504, // Sent to the overlay manager - data is overlay
 	VREvent_DashboardRequested		= 505, // Sent to the overlay manager - data is overlay
 	VREvent_ResetDashboard			= 506, // Send to the overlay manager
+	VREvent_RenderToast				= 507, // Send to the dashboard to render a toast - data is the notification ID
+	VREvent_ImageLoaded				= 508, // Sent to overlays when a SetOverlayRaw or SetOverlayFromFile call finishes loading
 
 	VREvent_Notification_Show				= 600,
 	VREvent_Notification_Dismissed			= 601,
@@ -992,6 +994,99 @@ static const char * const IVRCompositor_Version = "IVRCompositor_007";
 } // namespace vr
 
 
+// ivrnotifications.h
+namespace vr
+{
+
+#if defined(__linux__) || defined(__APPLE__) 
+	// The 32-bit version of gcc has the alignment requirement for uint64 and double set to
+	// 4 meaning that even with #pragma pack(8) these types will only be four-byte aligned.
+	// The 64-bit version of gcc has the alignment requirement for these types set to
+	// 8 meaning that unless we use #pragma pack(4) our structures will get bigger.
+	// The 64-bit structure packing has to match the 32-bit structure packing for each platform.
+	#pragma pack( push, 4 )
+#else
+	#pragma pack( push, 8 )
+#endif
+
+const char * const NotificationTypeFriendUpdate = "FriendUpdate";
+
+// Used for passing graphic data
+struct NotificationBitmap
+{
+	char *bytes;
+	int32_t width;
+	int32_t height;
+	int32_t depth;
+};
+
+enum NotificationError_t
+{
+	k_ENotificationError_OK = 0,
+	k_ENotificationError_Fail = 1
+};
+
+static const uint32_t k_unNotificationTypeMaxSize = 16;
+static const uint32_t k_unNotificationTextMaxSize = 128;
+
+/** The types of events that could be posted (and what the parameters mean for each event type) */
+/*enum NotificationEventType
+{
+	Notification_None = 0,
+
+	Notification_Dismissed			= 101, // param1 = Device index
+	Notification_BeginInteraction	= 102, // param1 = Device index
+	Notification_Scroll				= 103, // param1 = Device index
+	Notification_ClickOn			= 104, // param1 = Device index
+	Notification_ClickOff			= 105, // param1 = Device index
+};*/
+
+/** An event posted by the server to all running applications */
+/*struct NotificationEvent_t
+{
+	NotificationEventType eventType;
+	int32_t x; // X coordinate in the notifications bitmap when the click happened
+	int32_t y; // Y coordinate in the notifications bitmap when the click happened
+	int32_t scroll_x; // X scrolling amount in the notifications bitmap coords
+	int32_t scroll_y; // Y scrolling amount in the notifications bitmap coords
+	uint32_t buttons; // Buttons pressed
+
+	float eventAgeSeconds;
+};*/
+
+typedef uint32_t VRNotificationId;
+
+// This struct will be used for the history list of notifications
+struct NotificationItem
+{
+	VRNotificationId notificationId;
+};
+
+
+
+#pragma pack( pop )
+
+/** Allows notification sources to interact with the VR system
+	This current interface is not yet implemented. Do not use yet. */
+class IVRNotifications
+{
+public:
+	/** Returns the last error that occurred */
+	virtual uint32_t GetErrorString( NotificationError_t error, VR_OUT_STRING() char* pchBuffer, uint32_t unBufferSize ) = 0;
+
+	VR_METHOD_DESC( Create a new notification. )
+	virtual NotificationError_t CreateNotification( VROverlayHandle_t ulOverlayHandle, uint64_t ulUserValue, char *strType, char *strText, char *strCategory, NotificationBitmap *photo, /* out */ vr::VRNotificationId *notificationId  ) = 0;
+
+	VR_METHOD_DESC(Dismiss the notification)
+	virtual NotificationError_t DismissNotification( vr::VRNotificationId notificationId ) = 0;
+
+};
+
+static const char * const IVRNotifications_Version = "IVRNotifications_001";
+
+} // namespace vr
+
+
 // ivroverlay.h
 namespace vr
 {
@@ -1030,6 +1125,7 @@ namespace vr
 		VROverlayError_ArrayTooSmall		= 22,
 		VROverlayError_RequestFailed		= 23,
 		VROverlayError_InvalidTexture		= 24,
+		VROverlayError_UnableToLoadFile		= 25,
 	};
 
 	/** Types of input supported by VR Overlays */
@@ -1100,6 +1196,18 @@ namespace vr
 		* Otherwise it will return k_ulOverlayHandleInvalid. */
 		virtual vr::VROverlayHandle_t GetHighQualityOverlay() = 0;
 
+		/** Fills the provided buffer with the string key of the overlay. Returns the size of buffer required to store the key, including
+		* the terminating null character. k_unVROverlayMaxKeyLength will be enough bytes to fit the string. */
+		virtual uint32_t GetOverlayKey( VROverlayHandle_t ulOverlayHandle, VR_OUT_STRING() char *pchValue, uint32_t unBufferSize, VROverlayError *pError = 0L ) = 0;
+
+		/** Fills the provided buffer with the friendly name of the overlay. Returns the size of buffer required to store the key, including
+		* the terminating null character. k_unVROverlayMaxNameLength will be enough bytes to fit the string. */
+		virtual uint32_t GetOverlayName( VROverlayHandle_t ulOverlayHandle, VR_OUT_STRING() char *pchValue, uint32_t unBufferSize, VROverlayError *pError = 0L ) = 0;
+
+		/** Gets the raw image data from an overlay. Overlay image data is always returned as RGBA data, 4 bytes per pixel. If the buffer is not large enough, width and height 
+		* will be set and VROverlayError_ArrayTooSmall is returned. */
+		virtual VROverlayError GetOverlayImageData( VROverlayHandle_t ulOverlayHandle, void *pvBuffer, uint32_t unBufferSize, uint32_t *punWidth, uint32_t *punHeight ) = 0;
+
 		/** returns a string that corresponds with the specified overlay error. The string will be the name 
 		* of the error enum value for all valid error codes */
 		virtual const char *GetOverlayErrorNameFromEnum( VROverlayError error ) = 0;
@@ -1244,11 +1352,15 @@ namespace vr
 		/** Sets the dashboard overlay to only appear when the specified process ID has scene focus */
 		virtual VROverlayError SetDashboardOverlaySceneProcess( VROverlayHandle_t ulOverlayHandle, uint32_t unProcessId ) = 0;
 
-		/** Gets the process ID that this system overlay requires to have scene focus */
+		/** Gets the process ID that this dashboard overlay requires to have scene focus */
 		virtual VROverlayError GetDashboardOverlaySceneProcess( VROverlayHandle_t ulOverlayHandle, uint32_t *punProcessId ) = 0;
+
+		/** Shows the dashboard. */
+		virtual void ShowDashboard( const char *pchOverlayToShow ) = 0;
+
 	};
 
-	static const char * const IVROverlay_Version = "IVROverlay_002";
+	static const char * const IVROverlay_Version = "IVROverlay_003";
 
 } // namespace vr
 // ivrrendermodels.h

headers/openvr_api.cs

@@ -149,6 +149,12 @@ class VRNativeEntrypoints
 	internal static extern VROverlayError VR_IVROverlay_SetHighQualityOverlay(IntPtr instancePtr, ulong ulOverlayHandle);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_GetHighQualityOverlay")]
 	internal static extern ulong VR_IVROverlay_GetHighQualityOverlay(IntPtr instancePtr);
+	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_GetOverlayKey")]
+	internal static extern uint VR_IVROverlay_GetOverlayKey(IntPtr instancePtr, ulong ulOverlayHandle, System.Text.StringBuilder pchValue, uint unBufferSize, ref VROverlayError pError);
+	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_GetOverlayName")]
+	internal static extern uint VR_IVROverlay_GetOverlayName(IntPtr instancePtr, ulong ulOverlayHandle, System.Text.StringBuilder pchValue, uint unBufferSize, ref VROverlayError pError);
+	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_GetOverlayImageData")]
+	internal static extern VROverlayError VR_IVROverlay_GetOverlayImageData(IntPtr instancePtr, ulong ulOverlayHandle, IntPtr pvBuffer, uint unBufferSize, ref uint punWidth, ref uint punHeight);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_GetOverlayErrorNameFromEnum")]
 	internal static extern IntPtr VR_IVROverlay_GetOverlayErrorNameFromEnum(IntPtr instancePtr, VROverlayError error);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_SetOverlayFlag")]
@@ -223,6 +229,8 @@ class VRNativeEntrypoints
 	internal static extern VROverlayError VR_IVROverlay_SetDashboardOverlaySceneProcess(IntPtr instancePtr, ulong ulOverlayHandle, uint unProcessId);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_GetDashboardOverlaySceneProcess")]
 	internal static extern VROverlayError VR_IVROverlay_GetDashboardOverlaySceneProcess(IntPtr instancePtr, ulong ulOverlayHandle, ref uint punProcessId);
+	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVROverlay_ShowDashboard")]
+	internal static extern void VR_IVROverlay_ShowDashboard(IntPtr instancePtr, string pchOverlayToShow);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRRenderModels_LoadRenderModel")]
 	internal static extern bool VR_IVRRenderModels_LoadRenderModel(IntPtr instancePtr, string pchRenderModelName, ref RenderModel_t pRenderModel);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRRenderModels_FreeRenderModel")]
@@ -301,10 +309,8 @@ class VRNativeEntrypoints
 	internal static extern void VR_IVRChaperoneSetup_ReloadFromDisk(IntPtr instancePtr);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRNotifications_GetErrorString")]
 	internal static extern uint VR_IVRNotifications_GetErrorString(IntPtr instancePtr, NotificationError_t error, System.Text.StringBuilder pchBuffer, uint unBufferSize);
-	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRNotifications_NotificationStart")]
-	internal static extern NotificationError_t VR_IVRNotifications_NotificationStart(IntPtr instancePtr, ulong ulOverlayHandle, string strType, IntPtr pTexture, ulong ulUserValue, ref uint pNotificationId);
-	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRNotifications_UpdateTexture")]
-	internal static extern NotificationError_t VR_IVRNotifications_UpdateTexture(IntPtr instancePtr, uint notificationId, IntPtr pTexture);
+	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRNotifications_CreateNotification")]
+	internal static extern NotificationError_t VR_IVRNotifications_CreateNotification(IntPtr instancePtr, ulong ulOverlayHandle, ulong ulUserValue, string strType, string strText, string strCategory, ref NotificationBitmap photo, ref uint notificationId);
 	[DllImportAttribute("openvr_api", EntryPoint = "VR_IVRNotifications_DismissNotification")]
 	internal static extern NotificationError_t VR_IVRNotifications_DismissNotification(IntPtr instancePtr, uint notificationId);
 
@@ -402,6 +408,9 @@ public abstract class IVROverlay
 	public abstract VROverlayError DestroyOverlay(ulong ulOverlayHandle);
 	public abstract VROverlayError SetHighQualityOverlay(ulong ulOverlayHandle);
 	public abstract ulong GetHighQualityOverlay();
+	public abstract uint GetOverlayKey(ulong ulOverlayHandle,System.Text.StringBuilder pchValue,uint unBufferSize,ref VROverlayError pError);
+	public abstract uint GetOverlayName(ulong ulOverlayHandle,System.Text.StringBuilder pchValue,uint unBufferSize,ref VROverlayError pError);
+	public abstract VROverlayError GetOverlayImageData(ulong ulOverlayHandle,IntPtr pvBuffer,uint unBufferSize,ref uint punWidth,ref uint punHeight);
 	public abstract string GetOverlayErrorNameFromEnum(VROverlayError error);
 	public abstract VROverlayError SetOverlayFlag(ulong ulOverlayHandle,VROverlayFlags eOverlayFlag,bool bEnabled);
 	public abstract VROverlayError GetOverlayFlag(ulong ulOverlayHandle,VROverlayFlags eOverlayFlag,ref bool pbEnabled);
@@ -439,6 +448,7 @@ public abstract class IVROverlay
 	public abstract bool IsActiveDashboardOverlay(ulong ulOverlayHandle);
 	public abstract VROverlayError SetDashboardOverlaySceneProcess(ulong ulOverlayHandle,uint unProcessId);
 	public abstract VROverlayError GetDashboardOverlaySceneProcess(ulong ulOverlayHandle,ref uint punProcessId);
+	public abstract void ShowDashboard(string pchOverlayToShow);
 }
 
 
@@ -508,8 +518,7 @@ public abstract class IVRNotifications
 {
 	public abstract IntPtr GetIntPtr();
 	public abstract uint GetErrorString(NotificationError_t error,System.Text.StringBuilder pchBuffer,uint unBufferSize);
-	public abstract NotificationError_t NotificationStart(ulong ulOverlayHandle,string strType,IntPtr pTexture,ulong ulUserValue,ref uint pNotificationId);
-	public abstract NotificationError_t UpdateTexture(uint notificationId,IntPtr pTexture);
+	public abstract NotificationError_t CreateNotification(ulong ulOverlayHandle,ulong ulUserValue,string strType,string strText,string strCategory,ref NotificationBitmap photo,ref uint notificationId);
 	public abstract NotificationError_t DismissNotification(uint notificationId);
 }
 
@@ -991,6 +1000,26 @@ public override ulong GetHighQualityOverlay()
 		ulong result = VRNativeEntrypoints.VR_IVROverlay_GetHighQualityOverlay(m_pVROverlay);
 		return result;
 	}
+	public override uint GetOverlayKey(ulong ulOverlayHandle,System.Text.StringBuilder pchValue,uint unBufferSize,ref VROverlayError pError)
+	{
+		CheckIfUsable();
+		uint result = VRNativeEntrypoints.VR_IVROverlay_GetOverlayKey(m_pVROverlay,ulOverlayHandle,pchValue,unBufferSize,ref pError);
+		return result;
+	}
+	public override uint GetOverlayName(ulong ulOverlayHandle,System.Text.StringBuilder pchValue,uint unBufferSize,ref VROverlayError pError)
+	{
+		CheckIfUsable();
+		uint result = VRNativeEntrypoints.VR_IVROverlay_GetOverlayName(m_pVROverlay,ulOverlayHandle,pchValue,unBufferSize,ref pError);
+		return result;
+	}
+	public override VROverlayError GetOverlayImageData(ulong ulOverlayHandle,IntPtr pvBuffer,uint unBufferSize,ref uint punWidth,ref uint punHeight)
+	{
+		CheckIfUsable();
+		punWidth = 0;
+		punHeight = 0;
+		VROverlayError result = VRNativeEntrypoints.VR_IVROverlay_GetOverlayImageData(m_pVROverlay,ulOverlayHandle,pvBuffer,unBufferSize,ref punWidth,ref punHeight);
+		return result;
+	}
 	public override string GetOverlayErrorNameFromEnum(VROverlayError error)
 	{
 		CheckIfUsable();
@@ -1224,6 +1253,11 @@ public override VROverlayError GetDashboardOverlaySceneProcess(ulong ulOverlayHa
 		VROverlayError result = VRNativeEntrypoints.VR_IVROverlay_GetDashboardOverlaySceneProcess(m_pVROverlay,ulOverlayHandle,ref punProcessId);
 		return result;
 	}
+	public override void ShowDashboard(string pchOverlayToShow)
+	{
+		CheckIfUsable();
+		VRNativeEntrypoints.VR_IVROverlay_ShowDashboard(m_pVROverlay,pchOverlayToShow);
+	}
 }
 
 
@@ -1557,17 +1591,11 @@ public override uint GetErrorString(NotificationError_t error,System.Text.String
 		uint result = VRNativeEntrypoints.VR_IVRNotifications_GetErrorString(m_pVRNotifications,error,pchBuffer,unBufferSize);
 		return result;
 	}
-	public override NotificationError_t NotificationStart(ulong ulOverlayHandle,string strType,IntPtr pTexture,ulong ulUserValue,ref uint pNotificationId)
-	{
-		CheckIfUsable();
-		pNotificationId = 0;
-		NotificationError_t result = VRNativeEntrypoints.VR_IVRNotifications_NotificationStart(m_pVRNotifications,ulOverlayHandle,strType,pTexture,ulUserValue,ref pNotificationId);
-		return result;
-	}
-	public override NotificationError_t UpdateTexture(uint notificationId,IntPtr pTexture)
+	public override NotificationError_t CreateNotification(ulong ulOverlayHandle,ulong ulUserValue,string strType,string strText,string strCategory,ref NotificationBitmap photo,ref uint notificationId)
 	{
 		CheckIfUsable();
-		NotificationError_t result = VRNativeEntrypoints.VR_IVRNotifications_UpdateTexture(m_pVRNotifications,notificationId,pTexture);
+		notificationId = 0;
+		NotificationError_t result = VRNativeEntrypoints.VR_IVRNotifications_CreateNotification(m_pVRNotifications,ulOverlayHandle,ulUserValue,strType,strText,strCategory,ref photo,ref notificationId);
 		return result;
 	}
 	public override NotificationError_t DismissNotification(uint notificationId)
@@ -1700,6 +1728,8 @@ public enum EVREventType
 	VREvent_DashboardThumbSelected = 504,
 	VREvent_DashboardRequested = 505,
 	VREvent_ResetDashboard = 506,
+	VREvent_RenderToast = 507,
+	VREvent_ImageLoaded = 508,
 	VREvent_Notification_Show = 600,
 	VREvent_Notification_Dismissed = 601,
 	VREvent_Notification_BeginInteraction = 602,
@@ -1812,6 +1842,7 @@ public enum VROverlayError
 	ArrayTooSmall = 22,
 	RequestFailed = 23,
 	InvalidTexture = 24,
+	UnableToLoadFile = 25,
 }
 public enum VROverlayInputMethod
 {
@@ -2120,11 +2151,13 @@ public static string GetStringForHmdError(HmdError error)
 	public const uint k_unVROverlayMaxKeyLength = 128;
 	public const uint k_unVROverlayMaxNameLength = 128;
 	public const uint k_unMaxOverlayCount = 32;
-	public const string IVROverlay_Version = "IVROverlay_002";
+	public const string IVROverlay_Version = "IVROverlay_003";
 	public const string IVRRenderModels_Version = "IVRRenderModels_001";
 	public const string IVRControlPanel_Version = "IVRControlPanel_001";
 	public const string IVRCameraAccess_Version = "IVRCameraAccess_001";
 	public const string IVRChaperoneSetup_Version = "IVRChaperoneSetup_001";
+	public const uint k_unNotificationTypeMaxSize = 16;
+	public const uint k_unNotificationTextMaxSize = 128;
 	public const string IVRNotifications_Version = "IVRNotifications_001";
 }