Support passing through user data per frame

This is guarded under `#if VVENC_USE_UNSTABLE_API` and disabled by
default due to requiring breaking changes to the ABI. It can only be
unguarded when the major version is bumped to v2.

Closes #480

Author: cadubentzen

CMakeLists.txt

@@ -179,6 +179,8 @@ set( VVENC_INSTALL_FULLFEATURE_APP          OFF CACHE BOOL   "Install the full-f
 
 set( VVENC_ENABLE_WERROR                    ON  CACHE BOOL   "Treat warnings as errors (-Werror or /WX)" )
 
+set( VVENC_ENABLE_UNSTABLE_API              OFF CACHE BOOL   "Enable unstable API" )
+
 if( CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR
     CMAKE_CXX_COMPILER_ID STREQUAL "Clang" )
 
@@ -290,6 +292,13 @@ if( VVENC_ENABLE_WERROR )
   add_compile_options( "$<$<CXX_COMPILER_ID:MSVC>:/WX>" )
 endif()
 
+set( VVENC_USE_UNSTABLE_API 0 )
+if( VVENC_ENABLE_UNSTABLE_API )
+  set( VVENC_USE_UNSTABLE_API 1 )
+endif()
+
+configure_file( include/vvenc/vvenc.h.in ${CMAKE_BINARY_DIR}/vvenc/vvenc.h @ONLY )
+
 if( VVENC_ENABLE_X86_SIMD )
   if( ( UNIX OR MINGW ) AND VVENC_OPT_TARGET_ARCH )
     set( CMAKE_C_FLAGS   "${CMAKE_C_FLAGS} -march=${VVENC_OPT_TARGET_ARCH} -mtune=${VVENC_OPT_TARGET_ARCH}" )

Makefile

@@ -82,6 +82,10 @@ ifneq ($(enable-werror),)
 CONFIG_OPTIONS += -DVVENC_ENABLE_WERROR=$(enable-werror)
 endif
 
+ifneq ($(enable-unstable-api),)
+CONFIG_OPTIONS += -DVVENC_ENABLE_UNSTABLE_API=$(enable-unstable-api)
+endif
+
 ifeq ($(j),)
 # Query cmake for the number of cores
 NUM_JOBS := $(shell cmake -P cmake/modules/vvencNumCores.cmake)

cmake/modules/vvencInstall.cmake

@@ -60,8 +60,8 @@ endmacro( install_exe_pdb )
 target_include_directories( vvenc  SYSTEM INTERFACE $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}> )
 
 # install headers
-install( FILES     ${CMAKE_BINARY_DIR}/vvenc/version.h  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/vvenc )
-install( DIRECTORY include/vvenc                        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} )
+install( DIRECTORY ${CMAKE_BINARY_DIR}/vvenc  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} )
+install( DIRECTORY include/vvenc              DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} PATTERN "*.in" EXCLUDE )
 
 # install targets
 install_targets( Release )

include/vvenc/vvenc.h renamed to include/vvenc/vvenc.h.in

@@ -58,6 +58,8 @@ POSSIBILITY OF SUCH DAMAGE.
 #define VVENC_NAMESPACE_BEGIN
 #define VVENC_NAMESPACE_END
 
+#define VVENC_USE_UNSTABLE_API @VVENC_USE_UNSTABLE_API@
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -135,6 +137,9 @@ typedef struct vvencYUVBuffer
   uint64_t      sequenceNumber;        // sequence number of the picture
   uint64_t      cts;                   // composition time stamp in TicksPerSecond
   bool          ctsValid;              // composition time stamp valid flag (true: valid, false: CTS not set)
