256 lines
10 KiB
C++
256 lines
10 KiB
C++
/** @file
|
|
* VBox Remote Desktop Extension (VRDE) - Image updates interface.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (C) 2006-2024 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 */
|