Debian Codegraph @

media_driver/agnostic/common/cm/cm_surface_3d.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 //!
23 //! \file cm_surface_3d.h
24 //! \brief Contains CmSurface3D declarations.
25 //!
26
27 #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMSURFACE3D_H_
28 #define MEDIADRIVER_AGNOSTIC_COMMON_CM_CMSURFACE3D_H_
29
30 #include "cm_def.h"
31
32 namespace CMRT_UMD
33 {
34 class CmEvent;
35
36 //! \brief CmSurface3D class to manage 3D surface in video memory.
37 //! \details CmSurface3D represents a 3D surface in video memory. Each
38 //! CmSurface3D object is associated with a SurfaceIndex object
39 //! containing a unique index value the surface is mapped to when
40 //! created by the CmDevice. The CmDevice keeps the mapping b/w
41 //! index and CmSurface3D. The SurfaceIndex is passed to CM kernel
42 //! function as argument to indicate the surface.
43 class CmSurface3D
44 {
45 public:
46 //! \brief This function returns the SurfaceIndex object associated
47 //! with the surface.
48 //! \param [out] index
49 //! Reference to the pointer to the SurfaceIndex.
50 //! \returns Always returns CM_SUCCESS.
51 CM_RT_API virtual int32_t GetIndex(SurfaceIndex* &index) = 0;
52
53 //! \brief Copy the surface content to system memory.
54 //! \details The size of data copied is the size of data in surface. It is
55 //! the caller's responsibility to allocate the system memory.
56 //! This is a blocking function, i.e. the function will not
57 //! return until the copy operation is completed. Surface
58 //! reading will not happen until the status of the dependent
59 //! event becomes CM_STATUS_FINISHED. It is application's
60 //! responsibility to make sure no other task enqueued after
61 //! the task corresponding to the dependent task but before
62 //! ReadSurface. If sysMemSize is given, it will be checked
63 //! against the size needed for the surface.
64 //! \param [in] sysMem
65 //! pointer to the target system memory.
66 //! \param [in] event
67 //! pointer to the dependent event. See also CmEvent.
68 //! \param [in] sysMemSize
69 //! size of the system memory. Default value is -1 which means
70 //! no memory size checking.
71 //! \retval CM_SUCCESS if the copy is successful.
72 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr or the sysMemSize
73 //! is less than total size of CmSurface3D.
74 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
75 //! \retval CM_EXCEED_MAX_TIMEOUT if the dependent task times out.
76 //! \retval CM_FAILURE otherwise.
77 CM_RT_API virtual int32_t
78 ReadSurface(unsigned char *sysMem,
79 CmEvent *event,
80 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
81
82 //! \brief Copy system memory content to surface.
83 //! \details The size of data copied is the size of data in surface. It is the
84 //! caller's responsibility to allocate the system memory. This
85 //! is a blocking function, i.e. the function will not return
86 //! until the copy operation is completed. Surface writing will
87 //! not happen until the status of the dependent event becomes
88 //! CM_STATUS_FINISHED. The dependent event for WriteSurface is
89 //! usually NULL. If sysMemSize is given, it will be checked
90 //! against the size needed for the surface.
91 //! \param [in] sysMem
92 //! pointer to the source system memory.
93 //! \param [in] event
94 //! pointer to the dependent event. See also CmEvent.
95 //! \param [in] sysMemSize
96 //! size of the system memory. The default value is -1, which
97 //! means no memory size checking.
98 //! \retval CM_SUCCESS if the copy is successful.
99 //! \retval CM_INVALID_ARG_VALUE if sysMem is nullptr or the sysMemSize
100 //! is less than total size of CmSurface3D.
101 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
102 //! \retval CM_EXCEED_MAX_TIMEOUT if the dependent task times out.
103 //! \retval CM_FAILURE otherwise.
104 CM_RT_API virtual int32_t
105 WriteSurface(const unsigned char *sysMem,
106 CmEvent *event,
107 uint64_t sysMemSize = 0xFFFFFFFFFFFFFFFFULL) = 0;
108
109 //! \brief Set memory in surface to initValue.
110 //! \details The size of data initialized is the size of data in the surface. This
111 //! is a blocking function, i.e. the function will not return
112 //! until the memset operation is completed. Surface
113 //! initialization will not happen until the status of the
114 //! dependent event becomes CM_STATUS_FINISHED. The dependent
115 //! event for InitSurface is usually NULL.
116 //! \param [in] initValue
117 //! 4-byte value used to initilize the memory.
118 //! \param [in] event
119 //! pointer to the dependent event. See also CmEvent.
120 //! \retval CM_SUCCESS if the copy is successful.
121 //! \retval CM_LOCK_SURFACE_FAIL if surface locking is failed.
122 //! \retval CM_FAILURE otherwise.
123 CM_RT_API virtual int32_t InitSurface(const uint32_t initValue,
124 CmEvent *event) = 0;
125
126 //! \brief Selects one of the pre-defined memory object control
127 //! settings for this surface.
128 //! \param [in] memCtrl
129 //! the selected pre-defined memory object control setting.
130 //! See also MEMORY_OBJECT_CONTROL.
131 //! \retval CM_SUCCESS if the copy is successful.
132 //! \retval CM_FAILURE otherwise.
133 //! \note This API is platform related, and only for SKL and plus platforms.
134 CM_RT_API virtual int32_t
135 SelectMemoryObjectControlSetting(MEMORY_OBJECT_CONTROL memCtrl) = 0;
136
137 //!
138 //! \brief Selects one of the pre-defined MOS resource usage settings for this surface.
139 //! \note This function works on Gen9+ paltforms.
140 //! \param [in] mosUsage
141 //! The selected pre-defined MOS resource usage for memory object control setting.
142 //! \retval CM_SUCCESS if the given parameter is valid
143 //! \retval CM_FAILURE otherwise.
144 //!
145 CMRT_UMD_API virtual int32_t SetResourceUsage(const MOS_HW_RESOURCE_DEF mosUsage) = 0;
146 };
147 };//namespace
148
149 #endif // #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMSURFACE3D_H_