VirtualBox

source: vbox/trunk/include/VBox/RemoteDesktop/VRDEImage.h@ 96407

Last change on this file since 96407 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.2 KB
Line 
1/** @file
2 * VBox Remote Desktop Extension (VRDE) - Image updates interface.
3 */
4
5/*
6 * Copyright (C) 2006-2022 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_RemoteDesktop_VRDEImage_h
37#define VBOX_INCLUDED_RemoteDesktop_VRDEImage_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <VBox/RemoteDesktop/VRDE.h>
43
44/*
45 * Generic interface for external image updates with a clipping region to be sent
46 * to the client.
47 *
48 * Async callbacks are used for reporting errors, providing feedback, etc.
49 */
50
51#define VRDE_IMAGE_INTERFACE_NAME "IMAGE"
52
53#ifdef __cplusplus
54class VRDEImage;
55typedef class VRDEImage *HVRDEIMAGE;
56#else
57struct VRDEImage;
58typedef struct VRDEImage *HVRDEIMAGE;
59#endif /* __cplusplus */
60
61/*
62 * Format description structures for VRDEImageHandleCreate.
63 */
64typedef struct VRDEIMAGEFORMATBITMAP
65{
66 uint32_t u32BytesPerPixel; /** @todo impl */
67} VRDEIMAGEFORMATBITMAP;
68
69typedef struct VRDEIMAGEBITMAP
70{
71 uint32_t cWidth; /* The width of the bitmap in pixels. */
72 uint32_t cHeight; /* The height of the bitmap in pixels. */
73 const void *pvData; /* Address of pixel buffer. */
74 uint32_t cbData; /* Size of pixel buffer. */
75 const void *pvScanLine0; /* Address of first scanline. */
76 int32_t iScanDelta; /* Difference between two scanlines. */
77} VRDEIMAGEBITMAP;
78
79/*
80 * Image update handle creation flags.
81 */
82#define VRDE_IMAGE_F_CREATE_DEFAULT 0x00000000
83#define VRDE_IMAGE_F_CREATE_CONTENT_3D 0x00000001 /* Input image data is a rendered 3d scene. */
84#define VRDE_IMAGE_F_CREATE_CONTENT_VIDEO 0x00000002 /* Input image data is a sequence of video frames. */
85#define VRDE_IMAGE_F_CREATE_WINDOW 0x00000004 /* pRect parameter is the image update area. */
86
87/*
88 * Completion flags for image update handle creation.
89 */
90#define VRDE_IMAGE_F_COMPLETE_DEFAULT 0x00000000 /* The handle has been created. */
91#define VRDE_IMAGE_F_COMPLETE_ASYNC 0x00000001 /* The server will call VRDEImageCbNotify when the handle is ready. */
92
93/*
94 * Supported input image formats.
95 *
96 * The identifiers are arbitrary and new formats can be introduced later.
97 *
98 */
99#define VRDE_IMAGE_FMT_ID_BITMAP_BGRA8 "BITMAP_BGRA8.07e46a64-e93e-41d4-a845-204094f5ccf1"
100
101/** The VRDE server external image updates interface entry points. Interface version 1. */
102typedef struct VRDEIMAGEINTERFACE
103{
104 /** The header. */
105 VRDEINTERFACEHDR header;
106
107 /** Create image updates handle.
108 *
109 * The server can setup a context which will speed up further updates.
110 *
111 * A failure is returned if the server either does not support requested updates
112 * or it failed to create a handle.
113 *
114 * A success means that the server was able to create an internal context for
115 * the updates.
116 *
117 * @param hServer The server instance handle.
118 * @param phImage The returned image updates handle.
119 * @param pvUser The caller context of the call.
120 * @param u32ScreenId Updates are for this screen in a multimonitor config.
121 * @param fu32Flags VRDE_IMAGE_F_CREATE_* flags, which describe input data.
122 * @param pRect If VRDE_IMAGE_F_CREATE_WINDOW is set, this is the area of expected updates.
123 * Otherwise the entire screen will be used for updates.
124 * @param pvFormat Format specific data.
125 * @param cbFormat Size of format specific data.
126 * @param *pfu32CompletionFlags VRDE_IMAGE_F_COMPLETE_* flags. Async handle creation, etc.
127 *
128 * @return IPRT status code.
129 */
130 DECLR3CALLBACKMEMBER(int, VRDEImageHandleCreate, (HVRDESERVER hServer,
131 HVRDEIMAGE *phImage,
132 void *pvUser,
133 uint32_t u32ScreenId,
134 uint32_t fu32Flags,
135 const RTRECT *pRect,
136 const char *pszFormatId,
137 const void *pvFormat,
138 uint32_t cbFormat,
139 uint32_t *pfu32CompletionFlags));
140
141 /** Create image updates handle.
142 *
143 * @param hImage The image updates handle, which the caller will not use anymore.
144 *
145 * @return IPRT status code.
146 */
147 DECLR3CALLBACKMEMBER(void, VRDEImageHandleClose, (HVRDEIMAGE hImage));
148
149 /** Set a clipping region for a particular screen.
150 *
151 * @param hImage The image updates handle.
152 * @param cRects How many rectangles. 0 clears region for this screen.
153 * @param paRects Rectangles in the screen coordinates.
154 *
155 * @return IPRT status code.
156 */
157 DECLR3CALLBACKMEMBER(int, VRDEImageRegionSet, (HVRDEIMAGE hImage,
158 uint32_t cRects,
159 const RTRECT *paRects));
160
161 /** Set the new position of the update area. Only works if the image handle
162 * has been created with VRDE_IMAGE_F_CREATE_WINDOW.
163 *
164 * @param hImage The image updates handle.
165 * @param pRect New area rectangle in the screen coordinates.
166 *
167 * @return IPRT status code.
168 */
169 DECLR3CALLBACKMEMBER(int, VRDEImageGeometrySet, (HVRDEIMAGE hImage,
170 const RTRECT *pRect));
171
172 /** Set a configuration parameter.
173 *
174 * @param hImage The image updates handle.
175 * @param pszName The parameter name.
176 * @param pszValue The parameter value.
177 *
178 * @return IPRT status code.
179 */
180 DECLR3CALLBACKMEMBER(int, VRDEImagePropertySet, (HVRDEIMAGE hImage,
181 const char *pszName,
182 const char *pszValue));
183
184 /** Query a configuration parameter.
185 *
186 * @param hImage The image updates handle.
187 * @param pszName The parameter name.
188 * @param pszValue The parameter value.
189 * @param cbValueIn The size of pszValue buffer.
190 * @param pcbValueOut The length of data returned in pszValue buffer.
191 *
192 * Properties names:
193 * "ID" - an unique string for this hImage.
194 *
195 * @return IPRT status code.
196 */
197 DECLR3CALLBACKMEMBER(int, VRDEImagePropertyQuery, (HVRDEIMAGE hImage,
198 const char *pszName,
199 char *pszValue,
200 uint32_t cbValueIn,
201 uint32_t *pcbValueOut));
202
203 /** Data for an image update.
204 *
205 * @param hImage The image updates handle.
206 * @param i32TargetX Target x.
207 * @param i32TargetY Target y.
208 * @param i32TargetW Target width.
209 * @param i32TargetH Target height.
210 * @param pvImageData Format specific image data (for example VRDEIMAGEBITMAP).
211 * @param cbImageData Size of format specific image data.
212 */
213 DECLR3CALLBACKMEMBER(void, VRDEImageUpdate, (HVRDEIMAGE hImage,
214 int32_t i32TargetX,
215 int32_t i32TargetY,
216 uint32_t u32TargetW,
217 uint32_t u32TargetH,
218 const void *pvImageData,
219 uint32_t cbImageData));
220} VRDEIMAGEINTERFACE;
221
222/*
223 * Notifications.
224 * u32Id parameter of VRDEIMAGECALLBACKS::VRDEImageCbNotify.
225 */
226#define VRDE_IMAGE_NOTIFY_HANDLE_CREATE 1 /* Async result of VRDEImageHandleCreate.
227 * pvData: uint32_t = 0 if stream was not created,
228 * a non zero value otherwise.
229 */
230
231typedef struct VRDEIMAGECALLBACKS
232{
233 /** The header. */
234 VRDEINTERFACEHDR header;
235
236 /** Generic notification callback.
237 *
238 * @param hServer The server instance handle.
239 * @param pvContext The callbacks context specified in VRDEGetInterface.
240 * @param pvUser The pvUser parameter of VRDEImageHandleCreate.
241 * @param hImage The handle, same as returned by VRDEImageHandleCreate.
242 * @param u32Id The notification identifier: VRDE_IMAGE_NOTIFY_*.
243 * @param pvData The callback specific data.
244 * @param cbData The size of buffer pointed by pvData.
245 *
246 * @return IPRT status code.
247 */
248 DECLR3CALLBACKMEMBER(int, VRDEImageCbNotify,(void *pvContext,
249 void *pvUser,
250 HVRDEIMAGE hVideo,
251 uint32_t u32Id,
252 void *pvData,
253 uint32_t cbData));
254} VRDEIMAGECALLBACKS;
255
256#endif /* !VBOX_INCLUDED_RemoteDesktop_VRDEImage_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette