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_ 150