Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 256 insertions, 0 deletions

diff --git a/include/VBox/RemoteDesktop/VRDEImage.h b/include/VBox/RemoteDesktop/VRDEImage.h
new file mode 100644
index 00000000..54cd674e
--- /dev/null
+++ b/include/VBox/RemoteDesktop/VRDEImage.h
@@ -0,0 +1,256 @@
+/** @file
+ * VBox Remote Desktop Extension (VRDE) - Image updates interface.
+ */
+
+/*
+ * Copyright (C) 2006-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef VBOX_INCLUDED_RemoteDesktop_VRDEImage_h
+#define VBOX_INCLUDED_RemoteDesktop_VRDEImage_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <VBox/RemoteDesktop/VRDE.h>
+
+/*
+ * Generic interface for external image updates with a clipping region to be sent
+ * to the client.
+ *
+ * Async callbacks are used for reporting errors, providing feedback, etc.
+ */
+
+#define VRDE_IMAGE_INTERFACE_NAME "IMAGE"
+
+#ifdef __cplusplus
+class VRDEImage;
+typedef class VRDEImage *HVRDEIMAGE;
+#else
+struct VRDEImage;
+typedef struct VRDEImage *HVRDEIMAGE;
+#endif /* __cplusplus */
+
+/*
+ * Format description structures for VRDEImageHandleCreate.
+ */
+typedef struct VRDEIMAGEFORMATBITMAP
+{
+    uint32_t u32BytesPerPixel; /** @todo impl */
+} VRDEIMAGEFORMATBITMAP;
+
+typedef struct VRDEIMAGEBITMAP
+{
+    uint32_t    cWidth;      /* The width of the bitmap in pixels. */
+    uint32_t    cHeight;     /* The height of the bitmap in pixels. */
+    const void *pvData;      /* Address of pixel buffer. */
+    uint32_t    cbData;      /* Size of pixel buffer. */
+    const void *pvScanLine0; /* Address of first scanline. */
+    int32_t     iScanDelta;  /* Difference between two scanlines. */
+} VRDEIMAGEBITMAP;
+
+/*
+ * Image update handle creation flags.
+ */
+#define VRDE_IMAGE_F_CREATE_DEFAULT       0x00000000
+#define VRDE_IMAGE_F_CREATE_CONTENT_3D    0x00000001 /* Input image data is a rendered 3d scene. */
+#define VRDE_IMAGE_F_CREATE_CONTENT_VIDEO 0x00000002 /* Input image data is a sequence of video frames. */
+#define VRDE_IMAGE_F_CREATE_WINDOW        0x00000004 /* pRect parameter is the image update area. */
+
+/*
+ * Completion flags for image update handle creation.
+ */
+#define VRDE_IMAGE_F_COMPLETE_DEFAULT 0x00000000 /* The handle has been created. */
+#define VRDE_IMAGE_F_COMPLETE_ASYNC   0x00000001 /* The server will call VRDEImageCbNotify when the handle is ready. */
+
+/*
+ * Supported input image formats.
+ *
+ * The identifiers are arbitrary and new formats can be introduced later.
+ *
+ */
+#define VRDE_IMAGE_FMT_ID_BITMAP_BGRA8 "BITMAP_BGRA8.07e46a64-e93e-41d4-a845-204094f5ccf1"
+
+/** The VRDE server external image updates interface entry points. Interface version 1. */
+typedef struct VRDEIMAGEINTERFACE
+{
+    /** The header. */
+    VRDEINTERFACEHDR header;
+
+    /** Create image updates handle.
+     *
+     * The server can setup a context which will speed up further updates.
+     *
+     * A failure is returned if the server either does not support requested updates
+     * or it failed to create a handle.
+     *
+     * A success means that the server was able to create an internal context for
+     * the updates.
+     *
+     * @param hServer     The server instance handle.
+     * @param phImage     The returned image updates handle.
+     * @param pvUser      The caller context of the call.
+     * @param u32ScreenId Updates are for this screen in a multimonitor config.
+     * @param fu32Flags   VRDE_IMAGE_F_CREATE_* flags, which describe input data.
+     * @param pRect       If VRDE_IMAGE_F_CREATE_WINDOW is set, this is the area of expected updates.
+     *                    Otherwise the entire screen will be used for updates.
+     * @param pvFormat    Format specific data.
+     * @param cbFormat    Size of format specific data.
+     * @param *pfu32CompletionFlags VRDE_IMAGE_F_COMPLETE_* flags. Async handle creation, etc.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(int, VRDEImageHandleCreate, (HVRDESERVER hServer,
+                                                      HVRDEIMAGE *phImage,
+                                                      void *pvUser,
+                                                      uint32_t u32ScreenId,
+                                                      uint32_t fu32Flags,
+                                                      const RTRECT *pRect,
+                                                      const char *pszFormatId,
+                                                      const void *pvFormat,
+                                                      uint32_t cbFormat,
+                                                      uint32_t *pfu32CompletionFlags));
+
+    /** Create image updates handle.
+     *
+     * @param hImage The image updates handle, which the caller will not use anymore.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(void, VRDEImageHandleClose, (HVRDEIMAGE hImage));
+
+    /** Set a clipping region for a particular screen.
+     *
+     * @param hImage    The image updates handle.
+     * @param cRects    How many rectangles. 0 clears region for this screen.
+     * @param paRects   Rectangles in the screen coordinates.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(int, VRDEImageRegionSet, (HVRDEIMAGE hImage,
+                                                   uint32_t cRects,
+                                                   const RTRECT *paRects));
+
+    /** Set the new position of the update area. Only works if the image handle
+     * has been created with VRDE_IMAGE_F_CREATE_WINDOW.
+     *
+     * @param hImage    The image updates handle.
+     * @param pRect     New area rectangle in the screen coordinates.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(int, VRDEImageGeometrySet, (HVRDEIMAGE hImage,
+                                                     const RTRECT *pRect));
+
+    /** Set a configuration parameter.
+     *
+     * @param hImage      The image updates handle.
+     * @param pszName     The parameter name.
+     * @param pszValue    The parameter value.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(int, VRDEImagePropertySet, (HVRDEIMAGE hImage,
+                                                     const char *pszName,
+                                                     const char *pszValue));
+
+    /** Query a configuration parameter.
+     *
+     * @param hImage      The image updates handle.
+     * @param pszName     The parameter name.
+     * @param pszValue    The parameter value.
+     * @param cbValueIn   The size of pszValue buffer.
+     * @param pcbValueOut The length of data returned in pszValue buffer.
+     *
+     * Properties names:
+     * "ID" - an unique string for this hImage.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(int, VRDEImagePropertyQuery, (HVRDEIMAGE hImage,
+                                                       const char *pszName,
+                                                       char *pszValue,
+                                                       uint32_t cbValueIn,
+                                                       uint32_t *pcbValueOut));
+
+    /** Data for an image update.
+     *
+     * @param hImage      The image updates handle.
+     * @param i32TargetX  Target x.
+     * @param i32TargetY  Target y.
+     * @param i32TargetW  Target width.
+     * @param i32TargetH  Target height.
+     * @param pvImageData Format specific image data (for example VRDEIMAGEBITMAP).
+     * @param cbImageData Size of format specific image data.
+     */
+    DECLR3CALLBACKMEMBER(void, VRDEImageUpdate, (HVRDEIMAGE hImage,
+                                                 int32_t i32TargetX,
+                                                 int32_t i32TargetY,
+                                                 uint32_t u32TargetW,
+                                                 uint32_t u32TargetH,
+                                                 const void *pvImageData,
+                                                 uint32_t cbImageData));
+} VRDEIMAGEINTERFACE;
+
+/*
+ * Notifications.
+ * u32Id parameter of VRDEIMAGECALLBACKS::VRDEImageCbNotify.
+ */
+#define VRDE_IMAGE_NOTIFY_HANDLE_CREATE 1 /* Async result of VRDEImageHandleCreate.
+                                           * pvData: uint32_t = 0 if stream was not created,
+                                           * a non zero value otherwise.
+                                           */
+
+typedef struct VRDEIMAGECALLBACKS
+{
+    /** The header. */
+    VRDEINTERFACEHDR header;
+
+    /** Generic notification callback.
+     *
+     * @param hServer   The server instance handle.
+     * @param pvContext The callbacks context specified in VRDEGetInterface.
+     * @param pvUser    The pvUser parameter of VRDEImageHandleCreate.
+     * @param hImage    The handle, same as returned by VRDEImageHandleCreate.
+     * @param u32Id     The notification identifier: VRDE_IMAGE_NOTIFY_*.
+     * @param pvData    The callback specific data.
+     * @param cbData    The size of buffer pointed by pvData.
+     *
+     * @return IPRT status code.
+     */
+    DECLR3CALLBACKMEMBER(int, VRDEImageCbNotify,(void *pvContext,
+                                                 void *pvUser,
+                                                 HVRDEIMAGE hVideo,
+                                                 uint32_t u32Id,
+                                                 void *pvData,
+                                                 uint32_t cbData));
+} VRDEIMAGECALLBACKS;
+
+#endif /* !VBOX_INCLUDED_RemoteDesktop_VRDEImage_h */