/** @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 . * * 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 /* * 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 */