+#if VVENC_USE_UNSTABLE_API
+  void*         userData;              // user data to be returned in corresponding access unit
+#endif
 }vvencYUVBuffer;
 
 /* vvenc_YUVBuffer_alloc:
@@ -196,6 +201,9 @@ typedef struct vvencAccessUnit
   int             status;              // additional info (see Status)
   int             essentialBytes;      // number of bytes in nalus of type SLICE_*, DCI, VPS, SPS, PPS, PREFIX_APS, SUFFIX_APS
   char            infoString[VVENC_MAX_STRING_LEN]; // debug info from inside the encoder
+#if VVENC_USE_UNSTABLE_API
+  void*           userData;            // user data passed in corresponding input YUV buffer
+#endif
 } vvencAccessUnit;
 
 /* vvenc_accessUnit_alloc:

source/Lib/CommonLib/Nal.h

@@ -178,6 +178,7 @@ class AccessUnitList : public std::list<NALUnitEBSP*> // NOTE: Should not inheri
     rap           = false;
     refPic        = false;
     InfoString.clear();
+    userData      = nullptr;
 
     for( AccessUnitList::iterator it = this->begin(); it != this->end(); it++ )
     {
@@ -202,6 +203,7 @@ class AccessUnitList : public std::list<NALUnitEBSP*> // NOTE: Should not inheri
   bool            rap;                                    ///< random access point flag
   bool            refPic;                                 ///< reference picture
   std::string     InfoString;
+  void*           userData;                               ///< user data passed in corresponding input YUV buffer
 };
 
 

source/Lib/CommonLib/Picture.h

@@ -293,6 +293,8 @@ struct Picture : public UnitArea
   std::vector<uint8_t>          m_alfCtuAlternative[ MAX_NUM_COMP ];
   std::vector<std::atomic<int>>*  m_tileColsDone = nullptr;
 
+  void*                         userData;
+
 public:
   Slice*          allocateNewSlice();
   Slice*          swapSliceObject( Slice* p, uint32_t i );

source/Lib/EncoderLib/EncGOP.cpp

@@ -2455,6 +2455,7 @@ void EncGOP::xWritePicture( Picture& pic, AccessUnitList& au, bool isEncodeLtRef
   au.poc           = pic.poc;
   au.temporalLayer = pic.TLayer;
   au.refPic        = pic.isReferenced;
+  au.userData      = pic.userData;
   if( ! pic.slices.empty() )
   {
     au.sliceType = pic.slices[ 0 ]->sliceType;

source/Lib/EncoderLib/EncStage.h

@@ -82,6 +82,7 @@ class PicShared
   bool             m_isLead;
   bool             m_isTrail;
   bool             m_ctsValid;
+  void*            m_userData;
 
 public:
   PicShared()
@@ -99,6 +100,7 @@ class PicShared
   , m_isLead         ( false )
   , m_isTrail        ( false )
   , m_ctsValid       ( false )
+  , m_userData       ( nullptr )
   {
     std::fill_n( m_prevShared, NUM_QPA_PREV_FRAMES, nullptr );
     std::fill_n( m_minNoiseLevels, QPA_MAX_NOISE_LEVELS, 255u );
@@ -150,6 +152,9 @@ class PicShared
     std::fill_n( m_prevShared, NUM_QPA_PREV_FRAMES, nullptr );
     std::fill_n( m_minNoiseLevels, QPA_MAX_NOISE_LEVELS, 255u );
     m_gopEntry.setDefaultGOPEntry();
+#if VVENC_USE_UNSTABLE_API
+    m_userData       = yuvInBuf->userData;
+#endif
   }
 
   void shareData( Picture* pic )
@@ -165,6 +170,7 @@ class PicShared
     pic->cts            = m_cts;
     pic->ctsValid       = m_ctsValid;
     pic->gopEntry       = &m_gopEntry;
+    pic->userData       = m_userData;
     incUsed();
   }
 

source/Lib/vvenc/vvenc.cpp

@@ -193,6 +193,9 @@ VVENC_DECL void vvenc_accessUnit_reset(vvencAccessUnit *accessUnit )
   accessUnit->poc             = 0;
   accessUnit->status          = 0;
   accessUnit->essentialBytes  = 0;
+#if VVENC_USE_UNSTABLE_API
+  accessUnit->userData        = nullptr;
+#endif
 
   memset( accessUnit->infoString, 0, sizeof( accessUnit->infoString ) );
   accessUnit->infoString[0]   ='\0';

source/Lib/vvenc/vvencimpl.cpp

@@ -761,6 +761,9 @@ int VVEncImpl::xCopyAu( vvencAccessUnit& rcAccessUnit, const vvenc::AccessUnitLi
     rcAccessUnit.temporalLayer   = rcAuList.temporalLayer;
     rcAccessUnit.poc             = rcAuList.poc;
     rcAccessUnit.status          = rcAuList.status;
+#if VVENC_USE_UNSTABLE_API
+    rcAccessUnit.userData        = rcAuList.userData;
+#endif
 
     if ( !rcAuList.InfoString.empty() )
     {

test/vvenclibtest/vvenclibtest.cpp

@@ -54,6 +54,7 @@ POSSIBILITY OF SUCH DAMAGE.
 #include <cstring>
 #include <vector>
 #include <tuple>
+#include <unordered_set>
 
 #include "vvenc/version.h"
 #include "vvenc/vvenc.h"
@@ -924,6 +925,10 @@ static int runEncoder( vvenc_config& c, uint64_t framesToEncode, bool emulateMis
   uint64_t framesRcvd = 0;
   uint64_t numMissingFrames = emulateMissingFrames ? 10 : 0;
 
+#if VVENC_USE_UNSTABLE_API
+  std::unordered_set<int> userDataSet;
+#endif
+
   while( !eof || !encodeDone )
   {
     vvencYUVBuffer* inputPtr = nullptr;
@@ -932,6 +937,9 @@ static int runEncoder( vvenc_config& c, uint64_t framesToEncode, bool emulateMis
       inputPtr             = yuvPicture;
       yuvPicture->cts      = (c.m_TicksPerSecond > 0) ? (ctsOffset + (framesRcvd * (uint64_t)c.m_TicksPerSecond * (uint64_t)c.m_FrameScale / (uint64_t)c.m_FrameRate)) : (ctsOffset + framesRcvd);
       yuvPicture->ctsValid = true;
+#if VVENC_USE_UNSTABLE_API
+      yuvPicture->userData   = new int(framesRcvd);
+#endif
       framesRcvd++;
 
       if( emulateMissingFrames && framesRcvd == framesToEncode>>1 )
@@ -964,6 +972,11 @@ static int runEncoder( vvenc_config& c, uint64_t framesToEncode, bool emulateMis
         }
       }
       lastDts = AU->dts;
+#if VVENC_USE_UNSTABLE_API
+      int* userData = static_cast<int*>(AU->userData);
+      userDataSet.insert( *userData);
+      delete userData;
+#endif
     }
 
     if ( auCount > 0 && (!AU || ( AU &&  AU->payloadUsedSize == 0 )) )
@@ -984,6 +997,14 @@ static int runEncoder( vvenc_config& c, uint64_t framesToEncode, bool emulateMis
     goto fail;
   }
 
+#if VVENC_USE_UNSTABLE_API
+  if (userDataSet.size() != framesToEncode)
+  {
+    //std::cout << "expecting " << framesToEncode << " unique user data values, but got " << userDataSet.size() << std::endl;
+    goto fail;
+  }
+#endif
+
   vvenc_YUVBuffer_free( yuvPicture, true );
   vvenc_accessUnit_free( AU, true );
   vvenc_encoder_close( enc );