Debian Codegraph @

cmrtlib/linux/share/cm_device_base.h

raw
1 /*
2 * Copyright (c) 2017, Intel Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included
12 * in all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20 * OTHER DEALINGS IN THE SOFTWARE.
21 */
22 #ifndef CMRTLIB_LINUX_SHARE_CM_DEVICE_BASE_H_
23 #define CMRTLIB_LINUX_SHARE_CM_DEVICE_BASE_H_
24
25 #include "cm_def.h"
26 #include "cm_device_def.h"
27
28 class CmBuffer;
29 class CmSurface2D;
30 class CmProgram;
31 class CmKernel;
32 class CmTask;
33 class CmQueue;
34 class CmThreadSpace;
35 class CmThreadGroupSpace;
36 class CmBufferSVM;
37 class CmBufferUP;
38 class CmSurface2DUP;
39 class CmSurface3D ;
40 class CmSampler;
41 class CmSampler8x8;
42 class CmVebox;
43 class CmBufferStateless;
44 class SurfaceIndex;
45 class CmSurface2DStateless;
46 struct CM_SAMPLER_8X8_DESCR;
47 struct VME_STATE_G6;
48
49 //! \brief CmDevice class for Linux
50 class CmDevice
51 {
52 public:
53 //! \brief Creates a CmBuffer with specified size in bytes.
54 //! \details This function creates a buffer in video memory with linear
55 //! layout.
56 //! \param [in] size
57 //! Buffer size in bytes.
58 //! \param [out] buffer
59 //! Reference to the pointer to the CmBuffer.
60 //! \retval CM_SUCCESS if the CmBuffer is successfully created.
61 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
62 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
63 //! surface fails.
64 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
65 //! larger than CM_MAX_1D_SURF_WIDTH.
66 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
67 //! is exceeded. The amount is the amount of the surfaces
68 //! that can co-exist. The amount can be obtained by querying
69 //! the cap CAP_BUFFER_COUNT.
70 //! \retval CM_FAILURE otherwise.
71 CM_RT_API virtual int32_t CreateBuffer(uint32_t size, CmBuffer* &buffer)=0;
72
73 //! \brief Creates a CmSurface2D with given width, height, and format.
74 //! \details This function creates a surface in video memory with a 2D layout.
75 //! User needs to provide width, height and format.
76 //! \param [in] width
77 //! Surface width in pixel.
78 //! \param [in] height
79 //! Surface height in pixel.
80 //! \param [in] format
81 //! Surface format.
82 //! \param [out] surface
83 //! Reference to the pointer to the CmSurface2D.
84 //! \retval CM_SUCCESS if the CmSurface2D is successfully created.
85 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
86 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath
87 //! resource fails.
88 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
89 //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2, or NV12
90 //! format, the width is odd.
91 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
92 //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format,
93 //! the height is odd.
94 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
95 //! supported. The supported formats can be obtained by
96 //! querying cap CAP_SURFACE2D_FORMAT_COUNT and
97 //! CAP_SURFACE2D_FORMATS. For now, the following formats are
98 //! supported: \n
99 //! CM_SURFACE_FORMAT_A8R8G8B8, \n
100 //! CM_SURFACE_FORMAT_X8R8G8B8, \n
101 //! CM_SURFACE_FORMAT_A8B8G8R8, \n
102 //! CM_SURFACE_FORMAT_R32F, \n
103 //! CM_SURFACE_FORMAT_V8U8, \n
104 //! CM_SURFACE_FORMAT_P8, \n
105 //! CM_SURFACE_FORMAT_YUY2, \n
106 //! CM_SURFACE_FORMAT_A8, \n
107 //! CM_SURFACE_FORMAT_NV12, \n
108 //! CM_SURFACE_FORMAT_P010, \n
109 //! CM_SURFACE_FORMAT_UYVY, \n
110 //! CM_SURFACE_FORMAT_IMC3, \n
111 //! CM_SURFACE_FORMAT_411P, \n
112 //! CM_SURFACE_FORMAT_422H, \n
113 //! CM_SURFACE_FORMAT_422V, \n
114 //! CM_SURFACE_FORMAT_444P, \n
115 //! CM_SURFACE_FORMAT_YV12, \n
116 //! CM_SURFACE_FORMAT_R8_UINT, \n
117 //! CM_SURFACE_FORMAT_R16_UINT, \n
118 //! CM_SURFACE_FORMAT_P208 \n
119 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
120 //! is exceeded. The amount is the amount of the surfaces that
121 //! can co-exist. The amount can be obtained by querying the
122 //! cap CAP_SURFACE2D_COUNT.
123 //! \retval CM_FAILURE otherwise.
124 //! \note For planar surface, there is only one CmSurface2D instance,
125 //! no matter how many planes the surface may have.
126 //! The detail about how to access different planes in the kernel
127 //! code can be found in CM Language Spec, looking for read_plane
128 //! and write_plane.
129 CM_RT_API virtual int32_t CreateSurface2D(uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, CmSurface2D* &surface) = 0;
130
131 //! \brief Creates a CmSurface3D with given width, height, depth and
132 //! pixel format.
133 //! \details This function creates a surface in memory with a 3D layout.
134 //! User needs to provide width, height, depth and format.
135 //! \param [in] width
136 //! Surface width.
137 //! \param [in] height
138 //! Surface height.
139 //! \param [in] depth
140 //! Surface depth.
141 //! \param [in] format
142 //! Surface format.
143 //! \param [out] surface
144 //! Reference to the pointer to the CmSurface3D.
145 //! \retval CM_SUCCESS if the CmSurface3D is successfully created.
146 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
147 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
148 //! larger than CM_MAX_3D_SURF_WIDTH.
149 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
150 //! or larger than CM_MAX_3D_SURF_HEIGHT.
151 //! \retval CM_INVALID_DEPTH if width is less than CM_MIN_SURF_DEPTH or
152 //! larger than CM_MAX_3D_SURF_DEPTH.
153 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
154 //! supported. The supported formats can be obtained by
155 //! querying cap CAP_SURFACE3D_FORMAT_COUNT and
156 //! CAP_SURFACE3D_FORMATS, For now, only supports: \n
157 //! CM_SURFACE_FORMAT_X8R8G8B8, \n
158 //! CM_SURFACE_FORMAT_A8R8G8B8, \n
159 //! CM_SURFACE_FORMAT_A16B16G16R16. \n
160 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 3D
161 //! surface fails.
162 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 3D surfaces
163 //! is exceeded. The amount is the amount of the surfaces that
164 //! can co-exist. The amount can be obtained by querying the
165 //! cap CAP_SURFACE3D_COUNT.
166 //! \retval CM_FAILURE otherwise.
167 CM_RT_API virtual int32_t CreateSurface3D(uint32_t width, uint32_t height, uint32_t depth, CM_SURFACE_FORMAT format, CmSurface3D* &surface) = 0;
168
169 //! \brief Creates a CmSurface2D from an existing VA surface.
170 //! \details The application must have created the VA surface using the
171 //! same VA device as the one used to create the CmDevice.
172 //! The VA surface format should be within the supported
173 //! format set which can be obtained by querying cap
174 //! CAP_SURFACE2D_FORMAT_COUNT and CAP_SURFACE2D_FORMATS. The
175 //! surface must be lockable is you want to use
176 //! CmSurface2D::ReadSurface and CmSurface2D::WriteSurface.
177 //! \param [in] vaSurfaceId
178 //! Surface ID of the VA surface.
179 //! \param [out] surface
180 //! Reference to the pointer to the CmSurface2D.
181 //! \retval CM_SUCCESS if the CmSurface2D are successfully created.
182 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
183 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
184 //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2, or NV12
185 //! format, the width is odd.
186 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
187 //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format,
188 //! the height is odd.
189 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
190 //! supported. The supported formats can be obtained by
191 //! querying cap CAP_SURFACE2D_FORMAT_COUNT and
192 //! CAP_SURFACE2D_FORMATS. For now, the following formats are
193 //! supported: \n
194 //! CM_SURFACE_FORMAT_A8R8G8B8, \n
195 //! CM_SURFACE_FORMAT_X8R8G8B8, \n
196 //! CM_SURFACE_FORMAT_A8B8G8R8, \n
197 //! CM_SURFACE_FORMAT_R32F, \n
198 //! CM_SURFACE_FORMAT_V8U8, \n
199 //! CM_SURFACE_FORMAT_P8, \n
200 //! CM_SURFACE_FORMAT_YUY2, \n
201 //! CM_SURFACE_FORMAT_A8, \n
202 //! CM_SURFACE_FORMAT_NV12, \n
203 //! CM_SURFACE_FORMAT_P010, \n
204 //! CM_SURFACE_FORMAT_UYVY, \n
205 //! CM_SURFACE_FORMAT_IMC3, \n
206 //! CM_SURFACE_FORMAT_411P, \n
207 //! CM_SURFACE_FORMAT_422H, \n
208 //! CM_SURFACE_FORMAT_422V, \n
209 //! CM_SURFACE_FORMAT_444P, \n
210 //! CM_SURFACE_FORMAT_YV12, \n
211 //! CM_SURFACE_FORMAT_R8_UINT, \n
212 //! CM_SURFACE_FORMAT_R16_UINT, \n
213 //! CM_SURFACE_FORMAT_P208 \n
214 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
215 //! is exceeded. The amount is the amount of the surfaces that
216 //! can co-exist. The amount can be obtained by querying the
217 //! cap CAP_SURFACE2D_COUNT.
218 //! \retval CM_FAILURE otherwise.
219 //! \note This API is in Linux only.
220 CM_RT_API virtual int32_t CreateSurface2D(VASurfaceID vaSurfaceId, CmSurface2D* &surface) = 0;
221
222 //! \brief Creates an array of CmSurface2D type surfaces from an
223 //! existing array of VA surfaces.
224 //! \details Surface in the VA surface array must be created by the
225 //! same VA device as the one that created CmDevice. It is
226 //! application's responsibility to allocate memory for the
227 //! array of pointers to CmSurface2D. The VA surface format
228 //! should be within the supported format set which can be
229 //! obtained by querying cap CAP_SURFACE2D_FORMAT_COUNT and
230 //! CAP_SURFACE2D_FORMATS. The surface must be lockable is you
231 //! want to use CmSurface2D::ReadSurface and
232 //! CmSurface2D::WriteSurface.
233 //! \param [in] vaSurfaceId
234 //! Pointer to the array of surface ID of VA surfaces.
235 //! \param [in] surfaceCount
236 //! Array size.
237 //! \param [out] surfaceArray
238 //! Pointer to the array of pointers pointing to CmSurface2D
239 //! objects.
240 //! \retval CM_SUCCESS if all CmSurface2D objects are successfully
241 //! created.
242 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
243 //! \retval CM_FAILURE otherwise.
244 //! \note This API is in Linux only.
245 CM_RT_API virtual int32_t CreateSurface2D(VASurfaceID* vaSurfaceId, const uint32_t surfaceCount, CmSurface2D **surfaceArray) = 0;
246
247 //! \brief Destroys CmBuffer object.
248 //! \details This function destroys CmBuffer object. After the function
249 //! is called, it will return immediately without waiting. If
250 //! there is any Enqueue is being executed when this function
251 //! is called, the actual destroy will be postponed internally
252 //! by the runtime, and user doens't need to worry about it.
253 //! \param [in,out] buffer
254 //! Reference to the pointer pointing to CmBuffer, it will be
255 //! assigned to nullptr after destroy.
256 //! \retval CM_SUCCESS if CmBuffer is successfully destroyed.
257 //! \retval CM_FAILURE otherwise.
258 CM_RT_API virtual int32_t DestroySurface(CmBuffer* &buffer) = 0;
259
260 //! \brief Destroys CmSurface2D type surface.
261 //! \details This function destroys CmSurface2D object. After the function
262 //! is called, it will return immediately without waiting. If
263 //! there is any Enqueue is being executed when this function is
264 //! called, the actual destroy will be postponed internally by
265 //! the runtime, and user doens't need to worry about it. One
266 //! exception is that if the CmSurface2D was created by a third
267 //! party VA surface, user has to keep the VA surface until the
268 //! kernel using it finishes execution.
269 //! \param [in,out] surface2d
270 //! Reference to the pointer pointing to CmSurface2D. It will
271 //! be assigned to nullptr after destroy.
272 //! \retval CM_SUCCESS if CmSurface2D is successfully destroyed.
273 //! \retval CM_FAILURE otherwise.
274 CM_RT_API virtual int32_t DestroySurface( CmSurface2D* &surface2d) = 0;
275
276 //! \brief Destroys CmSurface3D object.
277 //! \details This function destroys CmSurface3D object. After the
278 //! function is called, it will return immediately without
279 //! waiting. If there is any Enqueue is being executed when this
280 //! function is called, the actual destroy will be postponed
281 //! internally by the runtime, and user doens't need to worry
282 //! about it.
283 //! \param [in,out] surface3d
284 //! Reference to the pointer pointing to CmSurface3D. It will
285 //! be assigned to nullptr after destroy.
286 //! \retval CM_SUCCESS if CmSurface3D is successfully destroyed.
287 //! \retval CM_FAILURE otherwise.
288 CM_RT_API virtual int32_t DestroySurface( CmSurface3D* &surface3d) = 0;
289
290 //! \brief Creates a task queue corresponding to the render context.
291 //! \details CmQueue is an in-order queue of tasks. Each task is
292 //! essentially a CmTask object containing kernels that are to
293 //! be run concurrently. Each kernel can be executed with
294 //! multiple threads. Trying to create a second CmQueue will
295 //! return an existing object.
296 //! \param [in,out] queue
297 //! Reference to the pointer to the CmQueue.
298 //! \retval CM_SUCCESS if the CmQueue is successfully created.
299 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
300 //! \retval CM_FAILURE otherwise.
301 CM_RT_API virtual int32_t CreateQueue(CmQueue* &queue) = 0;
302
303 //! \brief Creates a CmProgram object consisting of kernels loaded from
304 //! the commonISACode code.
305 //! \details Common ISA code is offline generated as a file with a .isa suffix
306 //! by the CM compiler when it is used to compile one or more
307 //! kernels. It contains ISA code common for all Intel platforms.
308 //! Just-In-Time (JIT) compilation of the common ISA code happens in
309 //! LoadProgram and generates platform specific ISA according to the
310 //! actaully platform where the application in running in hardware mode.
311 //! In the emulation mode JIT doesn't happen.
312 //! In the simulation mode JIT doesn't happen but paltform specfic
313 //! ISA need to be offline generated together with common ISA by
314 //! CM compiler and to be included in commonISACode.
315 //! How to generate common ISA and platform specific ISA can be
316 //! found in CM compiler manual.
317 //! \param [in] commonISACode
318 //! Pointer pointing to code in common ISA.
319 //! \param [in] size
320 //! Size in bytes of the common ISA code.
321 //! \param [in,out] program
322 //! Reference to the pointer to the CmProgram.
323 //! \param [in] options
324 //! JIT options for all kernels in the code. This argument
325 //! is optional. Size of options should be no more than 512
326 //! (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the null
327 //! terminator. There is one option available currently: \n
328 //! "nojitter" -- Use this option to completely disable jitter
329 //! from occurring. NOTE: "/Qxcm_jit_tartget=%GEN_ARCH%"
330 //! flag must be set during offline compilation if "nojitter"
331 //! is set in hardware mode.
332 //! In simulation and emulation mode, this option is ignored.
333 //! \retval CM_SUCCESS if the CmProgram is successfully created.
334 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
335 //! \retval CM_INVALID_ARG_VALUE if invalid input parameters.
336 //! \retval CM_INVALID_GENX_BINARY if the GEN binary is not matched with
337 //! actual running platform in "nojitter" mode.
338 //! \retval CM_JIT_COMPILE_FAILURE if JIT compile of the common ISA
339 //! code fails.
340 //! \retval CM_INVALID_KERNEL_SPILL_CODE if kernel has spill code and
341 //! devcie's scratch memory space is disabled in
342 //! CreateCmDeviceEx.
343 //! \retval CM_FAILURE otherwise.
344 CM_RT_API virtual int32_t LoadProgram(void* commonISACode, const uint32_t size, CmProgram*& program, const char* options = nullptr) = 0;
345
346 //! \brief Creates a CmKernel object from the CmProgram object.
347 //! \details A Cmprogram can contains multiple kernels.
348 //! The size of all arguments of a kernel should be no more than
349 //! CAP_ARG_SIZE_PER_KERNEL byte. The number of all kernel
350 //! arguments should be no more than CAP_ARG_COUNT_PER_KERNEL.
351 //! The size of kernel binary should be no more than
352 //! CAP_KERNEL_BINARY_SIZE bytes. The kernelName should be no
353 //! more than 256 (CM_MAX_KERNEL_NAME_SIZE_IN_BYTE) bytes
354 //! including the null terminator.
355 //! \param [in] program
356 //! CmProgram object from which the kernel is created.
357 //! \param [in] kernelName
358 //! CM kernel function (genx_main) name. A CM_KERNEL_FUNCTION
359 //! macro MUST be used to specify this argument.
360 //! \param [in,out] kernel
361 //! Reference to the pointer to the CmKernel object.
362 //! \param [in] options
363 //! JIT options for this specific kernel, overwriting the JIT
364 //! options specified for all kernels in the CmProgram. This
365 //! argument is optional. Size of options should be no more
366 //! than 512 (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the
367 //! null terminator. No options available for now.
368 //! \retval CM_SUCCESS if the CmKernel is successfully created or
369 //! returned.
370 //! \retval CM_INVALID_ARG_VALUE if program is an invalid pointer.
371 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
372 //! \retval CM_EXCEED_KERNEL_ARG_AMOUNT if the argument number of the
373 //! kernel fucntion is larger than CAP_ARG_COUNT_PER_KERNEL.
374 //! \retval CM_EXCEED_KERNEL_ARG_SIZE_IN_BYTE if the argument size of
375 //! the kernel fucntion is larger than CAP_ARG_SIZE_PER_KERNEL.
376 //! \retval CM_FAILURE otherwise.
377 CM_RT_API virtual int32_t CreateKernel( CmProgram* program, const char* kernelName, CmKernel* & kernel, const char* options = nullptr) = 0;
378
379 //! \brief Creates a CmKernel object in emulation mode.
380 //! \details The size of all kernel arguments should be no more than
381 //! CAP_ARG_SIZE_PER_KERNEL byte. The number of all kernel
382 //! arguments should be no more than CAP_ARG_COUNT_PER_KERNEL.
383 //! The size of kernel binary should be no more than
384 //! CAP_KERNEL_BINARY_SIZE bytes. The kernelName should be no
385 //! more than 256 (CM_MAX_KERNEL_NAME_SIZE_IN_BYTE) bytes
386 //! including the null terminator.
387 //! \param [in] program
388 //! CmProgram from which the kernel is created.
389 //! \param [in] kernelName
390 //! CM kernel function (genx_main) name emulation mode also
391 //! needs a pointer to the kernel function. A
392 //! CM_KERNEL_FUNCTION macro MUST be used to specify this
393 //! argument to accommodate emulation modes.
394 //! \param [in] fncPnt
395 //! This API is for emulation mode only, and this parameter
396 //! is not necessarily controlled by user because the macro
397 //! CM_KERNEL_FUNCTION will be used to set this parameter.
398 //! \param [in,out] kernel
399 //! Reference to the pointer to the CmKernel object.
400 //! \param [in] options
401 //! JIT options for this specific kernel, overwriting the JIT
402 //! options specified for all kernels in the CmProgram. This
403 //! argument is optional. Size of options should be no more
404 //! than 512 (CM_MAX_OPTION_SIZE_IN_BYTE) bytes including the
405 //! null terminator. No options available for now.
406 //! \retval CM_SUCCESS if the CmKernel is successfully created or
407 //! returned.
408 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
409 //! \retval CM_EXCEED_KERNEL_ARG_AMOUNT if the argument number of the
410 //! kernel fucntion is larger than CAP_ARG_COUNT_PER_KERNEL.
411 //! \retval CM_EXCEED_KERNEL_ARG_SIZE_IN_BYTE if the argument size of
412 //! the kernel fucntion is larger than CAP_ARG_SIZE_PER_KERNEL.
413 //! \retval CM_FAILURE otherwise.
414 CM_RT_API virtual int32_t CreateKernel(CmProgram* program, const char* kernelName, const void * fncPnt, CmKernel* & kernel, const char* options = nullptr) = 0;
415
416 //! \brief Creates a CmSampler object.
417 //! \details This function creates a 3D sampler state object used to sample
418 //! a 2D surface.
419 //! \param [in] sampleState
420 //! Const reference to a CM_SAMPLER_STATE specifying the
421 //! characteristics of the sampler to be created. The structure
422 //! is defined below.
423 //! \param [out] sampler
424 //! Reference to the pointer to the CmSampler object.
425 //! \retval CM_SUCCESS if the CmSampler is successfully created.
426 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
427 //! \retval CM_EXCEED_SAMPLER_AMOUNT if maximum amount of sampler is
428 //! exceeded. The amount is the amount of the sampler that can
429 //! co-exist. The amount can be obtained by querying the cap
430 //! CAP_SAMPLER_COUNT.
431 //! \retval CM_FAILURE otherwise.
432 //! \note typedef struct _CM_SAMPLER_STATE\n
433 //! {\n
434 //! CM_TEXTURE_FILTER_TYPE minFilterType;\n
435 //! CM_TEXTURE_FILTER_TYPE magFilterType;\n
436 //! CM_TEXTURE_ADDRESS_TYPE addressU;\n
437 //! CM_TEXTURE_ADDRESS_TYPE addressV;\n
438 //! CM_TEXTURE_ADDRESS_TYPE addressW;\n
439 //! } CM_SAMPLER_STATE;\n
440 //!
441 //! For now, only linear and anisotropic filter types are
442 //! supported for hardware and simulation modes. For emulation
443 //! mode, linear filter type is supported. Wrap, mirror, and
444 //! clamp address types are supported in hardware and simulation modes.
445 //! only clamp address type is supported in emulation mode.
446 CM_RT_API virtual int32_t CreateSampler(const CM_SAMPLER_STATE &sampleState, CmSampler* &sampler) = 0;
447
448 //! \brief Destroy a CmKernel.
449 //! \details A CmKernel that is not destroyed by calling this function
450 //! will be destroyed when the CmDevice is destroyed.
451 //! \param [in,out] kernel
452 //! CmKernel object to be destroyed. It will be assigned to
453 //! nullptr once the fuction is return.
454 //! \retval CM_SUCCESS if the CmKernel is successfully destroyed.
455 //! \retval CM_FAILURE otherwise.
456 CM_RT_API virtual int32_t DestroyKernel(CmKernel* &kernel) = 0;
457
458 //! \brief Destroys a CmSampler.
459 //! \details A CmSampler that is not destroyed by calling this function
460 //! will be destroyed when the CmDevice is destroyed.
461 //! \param [in,out] sampler
462 //! A reference to the CmSampler pointer.
463 //! \retval CM_SUCCESS if the CmSampler is successfully destroyed.
464 //! \retval CM_FAILURE otherwise.
465 CM_RT_API virtual int32_t DestroySampler(CmSampler* &sampler) = 0;
466
467 //! \brief Destroys a CmProgram.
468 //! \details A CmProgram that is not destroyed by calling this function
469 //! will be destroyed when the CmDevice is destroyed.
470 //! \param [in,out] program
471 //! Reference to the pointer to the CmProgram. It will be assigned to
472 //! nullptr once the fuction is return.
473 //! \retval CM_SUCCESS if the CmProgram is successfully destroyed.
474 //! \retval CM_FAILURE otherwise.
475 CM_RT_API virtual int32_t DestroyProgram(CmProgram* &program) = 0;
476
477 //! \brief Destroys a CmThreadSpace instance.
478 //! \details A CmThreadSpace that is not destroyed by calling this
479 //! function will be destroyed when the CmDevice is destroyed.
480 //! \param [in,out] threadSpace
481 //! Reference to the pointer to the CmThreadSpace. It will be
482 //! assigned to nullptr once the fuction is return.
483 //! \retval CM_SUCCESS if the CmThreadSpace is successfully destroyed.
484 //! \retval CM_FAILURE if the input is nullptr or not valid.
485 CM_RT_API virtual int32_t DestroyThreadSpace( CmThreadSpace* &threadSpace) = 0;
486
487 //!
488 //! \brief Creates a CmTask object
489 //! \details This object is a container for one or multiple CmKernel objects, and used
490 //! to enqueue the kernels for concurrent execution.
491 //! \param [out] task Reference to the pointer to the CmTask
492 //! \retval CM_SUCCESS if the CmTask is successfully created
493 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory
494 //!
495 CM_RT_API virtual int32_t CreateTask(CmTask* &task) = 0;
496
497 //!
498 //! \brief Destroy a CmTask object
499 //! \details A CmTask that is not destroyed by calling this
500 //! function will be destroyed when the CmDevice is destroyed
501 //! \param [in, out] task Reference to the pointer to the CmTask.
502 //! \retval CM_SUCCESS if the CmTaskis successfully destroyed
503 //! \retval CM_FAILURE otherwise
504 //!
505 CM_RT_API virtual int32_t DestroyTask(CmTask* &task)=0;
506
507 //!
508 //! \brief This function can be used to get HW capability.
509 //! \details By calling this function, user can get the hardware capabilites
510 //! of running platform.
511 //! \param [in] capName Name of cap to query
512 //! \param [out] capValueSize Reference to the size in bytes of the Cap
513 //! value. On entry application should set this to the size
514 //! of memory allocated for the cap value. Application should
515 //! make sure this size is large enough to hold the Cap value
516 //! requested. On return from this function the actual size of
517 //! cap value is returned.
518 //! \param [out] capValue Pointer pointing to memory where the
519 //! cap value should be returned
520 //! \retval CM_SUCCESS if the input capValueSize equals or
521 //! is larger than required Cap size and Cap Value
522 //! is successfully returned
523 //! \retval CM_FAILURE otherwise
524 //!
525 //! \details
526 //! <table>
527 //! <tr>
528 //! <th>Cap Name</th>
529 //! <th>Size in bytes </th>
530 //! <th>Type of Value</th>
531 //! <th>Description</th>
532 //! </tr>
533 //! <tr>
534 //! <td>CAP_KERNEL_COUNT_PER_TASK</td>
535 //! <td>4</td>
536 //! <td>uint32_t</td>
537 //! <td>Maximum number of kernels that can be enqueued in one task</td>
538 //! </tr>
539 //! <tr>
540 //! <td> CAP_KERNEL_BINARY_SIZE</td>
541 //! <td>4</td>
542 //! <td>uint32_t</td>
543 //! <td> Maximum kernel binary size in bytes</td>
544 //! </tr>
545 //! <tr>
546 //! <td> CAP_SAMPLER_COUNT</td>
547 //! <td>4</td>
548 //! <td>uint32_t</td>
549 //! <td> Maximum number of samplers that can co-exist at any time
550 //! in a CmDevice</td>
551 //! </tr>
552 //! <tr>
553 //! <td>CAP_SAMPLER_COUNT_PER_KERNEL </td>
554 //! <td>4</td>
555 //! <td>uint32_t</td>
556 //! <td>Maximum number of samplers that one kernel can use</td>
557 //! </tr>
558 //! <tr>
559 //! <td>CAP_BUFFER_COUNT </td>
560 //! <td>4</td>
561 //! <td>uint32_t</td>
562 //! <td>Maximum number of CmBuffer/CmBufferUP that can co - exist at any time </td>
563 //! </tr>
564 //! <tr>
565 //! <td> CAP_SURFACE2D_COUNT</td>
566 //! <td>4</td>
567 //! <td>uint32_t</td>
568 //! <td>Maximum number of CmSurface2D that can co-exist at
569 //! any time </td>
570 //! </tr>
571 //! <tr>
572 //! <td>CAP_SURFACE3D_COUNT </td>
573 //! <td>4</td>
574 //! <td>uint32_t</td>
575 //! <td>Maximum number of CmSurface3D that can co-exist at any
576 //! time in a CmDevice </td>
577 //! </tr>
578 //! <tr>
579 //! <td>CAP_SURFACE_COUNT_PER_KERNEL </td>
580 //! <td>4</td>
581 //! <td>uint32_t</td>
582 //! <td>Maximum number of surfaces (including 1D, 2D and 3D) that
583 //! one kernel can use </td>
584 //! </tr>
585 //! <tr>
586 //! <td>CAP_ARG_COUNT_PER_KERNEL </td>
587 //! <td>4</td>
588 //! <td>uint32_t</td>
589 //! <td>Maximum number of arguments that a kernel can have </td>
590 //! </tr>
591 //! <tr>
592 //! <td>CAP_ARG_SIZE_PER_KERNEL </td>
593 //! <td>4</td>
594 //! <td>uint32_t</td>
595 //! <td>Maximum size of all arguments that a kernel can have </td>
596 //! </tr>
597 //! <tr>
598 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_TASK </td>
599 //! <td>4</td>
600 //! <td>uint32_t</td>
601 //! <td>Maximum number of threads that all kernels of a task can
602 //! run, it's only used for media object usage </td>
603 //! </tr>
604 //! <tr>
605 //! <td>CAP_HW_THREAD_COUNT </td>
606 //! <td>4</td>
607 //! <td>uint32_t</td>
608 //! <td>Maximum number of threads that HW can run in parallel.This
609 //! indicates hardware parallelism and is hence one
610 //! of the factors indicating performance of the target machine </td>
611 //! </tr>
612 //! <tr>
613 //! <td>CAP_SURFACE2D_FORMAT_COUNT </td>
614 //! <td>4</td>
615 //! <td>uint32_t</td>
616 //! <td>Number of surface formats supported for CmSurface2D creation </td>
617 //! </tr>
618 //! <tr>
619 //! <td>CAP_SURFACE2D_FORMATS </td>
620 //! <td>sizeof(VA_CM_FORMAT) * CAP_SURFACE2D_FORMAT_COUNT</td>
621 //! <td>Array of VA_CM_FORMAT</td>
622 //! <td>All Libva formats supported to create CmSurface2D </td>
623 //! </tr>
624 //! <tr>
625 //! <td>CAP_SURFACE3D_FORMAT_COUNT </td>
626 //! <td>sizeof(VA_CM_FORMAT) * CAP_SURFACE3D_FORMAT_COUNT</td>
627 //! <td>Array of VA_CM_FORMAT</td>
628 //! <td>Number of Libva formats supported for CmSurface3D creation </td>
629 //! </tr>
630 //! <tr>
631 //! <td>CAP_SURFACE3D_FORMATS </td>
632 //! <td>sizeof(VA_CM_FORMAT) * CAP_SURFACE3D_FORMAT_COUNT</td>
633 //! <td>Array of VA_CM_FORMAT</td>
634 //! <td>All Libva formats supported to create CmSurface3D </td>
635 //! </tr>
636 //! <tr>
637 //! <td>CAP_GPU_PLATFORM </td>
638 //! <td>4</td>
639 //! <td>uint32_t</td>
640 //! <td>Return GPU platform as an enum of type GPU_PLATFORM
641 //! (PLATFORM_INTEL_BDW, PLATFORM_INTEL_SKL, etc) </td>
642 //! </tr>
643 //! <tr>
644 //! <td>CAP_GT_PLATFORM </td>
645 //! <td>4</td>
646 //! <td>uint32_t</td>
647 //! <td>Return GT platform (SKU) as an enum of type GPU_GT_PLATFORM
648 //! (PLATFORM_INTEL_GT1, PLATFORM_INTEL_GT2, etc) </td>
649 //! </tr>
650 //! <tr>
651 //! <td>CAP_MIN_FREQUENCY </td>
652 //! <td>4</td>
653 //! <td>uint32_t</td>
654 //! <td>Returns the minimum frequency of the GPU as an integer in MHz
655 //! </td>
656 //! </tr>
657 //! <tr>
658 //! <td>CAP_MAX_FREQUENCY </td>
659 //! <td>4</td>
660 //! <td>uint32_t</td>
661 //! <td>Returns the maximum frequency of the GPU as an integer in MHz
662 //! </td>
663 //! </tr>
664 //! <tr>
665 //! <td>CAP_GPU_CURRENT_FREQUENCY </td>
666 //! <td>4</td>
667 //! <td>uint32_t</td>
668 //! <td>Return the current frequency of the GPU as an integer
669 //! in MHz </td>
670 //! </tr>
671 //! <tr>
672 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_TASK_NO_THREAD_ARG </td>
673 //! <td>4</td>
674 //! <td>uint32_t</td>
675 //! <td>Returns the maximum thread count on media object without
676 //! per - thread argument </td>
677 //! </tr>
678 //! <tr>
679 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_MEDIA_WALKER </td>
680 //! <td>4</td>
681 //! <td>uint32_t</td>
682 //! <td>Returns the maximum thread count in media walker usage </td>
683 //! </tr>
684 //! <tr>
685 //! <td>CAP_USER_DEFINED_THREAD_COUNT_PER_THREAD_GROUP </td>
686 //! <td>4</td>
687 //! <td>uint32_t</td>
688 //! <td>Returns the maximum thread count per thread group in
689 //! GPGPU walker usage </td>
690 //! </tr>
691 //! <tr>
692 //! <td>CAP_SURFACE2DUP_COUNT </td>
693 //! <td>4</td>
694 //! <td>uint32_t</td>
695 //! <td>Maximum number of CmSurface2DUP that can
696 //! co - exist at any time </td>
697 //! </tr>
698 //! <tr>
699 //! <td>CAP_PLATFORM_INFO </td>
700 //! <td>sizeof(CM_PLATFORM_INFO)</td>
701 //! <td>CM_PLATFORM_INFO</td>
702 //! <td>EU information, like number of slice, number of subslice,
703 //! EU number per subslice, etc. See CM_PLATFORM_INFO. </td>
704 //! </tr>
705 //! <tr>
706 //! <td>CAP_MAX_BUFFER_SIZE </td>
707 //! <td>4</td>
708 //! <td>uint32_t</td>
709 //! <td>Returns maximum size in bytes for CmBuffer and CmBufferUP. </td>
710 //! </tr>
711 //! </table>
712 CM_RT_API virtual int32_t GetCaps(CM_DEVICE_CAP_NAME capName, size_t& capValueSize, void *capValue) = 0;
713
714 //! \brief Creates a CmThreadSpace object.
715 //! \details CmThreadSpace is a 2D space.Each unit is notated as
716 //! a pair of X/Y coordinates, which is in the range of [0, width -1]
717 //! or [0, heigh-1]. A thread space can define a dependency or no
718 //! dependency. A thread space can be used as per-task thread space
719 //! by passing it in Enqueue(), or be used as per-kernel thread space
720 //! by calling CmKernel::AssociateThreadSpace() API. Please
721 //! refer to "Host programming guide" for detailed thread space usages.
722 //! \param [in] width
723 //! Thread space width.
724 //! \param [in] height
725 //! Thread space height.
726 //! \param [out] threadSpace
727 //! Reference to pointer to CmThreadSpace object to be created.
728 //! \retval CM_SUCCESS if the CmThreadSpace is successfully created.
729 //! \retval CM_INVALID_THREAD_SPACE if the width or(and) height are
730 //! \retval invalid values (0 or exceeds maximum size).
731 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
732 //! \retval CM_FAILURE otherwise.
733 //! \note The maximum width/height allowed when using media walker is
734 //! 511 for pre-SKL and 2047 for SKL+. For media object the
735 //! maximum width/height allowed is 512.
736 CM_RT_API virtual int32_t CreateThreadSpace( uint32_t width, uint32_t height, CmThreadSpace* &threadSpace) = 0;
737
738 //! \brief Creates a CmBufferUP object.
739 //! \details This API creates a CmBufferUP object on top of the UP
740 //! (User Provided) system memory with specificed size in bytes.
741 //! The UP memory starting address must be page (4K Bytes) aligned.
742 //! \param [in] size
743 //! BufferUP size in bytes, the valid range is:
744 //! > CM_MIN_SURF_WIDTH, and < CM_MAX_1D_SURF_WIDTH.
745 //! \param [in] sysMem
746 //! Pointer to the system memory.
747 //! \param [out] buffer
748 //! Reference to the pointer to the CmBufferUP.
749 //! \retval CM_SUCCESS if the CmBufferUP is successfully created.
750 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
751 //! surface fails.
752 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
753 //! larger than CM_MAX_1D_SURF_WIDTH.
754 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr.
755 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
756 //! is exceeded. The amount is the amount of the surfaces
757 //! that can co-exist. The amount can be obtained by
758 //! querying the cap CAP_BUFFER_COUNT.
759 //! \retval CM_FAILURE otherwise.
760 //! \note Application can access the memory though the memory
761 //! point from CPU; can also access the
762 //! buffer created upon the same memory from GPU. It is
763 //! application's responsibility to make
764 //! sure accesses from both sides are not overlapped.
765 //! \note Refer to "MDF Host Programming Guide" for detailed usages.
766 CM_RT_API virtual int32_t CreateBufferUP(uint32_t size, void *sysMem, CmBufferUP* &buffer)=0;
767
768 //! \brief Destroys CmBufferUP object.
769 //! \details The UP (User Provided) memory is still existing after the
770 //! CmBufferUP object is destroyed.
771 //! \param [in, out] buffer
772 //! Reference to the pointer pointing to CmBufferUP. It will be
773 //! assigned to nullptr once the function is returned.
774 //! \retval CM_SUCCESS if CmBufferUP is successfully destroyed.
775 //! \retval CM_FAILURE otherwise.
776 CM_RT_API virtual int32_t DestroyBufferUP(CmBufferUP* &buffer) = 0;
777
778 //! \brief Gets Surface2D allocation information by given width,
779 //! height, and format.
780 //! \details Gets necessary information in order to create and use
781 //! CmSurface2DUP.
782 //! To create CmSurface2DUP, user needs to allocated such
783 //! amount of system memory which equals to
784 //! or larger than physical size returned here. When
785 //! accessing the system memory, the user needs be
786 //! aware about pitch, which is equal to (pixel_width *
787 //! byte_per_pixel + necessary_padding).
788 //! \param [in] width
789 //! Width in pixel.
790 //! \param [in] height
791 //! height in pixel.
792 //! \param [in] format
793 //! pixel format.
794 //! \param [out] pitch
795 //! Reference to returned pitch.
796 //! \param [out] physicalSize
797 //! Reference to returned physical size.
798 //! \retval CM_SUCCESS always
799 CM_RT_API virtual int32_t GetSurface2DInfo( uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, uint32_t & pitch, uint32_t & physicalSize)= 0;
800
801 //! \brief Creates a CmSurface2DUP object.
802 //! \details Creates a CmSurface2DUP in UP (User Provided) system memory
803 //! with given surface width, height in pixel, and format.
804 //! The UP system memory must be page (4K Bytes) aligned.
805 //! The size of the system memory must larger than or equal to
806 //! the size return by GetSurface2DInfo().
807 //! \param [in] width
808 //! Width in pixel.
809 //! \param [in] height
810 //! Height in pixel.
811 //! \param [in] format
812 //! Format.
813 //! \param [in] sysMem
814 //! Reference to the pointer to the system memory which is CPU
815 //! accessible.
816 //! \param [out] surface
817 //! Reference to the pointer to the CmSurface2DUP.
818 //! \retval CM_SUCCESS if the CmSurface2DUPis successfully created.
819 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr.
820 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
821 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
822 //! larger than CM_MAX_2D_SURF_WIDTH, or for YUY2 or NV12
823 //! format, the width is odd.
824 //! \retval CM_INVALID_HEIGHT if height is less than CM_MIN_SURF_HEIGHT
825 //! or larger than CM_MAX_2D_SURF_HEIGHT, or for NV12 format,
826 //! the height is odd.
827 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not
828 //! supported. The supported formats can be obtained by
829 //! querying cap CAP_SURFACE2D_FORMAT_COUNT
830 //! and CAP_SURFACE2D_FORMATS.
831 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
832 //! is exceeded. The amount is the amount of the surfaces that
833 //! can co-exist. The amount can be obtained by
834 //! querying the cap CAP_SURFACE2D_COUNT.
835 //! \retval CM_SURFACE_ALLOCATION_FAILURE if allocation is failed.
836 //! \retval CM_FAILURE otherwise.
837 //! \note Application can access the memory though the memory point
838 //! returned from CPU; can also access the surface created
839 //! upon the same memory from GPU. It is application's
840 //! responsibility to make sure accesses from both sides are
841 //! not overlapped. When accessing the system memory from CPU,
842 //! the user needs to be aware about pitch, which is equal to
843 //! (pixel_width * byte_per_pixel + necessary_padding).
844 //! \note Refer to the CmSurface2DUP class for member APIs, and
845 //! 'MDF runtime host programming guide' for usages.
846 CM_RT_API virtual int32_t CreateSurface2DUP( uint32_t width, uint32_t height, CM_SURFACE_FORMAT format, void* sysMem, CmSurface2DUP* &surface)= 0;
847
848 //! \brief Destroys CmSurface2DUP surface.
849 //! \details The UP (User Provided) memory is still existing after the
850 //! CmSurface2DUP object is destroyed.
851 //! \param [in] surface
852 //! Reference to the pointer pointing to CmSurface2DUP. It will
853 //! be assigned to nullptr once this function is returned.
854 //! \retval CM_SUCCESS if CmSurface2DUPis successfully destroyed.
855 //! \retval CM_FAILURE otherwise.
856 CM_RT_API virtual int32_t DestroySurface2DUP( CmSurface2DUP* & surface) = 0;
857
858 //! \brief Creates a VME surface for AVC messages in kernel.
859 //! \details Creates a VME surface by using the given 2D surfaces:
860 //! the current frame, the forward frames and, the backward
861 //! frames. The last two can be nullptr if not used. The function
862 //! indicates these 2D surfaces are used for VME; no extra
863 //! surface is actually created. A SurfaceIndex object is created
864 //! instead, which is passed to CM kernel function (genx_main)
865 //! as argument to indicate the frame surface. Please see VME
866 //! examples in "MDF Host Programming Guide" document and CM
867 //! language specification for details.
868 //! \param [in] currentSurface
869 //! Pointer to current surface (can't be nullptr).
870 //! \param [in] forwardSurfaceArray
871 //! Array of forward surfaces (can be nullptr).
872 //! \param [in] backwardSurfaceArray
873 //! Array of backward surfaces (can be nullptr).
874 //! \param [in] surfaceCountForward
875 //! Count of forward surfaces, up to 16 forward surfaces can be
876 //! used.
877 //! \param [in] surfaceCountBackward
878 //! Count of backward surfaces, up to 16 backward surfaces can
879 //! be used.
880 //! \param [out] vmeSurfaceIndex
881 //! Reference to pointer to SurfaceIndex object to be created.
882 //! \retval CM_SUCCESS if the SurfaceIndex is successfully created.
883 //! \retval CM_NULL_POINTER if currentSurface is nullptr.
884 //! \retval CM_INVALID_ARG_VALUE if any parameter is not valid.
885 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
886 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of VME surfaces
887 //! is exceeded. The amount is the amount of VME surfaces that
888 //! can co-exist. The amount can be obtained by querying the
889 //! cap CAP_VME_SURFACE_COUNT.
890 //! \retval CM_FAILURE otherwise.
891 //! \note This can be used for all Gen7_5 and plus platforms.
892 CM_RT_API virtual int32_t CreateVmeSurfaceG7_5 ( CmSurface2D* currentSurface, CmSurface2D** forwardSurfaceArray, CmSurface2D** backwardSurfaceArray, const uint32_t surfaceCountForward, const uint32_t surfaceCountBackward, SurfaceIndex* & vmeSurfaceIndex )=0;
893
894 //! \brief Destroy a VME surface object.
895 //! \details Any VME surface not destroyed by calling this function
896 //! explicitly will be destroyed when CmDevice is destroyed.
897 //! \param [in] vmeSurfaceIndex
898 //! Pointer to the SurfaceIndex of the VME surface. It will be
899 //! assigned to nullptr once destroy is done.
900 //! \retval CM_SUCCESS if the VME surface is successfully destroyed.
901 //! \retval CM_FAILURE otherwise.
902 //! \note This can be used for all Gen7_5 and plus platforms.
903 CM_RT_API virtual int32_t DestroyVmeSurfaceG7_5( SurfaceIndex* &vmeSurfaceIndex) = 0;
904
905 //! \brief Creates a CmSampler8x8 object.
906 //! \param [in] samplerDescriptor
907 //! Const reference to a CM_SAMPLER_8X8_DESCR specifying the
908 //! characteristics of the Sampler8x8 state to be created.
909 //! Currently, AVS, VA Convolve and VA Misc( including MinMax
910 //! Filter/Erode/Dilate ) states are supported.
911 //! \param [out] sampler
912 //! Reference to the pointer to the CmSampler8x8 object.
913 //! \retval CM_SUCCESS if the CmSampler8x8is successfully created.
914 //! \retval CM_INVALID_ARG_VALUE wrong sampler8x8 type.
915 //! \retval CM_EXCEED_SAMPLER_AMOUNT if the co-existed sampler exceeds
916 //! maximum count which can be queried by CAP_SAMPLER_COUNT cap.
917 CM_RT_API virtual int32_t CreateSampler8x8(const CM_SAMPLER_8X8_DESCR &samplerDescriptor,
918 CmSampler8x8* &sampler) = 0;
919
920 //! \brief Destroys a CmSampler8x8 object.
921 //! \details A CmSampler8x8 which is not destroyed by calling this
922 //! function will be destroyed when the CmDevice is destroyed.
923 //! \param [in, out] sampler
924 //! Reference to a sampler of CmSampler8x8. It will be assigned
925 //! to nullptr once destroy is done.
926 //! \retval CM_SUCCESS if the CmSampler8x8 is successfully destroyed.
927 //! \retval CM_FAILURE otherwise.
928 CM_RT_API virtual int32_t DestroySampler8x8(CmSampler8x8* &sampler) = 0;
929
930 //! \brief Creates a CmSampler8x8 surface.
931 //! \details Creates a CmSampler8x8 surface by using the given 2D surface.
932 //! The function indicates the 2D surface is used for sampler
933 //! 8x8; no extra surface is actually created. A SurfaceIndex
934 //! object is created instead, which is passed to CM kernel
935 //! function (genx_main) as argument to indicate the surface
936 //! for sampler 8x8.
937 //! \param [in] surface2d
938 //! Pointer to CmSurface2D.
939 //! \param [out] surfaceIndex
940 //! Reference to pointer to SurfaceIndex.
941 //! \param [in] surfaceType
942 //! Enumeration data type of CM_SAMPLER8x8_SURFACE.
943 //! \param [in] addressControl
944 //! Enumeration data type of CM_SURFACE_ADDRESS_CONTROL_MODE.
945 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
946 //! created.
947 //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too many co-existed
948 //! surfaces and exceed the maximum number. Destroying some
949 //! unused surfaces could solve this error.
950 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory
951 //! \retval CM_FAILURE otherwise.
952 CM_RT_API virtual int32_t CreateSampler8x8Surface(
953 CmSurface2D *surface2d,
954 SurfaceIndex* &surfaceIndex,
955 CM_SAMPLER8x8_SURFACE surfaceType = CM_VA_SURFACE,
956 CM_SURFACE_ADDRESS_CONTROL_MODE addressControl = CM_SURFACE_CLAMP) = 0;
957
958 //! \brief Destroys a CmSampler8x8 surface.
959 //! \details A CmSampler8x8 surface which is not destroyed by calling
960 //! this function will be destroyed when the CmDevice is
961 //! destroyed.
962 //! \param [in] surfaceIndex
963 //! Reference to SurfaceIndex. It will be assigned to nullptr
964 //! once destroy is done.
965 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
966 //! destroyed.
967 //! \retval CM_FAILURE otherwise.
968 CM_RT_API virtual int32_t DestroySampler8x8Surface(SurfaceIndex* &surfaceIndex) = 0;
969
970 //! \brief Creates a 2-dimensional thread group space object.
971 //! \details This function creates a thread group space specified by the
972 //! height and width dimensions of the group space, and the
973 //! height and width dimensions of the thread space within a
974 //! group. This information is used to execute a kernel in GPGPU pipe
975 //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf).
976 //! Relevant sample code is shown in "MDF Host Programming Guide"
977 //! \param [in] threadSpaceWidth
978 //! width in unit of threads of each thread group.
979 //! \param [in] threadSpaceHeight
980 //! height in unit of threads of each thread group.
981 //! \param [in] groupSpaceWidth
982 //! width in unit of groups of thread group space.
983 //! \param [in] groupSpaceHeight
984 //! height in unit of groups of thread group space.
985 //! \param [out] threadGroupSpace
986 //! Reference to the pointer to CmThreadGroupSpace object to be
987 //! created.
988 //! \retval CM_SUCCESS if the CmThreadGroupSpace is successfully
989 //! created.
990 //! \retval CM_INVALID_THREAD_GROUP_SPACE if any input is 0 or the
991 //! threadSpaceWidth is more than MAX_THREAD_SPACE_WIDTH_PERGROUP,
992 //! or the threadSpaceHeight is more than
993 //! MAX_THREAD_SPACE_HEIGHT_PERGROUP.
994 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
995 //! \retval CM_FAILURE otherwise.
996 //! \note The total thread count is width*height*grpWidth*grpHeight.
997 //! CmKernel::SetThreadCount() calling is not necessary in this
998 //! GPGPU working mode. Currently, it's only used for SLM
999 //! enabled kernels. See also CreateThreadGroupSpaceEx() API which
1000 //! specifies a 3-dimensional thread group space with width, height
1001 //! and depth.
1002 CM_RT_API virtual int32_t CreateThreadGroupSpace(
1003 uint32_t threadSpaceWidth,
1004 uint32_t threadSpaceHeight,
1005 uint32_t groupSpaceWidth,
1006 uint32_t groupSpaceHeight,
1007 CmThreadGroupSpace* &threadGroupSpace) = 0;
1008
1009 //! \brief Destroys the created thread group space object.
1010 //! \details Caller provides the reference of thread group space pointer
1011 //! \param [in] threadGroupSpace
1012 //! Pointer to a CmThreadGroupSpace. It will be assigned to
1013 //! nullptr once destroy is done.
1014 //! \retval CM_SUCCESS if the CmThreadGroupSpace pointer is
1015 //! successfully destroyed.
1016 //! \note User can call this API to explicitly destroy
1017 //! CmThreadGroupSpace instance, otherwise, DestroyCmDevice()
1018 //! takes care of all of such instances release.
1019 CM_RT_API virtual int32_t DestroyThreadGroupSpace(CmThreadGroupSpace* &threadGroupSpace) = 0;
1020
1021 //! \brief Sets the configuration for L3 cache.
1022 //! \details This API allows users to configure L3 cach by themselves.
1023 //! \param [in] registerValues
1024 //! L3ConfigRegisterValues contains the values of L3 control
1025 //! registers. The registers are different from platform to
1026 //! platform.\n
1027 //! struct L3ConfigRegisterValues \n
1028 //! { \n
1029 //! \t unsigned int config_register0; \n
1030 //! \t unsigned int config_register1; \n
1031 //! \t unsigned int config_register2; \n
1032 //! \t unsigned int config_register3; \n
1033 //! }; \n
1034 //! \retval CM_SUCCESS if the L3 configuration pointer is set correctly.
1035 //! \retval CM_FAILURE if the platform does not support L3 or L3
1036 //! configuration failed to be set.
1037 //! \note This function is implemented for both hardware mode and
1038 //! simulation mode.
1039 CM_RT_API virtual int32_t
1040 SetL3Config(const L3ConfigRegisterValues *registerValues) = 0;
1041
1042 //! \brief Sets the suggested configuration for L3 cache.
1043 //! \param [in] configIndex
1044 //! Index of suggested configuration plan. These configurations
1045 //! are defined in ::L3_SUGGEST_CONFIG which is a enumeration
1046 //! definition.
1047 //! \retval CM_SUCCESS if the L3 configuration pointer is set correctly.
1048 //! \retval CM_FAILURE if the platform does not support L3 or L3
1049 //! configuration failed to be set.
1050 //! \note This function is only implemented for hardware and
1051 //! simulation modes.
1052 CM_RT_API virtual int32_t SetSuggestedL3Config( L3_SUGGEST_CONFIG configIndex) = 0;
1053
1054 //! \brief This function can be used to set/limit hardware
1055 //! capabilities- number of threads that HW can run in parallel
1056 //! \details Hardware thread number can be set from 1 to maximum.
1057 //! \param [in] capName
1058 //! Name of cap to set.
1059 //! \param [in] capValueSize
1060 //! The size of the cap value.
1061 //! \param [in] capValue
1062 //! Pointer to the cap value.
1063 //! \retval CM_SUCCESS if cap value is valid and is set correctly.
1064 //! \retval CM_INVALID_HARDWARE_THREAD_NUMBER specific SetCaps error
1065 //! message if cap value is not valid.
1066 //! \retval CM_NOT_IMPLEMENTED for emulation mode.
1067 //! \retval CM_FAILURE otherwise.
1068 //! \note The following is the specific behavior for the cap value
1069 //! that is being set.
1070 //! <table>
1071 //! <tr>
1072 //! <th>Cap name< / th>
1073 //! <th>Behavior< / th>
1074 //! < / tr>
1075 //! <tr>
1076 //! <td>CAP_HW_THREAD_COUNT< / td>
1077 //! <td>The number of hardware threads is per - task.A call
1078 //! to the SetCaps function to set the CAP_HW_THREAD_COUNT
1079 //! will limit the maximum number of hardware threads for
1080 //! the ensuing call to Enqueue.After the call to Enqueue,
1081 //! the maximum number of hardware threads will be restored
1082 //! to its default value, which is determined by the
1083 //! hardware's capability.
1084 //! < / td>
1085 //! < / tr>
1086 //! < / table>
1087 CM_RT_API virtual int32_t SetCaps(CM_DEVICE_CAP_NAME capName, size_t capValueSize, void* capValue) = 0;
1088
1089 //! \brief This function creates a sampler surface index by a given
1090 //! CmSurface2D.
1091 //! \details This sampler surface doesn't create any actual surface. It
1092 //! just binds the actual 2D surface with a virtual sampler
1093 //! surface index. User need pass this surface index as kernel
1094 //! argument if the surface is used for sampler, otherwise,
1095 //! the runtime will report error if user pass the 2D surface
1096 //! index. For the 2D surface format, for now supports
1097 //! following formats: \n
1098 //! CM_SURFACE_FORMAT_A16B16G16R16 \n
1099 //! CM_SURFACE_FORMAT_A16B16G16R16F \n
1100 //! CM_SURFACE_FORMAT_R32G32B32A32F \n
1101 //! CM_SURFACE_FORMAT_A8 \n
1102 //! CM_SURFACE_FORMAT_A8R8G8B8 \n
1103 //! CM_SURFACE_FORMAT_YUY2 \n
1104 //! CM_SURFACE_FORMAT_R32F \n
1105 //! CM_SURFACE_FORMAT_R32_UINT \n
1106 //! CM_SURFACE_FORMAT_L16 \n
1107 //! CM_SURFACE_FORMAT_R16G16_UNORM \n
1108 //! CM_SURFACE_FORMAT_R16_FLOAT \n
1109 //! CM_SURFACE_FORMAT_NV12 \n
1110 //! CM_SURFACE_FORMAT_L8 \n
1111 //! CM_SURFACE_FORMAT_AYUV \n
1112 //! CM_SURFACE_FORMAT_Y410 \n
1113 //! CM_SURFACE_FORMAT_Y416 \n
1114 //! CM_SURFACE_FORMAT_Y210 \n
1115 //! CM_SURFACE_FORMAT_Y216 \n
1116 //! CM_SURFACE_FORMAT_P010 \n
1117 //! CM_SURFACE_FORMAT_P016 \n
1118 //! CM_SURFACE_FORMAT_YV12 \n
1119 //! CM_SURFACE_FORMAT_411P \n
1120 //! CM_SURFACE_FORMAT_411R \n
1121 //! CM_SURFACE_FORMAT_IMC3 \n
1122 //! CM_SURFACE_FORMAT_I420 \n
1123 //! CM_SURFACE_FORMAT_422H \n
1124 //! CM_SURFACE_FORMAT_422V \n
1125 //! CM_SURFACE_FORMAT_444P \n
1126 //! CM_SURFACE_FORMAT_P208 \n
1127 //! CM_SURFACE_FORMAT_RGBP \n
1128 //! CM_SURFACE_FORMAT_BGRP \n
1129 //! \param [in] surface2d
1130 //! Pointer to CmSurface2D object.
1131 //! \param [out] samplerSurfaceIndex
1132 //! Reference to the pointer to SurfaceIndex object to be
1133 //! created.
1134 //! \retval CM_SUCCESS if the new sampler surface index is successfully
1135 //! created.
1136 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format
1137 //! is not list above.
1138 //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of
1139 //! co-existed surfaces are exceed maximum count.
1140 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1141 //! \retval CM_FAILURE otherwise.
1142 CM_RT_API virtual int32_t CreateSamplerSurface2D(
1143 CmSurface2D* surface2d,
1144 SurfaceIndex* &samplerSurfaceIndex) = 0;
1145
1146 //! \brief This function creates a sampler surface index by a given
1147 //! CmSurface3D.
1148 //! \details This function call doesn't create any actual surface. It
1149 //! just binds the actual 3D surface with a virtual sampler
1150 //! surface index. User need pass this surface index as kernel
1151 //! argument if the surface is used for sampler, otherwise, the
1152 //! runtime will report error if user pass the 3D surface
1153 //! index. For the 3D surface format, for now only supports the
1154 //! CM_SURFACE_FORMAT_A8R8G8B8 and CM_SURFACE_FORMAT_A16B16G16R16
1155 //! formats.
1156 //! \param [in] surface3d
1157 //! Pointer to CmSurface3D object.
1158 //! \param [out] samplerSurfaceIndex
1159 //! Reference to the pointer to SurfaceIndex object to be
1160 //! created.
1161 //! \retval CM_SUCCESS if the sampler surface index is successfully
1162 //! created.
1163 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format
1164 //! is not list above.
1165 //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of created
1166 //! co-existed surfaces are exceed maximum count.
1167 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1168 //! \retval CM_FAILURE otherwise.
1169 CM_RT_API virtual int32_t CreateSamplerSurface3D(
1170 CmSurface3D* surface3d,
1171 SurfaceIndex* &samplerSurfaceIndex) = 0;
1172
1173 //! \brief This function destroys a sampler surface index created by
1174 //! CreateSamplerSurface2D(), CreateSamplerSurface2DUP, or
1175 //! CreateSamplerSurface3D().
1176 //! \details Caller provides the reference of a pointer to the surface
1177 //! index needs t be destoryed.
1178 //! \param [in] samplerSurfaceIndex
1179 //! Reference to the pointer to SurfaceIndex object to be
1180 //! destroyed.
1181 //! \retval CM_SUCCESS if the sampler surface index is successfully
1182 //! destroyed.
1183 //! \retval CM_FAILURE otherwise.
1184 CM_RT_API virtual int32_t DestroySamplerSurface(
1185 SurfaceIndex* & samplerSurfaceIndex) = 0;
1186
1187 //! \brief This function creates a buffer to store the message printed
1188 //! by printf() in kernel side.
1189 //! \details The default size of print buffer is 1M bytes. User can set
1190 //! its size according to the length of message printed in
1191 //! kernel and the number of threads. printf() can be used for
1192 //! kernel debug purpose
1193 //! \param [in] printbufsize
1194 //! The size of print buffer in bytes.
1195 //! \retval CM_SUCCESS if the print buffer is created successfully.
1196 //! \retval CM_OUT_OF_HOST_MEMORY if print buffer allication is failed.
1197 //! \retval CM_FAILURE otherwise.
1198 //! \note Internally the print buffer occupies static buffer index 1,
1199 //! thus only other 3 static buffers can be used by host (0, 2, 3)
1200 //! if print functionality is enabled.
1201 CM_RT_API virtual int32_t InitPrintBuffer(size_t printbufsize = CM_DEFAULT_PRINT_BUFFER_SIZE) = 0;
1202
1203 //! \brief This function prints the message on the standard display
1204 //! device that are dumped by kernel.
1205 //! \details It should be called after the task being finished. The
1206 //! order of printf output is not deterministic due to thread
1207 //! scheduling and the fact that different threads may be
1208 //! interleaved. To distinguish which thread the printf string
1209 //! comes from, it is better to print the thread id as the
1210 //! first value. Alternatively you could always
1211 //! put the printf inside if statement that limits the printf to a
1212 //! given thread. If one task has more than one kernels call
1213 //! printf() , their outputs could mix together.
1214 //! \retval CM_SUCCESS if the buffer is flushed successfully.
1215 //! \retval CM_FAILURE otherwise.
1216 //! \note See also FlushPrintBufferIntoFile() which is a variant to
1217 //! print message to a file.
1218 CM_RT_API virtual int32_t FlushPrintBuffer() = 0;
1219
1220 //! \brief This function creates a VEBOX object for VEBOX
1221 //! operations (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol09-media_vebox.pdf).
1222 //! \details Caller provides a reference of CmVebox pointer to get the
1223 //! CmVebox object created from this function.
1224 //! \param [in, out] vebox
1225 //! the created VEBOX object.
1226 //! \retval CM_SUCCESS if creation is successfully.
1227 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1228 //! \retval CM_FAILURE otherwise.
1229 CM_RT_API virtual int32_t CreateVebox(CmVebox* &vebox) = 0;
1230
1231 //! \brief This function destroys a VEBOX object.
1232 //! \details Caller provides a reference of CmVebox pointer to destroy.
1233 //! \param [in, out] vebox
1234 //! The VEBOX object to be destroyed. It will be assigned to
1235 //! nullptr once destroy is done.
1236 //! \retval CM_SUCCESS if creation is successfully.
1237 //! \retval CM_NULL_POINTER if the pVebox pointer is nullptr.
1238 //! \retval CM_FAILURE otherwise.
1239 CM_RT_API virtual int32_t DestroyVebox(CmVebox* & vebox) = 0;
1240
1241 //! \brief This function get the pointer to VADisplay.
1242 //! \details Caller provides a reference of pointer to VADisplay.
1243 //! \param [in,out] vaDisplay
1244 //! A poniter of type VADisplay for Libva Surface
1245 //! \retval CM_SUCCESS always.
1246 //! \note This is Linux only API.
1247 CM_RT_API virtual int32_t GetVaDpy(VADisplay* &vaDisplay) = 0;
1248
1249 //! \brief Create Libva Surface and wrap it as a CmSurface.
1250 //! \details It is caller's responsibility to allocation memory for all
1251 //! pointers to CmSurface2D.
1252 //! \param [in] width
1253 //! Surface's width
1254 //! \param [in] height
1255 //! Surface's height
1256 //! \param [in] format
1257 //! Surface's format
1258 //! \param [out] vaSurfaceId
1259 //! Reference to created VASurfaceID
1260 //! \param [out] surface
1261 //! Reference to pointer of created Cm Surface
1262 //! \retval CM_SUCCESS if all CmSurface2D are successfully created
1263 //! \retval CM_VA_SURFACE_NOT_SUPPORTED if libva surface creation fail
1264 //! \retval CM_FAILURE otherwise.
1265 //! \note This is a Linux only API.
1266 CM_RT_API virtual int32_t CreateVaSurface2D(
1267 uint32_t width,
1268 uint32_t height,
1269 CM_SURFACE_FORMAT format,
1270 VASurfaceID &vaSurfaceId,
1271 CmSurface2D* &surface) = 0;
1272
1273 //!
1274 //! \brief It creates a CmBufferSVM of the specified size in bytes by
1275 //! using the SVM (shared virtual memory) system memory.
1276 //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol05-memory_views.pdf).
1277 //! \details The SVM memory can be accessed by both CPU and GPU. The SVM
1278 //! memory will be allocated in runtime internally(if user pass
1279 //! nullptr pointer) or user provided (if user pass a valid
1280 //! pointer). In both way, the memory should be page aligned
1281 //! (4K bytes). And the staring address is returned.
1282 //! \param [in] size
1283 //! SVM buffer size in bytes.
1284 //! \param [in,out] sysMem
1285 //! Pointer to the SVM memory starting address.
1286 //! \param [in] accessFlag
1287 //! Buffer access flags.
1288 //! \param [out] buffer
1289 //! Reference to the pointer to the CmBufferSVM.
1290 //! \retval CM_SUCCESS if the CmBufferSVM is successfully created.
1291 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
1292 //! surface fails.
1293 //! \retval CM_INVALID_WIDTH if width is less than CM_MIN_SURF_WIDTH or
1294 //! larger than CM_MAX_1D_SURF_WIDTH.
1295 //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size
1296 //! SVM memory.
1297 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
1298 //! is exceeded. The amount is the amount of the surfaces that
1299 //! can co-exist. The amount can be obtained by querying the
1300 //! cap CAP_BUFFER_COUNT.
1301 //! \retval CM_FAILURE otherwise.
1302 //! \note This API is not implemented in Linux for now.
1303 //!
1304 CM_RT_API virtual int32_t CreateBufferSVM(uint32_t size,
1305 void* &sysMem,
1306 uint32_t accessFlag,
1307 CmBufferSVM* &buffer) = 0;
1308
1309 //!
1310 //! \brief Destroys CmBufferSVM object and associated SVM memory.
1311 //! \param [in,out] buffer
1312 //! Reference to the pointer pointing to CmBufferSVM, will be
1313 //! assigned to nullptr once it is destroyed successfully.
1314 //! \retval CM_SUCCESS if CmBufferSVM and associated SVM meory are
1315 //! successfully destroyed.
1316 //! \retval CM_FAILURE otherwise.
1317 //!
1318 CM_RT_API virtual int32_t DestroyBufferSVM( CmBufferSVM* &buffer) = 0;
1319
1320 //!
1321 //! \brief This function creates a sampler surface index by a
1322 //! CmSurface2DUP.
1323 //! \details This sampler surface doesn't create any actual surface,
1324 //! and just bind the actual 2D UP (User Provided) surface
1325 //! with a virtual sampler surface index. User need pass this
1326 //! surface index as kernel argument if the surface is used
1327 //! for sampler, otherwise, the runtime will report error if
1328 //! user pass the 2D UP surface index. For the 2DUP surface
1329 //! formats, for now supports following formats: \n
1330 //! CM_SURFACE_FORMAT_A16B16G16R16 \n
1331 //! CM_SURFACE_FORMAT_A8 \n
1332 //! CM_SURFACE_FORMAT_A8R8G8B8 \n
1333 //! CM_SURFACE_FORMAT_YUY2 \n
1334 //! CM_SURFACE_FORMAT_R32F \n
1335 //! CM_SURFACE_FORMAT_R32_UINT \n
1336 //! CM_SURFACE_FORMAT_L16 \n
1337 //! CM_SURFACE_FORMAT_R16G16_UNORM \n
1338 //! CM_SURFACE_FORMAT_NV12 \n
1339 //! CM_SURFACE_FORMAT_L8 \n
1340 //! CM_SURFACE_FORMAT_AYUV \n
1341 //! CM_SURFACE_FORMAT_Y410 \n
1342 //! CM_SURFACE_FORMAT_Y416 \n
1343 //! CM_SURFACE_FORMAT_Y210 \n
1344 //! CM_SURFACE_FORMAT_Y216 \n
1345 //! CM_SURFACE_FORMAT_P010 \n
1346 //! CM_SURFACE_FORMAT_P016 \n
1347 //! CM_SURFACE_FORMAT_YV12 \n
1348 //! CM_SURFACE_FORMAT_411P \n
1349 //! CM_SURFACE_FORMAT_411R \n
1350 //! CM_SURFACE_FORMAT_IMC3 \n
1351 //! CM_SURFACE_FORMAT_I420 \n
1352 //! CM_SURFACE_FORMAT_422H \n
1353 //! CM_SURFACE_FORMAT_422V \n
1354 //! CM_SURFACE_FORMAT_444P \n
1355 //! CM_SURFACE_FORMAT_P208 \n
1356 //! CM_SURFACE_FORMAT_RGBP \n
1357 //! CM_SURFACE_FORMAT_BGRP \n
1358 //! \param [in] surface2dUP
1359 //! Pointer to CmSurface2DUP object.
1360 //! \param [out] samplerSurfaceIndex
1361 //! Reference to the pointer to SurfaceIndex object to be
1362 //! created.
1363 //! \retval CM_SUCCESS if the new sampler surface index is
1364 //! successfully created.
1365 //! \retval CM_NULL_POINTER if p2DUPSurface is nullptr.
1366 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the format is not supported.
1367 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1368 //! \retval CM_FAILURE otherwise.
1369 //! \note This API is supported for HW mode only.
1370 //!
1371 CM_RT_API virtual int32_t
1372 CreateSamplerSurface2DUP(
1373 CmSurface2DUP* surface2dUP,
1374 SurfaceIndex* & samplerSurfaceIndex) = 0;
1375
1376 //!
1377 //! \brief Copies the content of source kernel to a new kernel.
1378 //! \param [out] destKernel
1379 //! pointer to the destination kernel. The new pointer will be
1380 //! returned to destKernel.
1381 //! \param [in] srcKernel
1382 //! pointer to the source kernel.
1383 //! \retval CM_SUCCESS If the clone operation is successful.
1384 //! \retval CM_FAILURE If the clone operation is failed.
1385 //! \note This API is not supported in emulation mode.
1386 //!
1387 CM_RT_API virtual int32_t CloneKernel(CmKernel * &destKernel,
1388 CmKernel *srcKernel) = 0;
1389
1390 //!
1391 //! \brief Creates an alias to CmSurface2D.
1392 //! \details Returns a new surface index for this surface. This API is
1393 //! used with CmSurface2D::SetSurfaceStateParam in order
1394 //! to reinterpret surface for different surface states,
1395 //! i.e., the same memory is used but different width and
1396 //! height can be programmed through the surface state.
1397 //! \param [in] originalSurface
1398 //! pointer to the surface used to create an alias.
1399 //! \param [out] aliasSurfaceIndex
1400 //! new surface index pointing to 2D surface.
1401 //! \retval CM_SUCCESS if alias is created successfully.
1402 //! \retval CM_INVALID_ARG_VALUE if p2DSurface is not a valid pointer.
1403 //! \retval CM_MAX_NUM_2D_ALIASES if try to create more than 10 aliases
1404 //! for same surface.
1405 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1406 //! \retval CM_FAILURE otherwise.
1407 //! \note This API is implemented for HW and SIM modes only.
1408 //!
1409 CM_RT_API virtual int32_t
1410 CreateSurface2DAlias(CmSurface2D* originalSurface,
1411 SurfaceIndex* &aliasSurfaceIndex) = 0;
1412
1413 //!
1414 //! \brief Creates an HEVC VME surface by using the given 2D surfaces:
1415 //! the current frame, the forward frames and, the backward
1416 //! frames.
1417 //! \details No extra surface is actually created. A SurfaceIndex
1418 //! object is created instead, which is passed to CM kernel
1419 //! function (genx_main) as argument to indicate the frame
1420 //! surface. This can be used for Gen10 and plus platforms.
1421 //! \param [in] currentSurface
1422 //! Pointer to current surface (can't be nullptr).
1423 //! \param [in] forwardSurfaceArray
1424 //! Array of forward surfaces (can be nullptr if backward
1425 //! surfaces not a nullptr).
1426 //! \param [in] backwardSurfaceArray
1427 //! Array of backward surfaces (can be nullptr if forward
1428 //! surfaces not a nullptr).
1429 //! \param [in] surfaceCountForward
1430 //! Count of forward surfaces, up to 9 forward surfaces can
1431 //! be used.
1432 //! \param [in] surfaceCountBackward
1433 //! Count of backward surfaces, up to 9 backward surfaces can
1434 //! be used.
1435 //! \param [out] vmeSurfaceIndex
1436 //! Reference to pointer to SurfaceIndex object to be created.
1437 //! \retval CM_SUCCESS if the SurfaceIndex is successfully created.
1438 //! \retval CM_NULL_POINTER if currentSurface is nullptr.
1439 //! \retval CM_INVALID_ARG_VALUE if invalid surface pointers for forward
1440 //! and backward surfaces.
1441 //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too much co-existed
1442 //! surfaces are created. Destroying unused surfaces to solve
1443 //! such error.
1444 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
1445 //! \retval CM_FAILURE otherwise.
1446 //! \note This API is only supported for Gen10 and plus platforms.
1447 //!
1448 CM_RT_API virtual int32_t
1449 CreateHevcVmeSurfaceG10(CmSurface2D* currentSurface,
1450 CmSurface2D** forwardSurfaceArray,
1451 CmSurface2D** backwardSurfaceArray,
1452 const uint32_t surfaceCountForward,
1453 const uint32_t surfaceCountBackward,
1454 SurfaceIndex* & vmeSurfaceIndex) = 0;
1455
1456 //!
1457 //! \brief Destroys an HEVC VME surface. This can be used for Gen10.
1458 //! \param [in] vmeSurfaceIndex
1459 //! Pointer to the SurfaceIndex of the VME surface. It will be
1460 //! assigned to nullptr once destroy is done.
1461 //! \retval CM_SUCCESS if the HEVC VME surface is successfully destroyed
1462 //! \retval CM_FAILURE otherwise.
1463 //! \note This API is only supported for Gen10 and plus platforms. \n
1464 //! Any HEVC VME surface not destroyed by calling this function
1465 //! explicitly will be destroyed when CmDevice is destroyed.
1466 //!
1467 CM_RT_API virtual int32_t
1468 DestroyHevcVmeSurfaceG10(SurfaceIndex* & vmeSurfaceIndex) = 0;
1469
1470 //!
1471 //! \brief Creates a CmSampler object with border color setting.
1472 //! \param [in] sampleState
1473 //! Const reference to a CM_SAMPLER_STATE_EX specifying the
1474 //! characteristics of the sampler to be created.
1475 //! \param [out] sampler
1476 //! Reference to the pointer to the CmSampler object.
1477 //! \retval CM_SUCCESS if the CmSampler is successfully created.
1478 //! \retval CM_OUT_OF_HOST_MEMORY if out of system memory.
1479 //! \retval CM_EXCEED_SAMPLER_AMOUNT if maximum amount of sampler is
1480 //! exceeded. The amount is the amount of the sampler that can
1481 //! co-exist. The amount can be obtained by querying the cap
1482 //! CAP_SAMPLER_COUNT.
1483 //! \retval CM_FAILURE otherwise.
1484 //! \note This API is not implemented for EMU mode. \n Point, linear,
1485 //! and anisotropic filter types are supported for hardware and
1486 //! simulation modes. \n Wrap, mirror, clamp and border are
1487 //! supported in hardware and simulation modes. Clamp is
1488 //! supported in emulation mode.
1489 //!
1490 CM_RT_API virtual int32_t
1491 CreateSamplerEx(const CM_SAMPLER_STATE_EX & sampleState,
1492 CmSampler* &sampler) = 0;
1493
1494 //!
1495 //! \brief This function prints the message dumped by kernel into file
1496 //! instead of stdout.
1497 //! \details This function's usage is the same as
1498 //! CmDevice::FlushPrintBuffer(). It is recommended to use this
1499 //! interface when there are tons of messages from kernel.
1500 //! \param [in] filename
1501 //! name of file the message printed into.
1502 //! \retval CM_SUCCESS if the buffer is flushed successfully into file.
1503 //! \retval CM_FAILURE otherwise.
1504 //! \note This is API is supported in hardware mode. See also
1505 //! FlushPrintBuffer().
1506 //!
1507 CM_RT_API virtual int32_t FlushPrintBufferIntoFile(const char *filename) = 0;
1508
1509 //!
1510 //! \brief This function creates a 3-dimensional thread group space specified by the
1511 //! depth, height and width dimensions of the group space, and
1512 //! the depth, the height and width dimensions of the thread
1513 //! space within a group.
1514 //! \details This information is used to execute a kernel in GPGPU pipe
1515 //! (https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf).
1516 //! \param [in] threadSpaceWidth
1517 //! width in unit of threads of each thread group.
1518 //! \param [in] threadSpaceHeight
1519 //! height in unit of threads of each thread group.
1520 //! \param [in] threadSpaceDepth
1521 //! Depth in unit of threads of each thread group.
1522 //! \param [in] groupSpaceWidth
1523 //! width in unit of groups of thread group space.
1524 //! \param [in] groupSpaceHeight
1525 //! height in unit of groups of thread group space.
1526 //! \param [in] groupSpaceDepth
1527 //! Depth in unit of groups of thread group space.
1528 //! \param [out] threadGroupSpace
1529 //! Reference to the pointer to CmThreadGroupSpace object to be
1530 //! created.
1531 //! \retval CM_SUCCESS if the CmThreadGroupSpace is successfully created.
1532 //! \retval CM_INVALID_THREAD_GROUP_SPACE if any input is 0 or the
1533 //! threadSpaceWidth is more than MAX_THREAD_SPACE_WIDTH_PERGROUP,
1534 //! or the threadSpaceHeight is more than
1535 //! MAX_THREAD_SPACE_HEIGHT_PERGROUP.
1536 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1537 //! \retval CM_FAILURE otherwise.
1538 //! \note The total thread count is
1539 //! width*height*depth*grpWidth*grpHeight*grpDepth.
1540 //! The function need to be called when Z dimension
1541 //! is larger than 1. when thrdSpaceDepth is 1 and grpSpaceDepth
1542 //! is 1, it is equivalent to call function
1543 //! CmDevice::CreateThreadGroupSpace(uint32_t threadSpaceWidth, uint32_t
1544 //! threadSpaceHeight, uint32_t groupSpaceWidth, uint32_t groupSpaceHeight,
1545 //! CmThreadGroupSpace* &threadGroupSpace). \n
1546 //! See also CmDevice::CreateThreadGroupSpace().
1547 //!
1548 CM_RT_API virtual int32_t
1549 CreateThreadGroupSpaceEx(uint32_t threadSpaceWidth,
1550 uint32_t threadSpaceHeight,
1551 uint32_t threadSpaceDepth,
1552 uint32_t groupSpaceWidth,
1553 uint32_t groupSpaceHeight,
1554 uint32_t groupSpaceDepth,
1555 CmThreadGroupSpace* &threadGroupSpace) = 0;
1556
1557 //!
1558 //! \brief Creates a CmSampler8x8 surface by using given 2D surface
1559 //! and given flags.
1560 //! \details The function indicates the 2D surface is used for sampler
1561 //! 8x8; no extra surface is actually created. A SurfaceIndex
1562 //! object is created instead, which is passed to CM kernel
1563 //! function(genx_main) as argument to indicate the surface for
1564 //! sampler 8x8. Compared to CmDeive::CreateSampler8x8Surface,
1565 //! this API is used to support rotation and chroma siting for
1566 //! MediaSampler.
1567 //! \param [in] surface
1568 //! Pointer to CmSurface2D.
1569 //! \param [out] surfaceIndex
1570 //! Reference to pointer to SurfaceIndex.
1571 //! \param [in] surfaceType
1572 //! Enumeration data type of CM_SAMPLER8x8_SURFACE.
1573 //! \param [in] addressControl
1574 //! Enumeration data type of CM_SURFACE_ADDRESS_CONTROL_MODE.
1575 //! \param [in] flag
1576 //! Pointer to CM_FLAG.
1577 //! \retval CM_SUCCESS if the CmSampler8x8 surface is successfully
1578 //! created.
1579 //! \retval CM_EXCEED_SURFACE_AMOUNT if there is too many co-existed
1580 //! surfaces and exceed the maximum number. Destroying some
1581 //! unused surfaces could solve this error.
1582 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory
1583 //! \retval CM_FAILURE otherwise.
1584 //! \note This API is not supported in emulation mode.
1585 //!
1586 CM_RT_API virtual int32_t CreateSampler8x8SurfaceEx(
1587 CmSurface2D *surface,
1588 SurfaceIndex* &surfaceIndex,
1589 CM_SAMPLER8x8_SURFACE surfaceType,
1590 CM_SURFACE_ADDRESS_CONTROL_MODE addressControl = CM_SURFACE_CLAMP,
1591 CM_FLAG *flag = nullptr) = 0;
1592
1593 //!
1594 //! \brief Create sampler surface by using given 2D surface and flags.
1595 //! \details This sampler surface does't create any actual surface, and
1596 //! just bind the actual 2D surface with a virtual sampler
1597 //! surface index. User need pass this surface index as kernel
1598 //! argument if the surface is used for sampler, otherwise,
1599 //! the runtime will report error if user pass the 2D surface
1600 //! index. Compared to CmDevice::CreateSampler8x8Surface, this
1601 //! API is used to support rotation for 3D sampler. For given
1602 //! surface's formats, for now, we support following: \n
1603 //! CM_SURFACE_FORMAT_A16B16G16R16 \n
1604 //! CM_SURFACE_FORMAT_A16B16G16R16F \n
1605 //! CM_SURFACE_FORMAT_R32G32B32A32F \n
1606 //! CM_SURFACE_FORMAT_A8 \n
1607 //! CM_SURFACE_FORMAT_A8R8G8B8 \n
1608 //! CM_SURFACE_FORMAT_YUY2 \n
1609 //! CM_SURFACE_FORMAT_R32F \n
1610 //! CM_SURFACE_FORMAT_R32_UINT \n
1611 //! CM_SURFACE_FORMAT_L16 \n
1612 //! CM_SURFACE_FORMAT_R16G16_UNORM \n
1613 //! CM_SURFACE_FORMAT_R16_FLOAT \n
1614 //! CM_SURFACE_FORMAT_NV12 \n
1615 //! CM_SURFACE_FORMAT_L8 \n
1616 //! CM_SURFACE_FORMAT_AYUV \n
1617 //! CM_SURFACE_FORMAT_Y410 \n
1618 //! CM_SURFACE_FORMAT_Y416 \n
1619 //! CM_SURFACE_FORMAT_Y210 \n
1620 //! CM_SURFACE_FORMAT_Y216 \n
1621 //! CM_SURFACE_FORMAT_P010 \n
1622 //! CM_SURFACE_FORMAT_P016 \n
1623 //! CM_SURFACE_FORMAT_YV12 \n
1624 //! CM_SURFACE_FORMAT_411P \n
1625 //! CM_SURFACE_FORMAT_411R \n
1626 //! CM_SURFACE_FORMAT_IMC3 \n
1627 //! CM_SURFACE_FORMAT_I420 \n
1628 //! CM_SURFACE_FORMAT_422H \n
1629 //! CM_SURFACE_FORMAT_422V \n
1630 //! CM_SURFACE_FORMAT_444P \n
1631 //! CM_SURFACE_FORMAT_P208 \n
1632 //! CM_SURFACE_FORMAT_RGBP \n
1633 //! CM_SURFACE_FORMAT_BGRP \n
1634 //! \param [in] surface2d
1635 //! Pointer to CmSurface2D object.
1636 //! \param [out] samplerSurfaceIndex
1637 //! Reference to the pointer to SurfaceIndex object to be
1638 //! created.
1639 //! \param [in] flag
1640 //! Pointer to CM_FLAG.
1641 //! \retval CM_SUCCESS if the new sampler surface index is
1642 //! successfully created.
1643 //! \retval CM_SURFACE_FORMAT_NOT_SUPPORTED if the input surface format
1644 //! is not list above.
1645 //! \retval CM_EXCEED_SURFACE_AMOUNT if the total number of created
1646 //! co-existed surfaces are exceed maximum count.
1647 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1648 //! \retval CM_FAILURE otherwise.
1649 //! \note This API is not supported in emulation mode.
1650 //!
1651 CM_RT_API virtual int32_t
1652 CreateSamplerSurface2DEx(CmSurface2D* surface2d,
1653 SurfaceIndex* & samplerSurfaceIndex,
1654 CM_FLAG* flag = nullptr) = 0;
1655
1656 //! \brief Create an alias to CmBuffer.
1657 //! \details Returns a new surface index for this surface. This API is
1658 //! used with CmBuffer::SetSurfaceStateParam in order
1659 //! to reinterpret buffer for different surface states,
1660 //! i.e., the same memory is used but different size
1661 //! can be programmed through the surface state.
1662 //! \param [in] originalBuffer
1663 //! pointer to CmBuffer object used to create an alias.
1664 //! \param [out] aliasIndex
1665 //! \retval CM_SUCCESS if alias is created successfully.
1666 //! new surface index pointing to CmBuffer.
1667 //! \retval CM_EXCEED_MAX_NUM_BUFFER_ALIASES if try to create more
1668 //! than 10 aliases for same surface.
1669 //! \retval CM_OUT_OF_HOST_MEMORY if out of host memory.
1670 //! \retval CM_FAILURE if alias cannot be created.
1671 //! \note This API is not implemented for EMU mode.
1672 //!
1673 CM_RT_API virtual int32_t CreateBufferAlias(CmBuffer *originalBuffer,
1674 SurfaceIndex* &aliasIndex) = 0;
1675
1676 //! \brief Set the width and height values in the VME surface state.
1677 //! \param [in] vmeIndex
1678 //! Pointer to VME surface index.
1679 //! \param [in] surfStateParam
1680 //! Pointer to CM_VME_SURFACE_STATE_PARAM to set width and
1681 //! height of this surface
1682 //! \retval CM_SUCCESS if setting VME surface state values successfully.
1683 //! \retval CM_INVALID_ARG_VALUE if invalid input.
1684 //! \note This API will work on HW and SIM modes.
1685 //!
1686 CM_RT_API virtual int32_t
1687 SetVmeSurfaceStateParam(SurfaceIndex* vmeIndex,
1688 CM_VME_SURFACE_STATE_PARAM *surfStateParam) = 0;
1689
1690 //!
1691 //! \brief Gets the VISA version up-to which IGC supports.
1692 //! \param [out] majorVersion
1693 //! The major Version of VISA.
1694 //! \param [out] minorVersion
1695 //! The minor Version of VISA.
1696 //! \retval CM_SUCCESS if get the right VISA version.
1697 //! \retval CM_JITDLL_LOAD_FAILURE if loading igc library is failed.
1698 //! \retval CM_FAILURE otherwise.
1699 //! \note This API is implemented in hardware mode only.
1700 //!
1701 CM_RT_API virtual int32_t GetVISAVersion(uint32_t& majorVersion,
1702 uint32_t& minorVersion) = 0;
1703
1704 //!
1705 //! \brief Creates a CmQueue object with option.
1706 //! \param [out] queue
1707 //! Pointer to the CmQueue object created.
1708 //! \param [in] createOption
1709 //! The option to create a queue. The sturcture of the
1710 //! <b>QueueCreateOption</b> is:\n
1711 //! \code
1712 //! struct CM_QUEUE_CREATE_OPTION
1713 //! {
1714 //! CM_QUEUE_TYPE QueueType : 3;
1715 //! bool RAMode : 1;
1716 //! unsigned int Reserved0 : 3;
1717 //! bool UserGPUContext : 1;
1718 //! unsigned int GPUContext : 8;
1719 //! CM_QUEUE_SSEU_USAGE_HINT_TYPE SseuUsageHint : 3;
1720 //! unsigned int Reserved1 : 1;
1721 //! unsigned int Reserved2 : 12;
1722 //! }
1723 //! \endcode
1724 //! \n
1725 //! <b>QueueType</b> indicates which engine the queue will be created for:\n
1726 //! \code
1727 //! enum CM_QUEUE_TYPE
1728 //! {
1729 //! CM_QUEUE_TYPE_NONE = 0,
1730 //! CM_QUEUE_TYPE_RENDER = 1,
1731 //! CM_QUEUE_TYPE_COMPUTE = 2
1732 //! };
1733 //! \endcode
1734 //! \n
1735 //! <b>RAMode</b> decides if the queue will occupy GPU
1736 //! exclusively during execution.
1737 //! \n
1738 //! <b>UserGPUContext</b> indicates whether a existed GPU context is passed
1739 //! by user via below GPUContext field.
1740 //! \n
1741 //! <b>GPUContext</b> indicates GPU context passed by user.
1742 //! \n
1743 //! <b>SseuUsageHint</b> indicates SSEU setting, will be created for:\n
1744 //! \code
1745 //! enum CM_QUEUE_SSEU_USAGE_HINT_TYPE
1746 //! {
1747 //! CM_QUEUE_SSEU_USAGE_HINT_DEFAULT = 0,
1748 //! CM_QUEUE_SSEU_USAGE_HINT_VME = 1
1749 //! };
1750 //! \endcode
1751 //! \n
1752 //! \retval CM_SUCCESS if the CmQueue object is created.
1753 //! \note This API is implemented in hardware mode only. Only
1754 //! CM_QUEUE_TYPE_RENDER and CM_QUEUE_TYPE_COMPUTE are
1755 //! implemented at this moment.
1756 //!
1757 CM_RT_API virtual int32_t
1758 CreateQueueEx(CmQueue *&queue,
1759 CM_QUEUE_CREATE_OPTION createOption) = 0;
1760
1761 //!
1762 //! \brief It creates a CmBufferStateless of the specified size in bytes by
1763 //! using the vedio memory or the system memory.
1764 //! \details The stateless buffer means it is stateless-accessed by GPU. There
1765 //! are two ways to create a stateless buffer. One is to create from
1766 //! vedio memory, then it can be only accessed by GPU. The other way is
1767 //! to create from system memory, then it can be accessed by both GPU
1768 //! and CPU. In this way, The system memory will be allocated in runtime
1769 //! internally(if user pass nullptr pointer) or user provided (if user
1770 //! pass a valid pointer). And the system memory should be page aligned
1771 //! (4K bytes).
1772 //! \param [in] size
1773 //! Stateless buffer size in bytes.
1774 //! \param [in] option
1775 //! Stateless buffer create option.
1776 //! \param [in] sysMem
1777 //! Pointer to user provided system memory if option is system memory.
1778 //! \param [out] pSurface
1779 //! Reference to the pointer to the CmBufferStateless.
1780 //! \retval CM_SUCCESS if the CmBufferStateless is successfully created.
1781 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 1D
1782 //! surface fails.
1783 //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size
1784 //! system memory.
1785 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 1D surfaces
1786 //! is exceeded. The amount is the amount of the surfaces that
1787 //! can co-exist. The amount can be obtained by querying the
1788 //! cap CAP_BUFFER_COUNT.
1789 //! \retval CM_INVALID_CREATE_OPTION_FOR_BUFFER_STATELESS if option is invalid.
1790 //! \retval CM_FAILURE otherwise.
1791 CM_RT_API virtual int32_t CreateBufferStateless(size_t size,
1792 uint32_t option,
1793 void *sysMem,
1794 CmBufferStateless *&buffer) = 0;
1795
1796 //!
1797 //! \brief Destroy CmBufferStateless object and associated vedio/system memory.
1798 //! \param [in,out] pSurface
1799 //! Reference to the pointer pointing to CmBufferStateless, will be
1800 //! assigned to nullptr once it is destroyed successfully.
1801 //! \retval CM_SUCCESS if CmBufferStateless and associated vedio/system memory are
1802 //! successfully destroyed.
1803 //! \retval CM_FAILURE otherwise.
1804 //!
1805 CM_RT_API virtual int32_t DestroyBufferStateless(CmBufferStateless* &buffer) = 0;
1806
1807 CM_RT_API virtual int32_t DispatchTask() = 0;
1808
1809 //!
1810 //! \brief It creates a CmSurface2DStateless of the specified width, height and
1811 //! pitch in bytes by using the vedio memory.
1812 //! \details The stateless surface means it is stateless-accessed by GPU. It is
1813 //! created from vedio memory, and can be only accessed by GPU.
1814 //! \param [in] width
1815 //! Surface width in bytes.
1816 //! \param [in] width
1817 //! Surface height in bytes.
1818 //! \param [out] pitch
1819 //! Surface pitch in bytes.
1820 //! \param [out] pSurface
1821 //! Reference to the pointer to the CmSurface2DStateless.
1822 //! \retval CM_SUCCESS if the CmSurface2DStateless is successfully created.
1823 //! \retval CM_SURFACE_ALLOCATION_FAILURE if creating the underneath 2D
1824 //! surface fails.
1825 //! \retval CM_OUT_OF_HOST_MEMORY if runtime can't allocate such size
1826 //! system memory.
1827 //! \retval CM_EXCEED_SURFACE_AMOUNT if maximum amount of 2D surfaces
1828 //! is exceeded. The amount is the amount of the surfaces that
1829 //! can co-exist. The amount can be obtained by querying the
1830 //! cap CAP_SURFACE2D_COUNT.
1831 //! \retval CM_FAILURE otherwise.
1832 CM_RT_API virtual int32_t
1833 CreateSurface2DStateless(uint32_t width,
1834 uint32_t height,
1835 uint32_t &pitch,
1836 CmSurface2DStateless *&pSurface) = 0;
1837
1838 //!
1839 //! \brief Destroy CmSurface2DStateless object and associated vedio memory.
1840 //! \param [in,out] pSurface
1841 //! Reference to the pointer pointing to CmSurface2DStateless, will be
1842 //! assigned to nullptr once it is destroyed successfully.
1843 //! \retval CM_SUCCESS if CmSurface2DStateless and associated vedio memory are
1844 //! successfully destroyed.
1845 //! \retval CM_FAILURE otherwise.
1846 //!
1847 CM_RT_API virtual int32_t DestroySurface2DStateless(CmSurface2DStateless *&pSurface) = 0;
1848
1849 protected:
1850 virtual ~CmDevice() = default;
1851 };
1852
1853 #endif // #ifndef CMRTLIB_LINUX_SHARE_CM_DEVICE_BASE_H_