Doom3 Engine

struct job_t
{
    void  (* function )(void *);   // Job instructions
    void   * data;                 // Job parameters
    int    executed;               // Job end marker...Not used.
};

int idJobThread::Run()
{
    threadJobListState_t threadJobListState[MAX_JOBLISTS];

    while ( !IsTerminating() )
    {
        int currentJobList = 0;

        // fetch any new job lists and add them to the local list in threadJobListState
        {}

        if  ( lastStalledJobList < 0 )
            // find the job list with the highest priority
        else
            // try to hide the stall with a job from a list that has equal or higher priority

            currentJobList = X;

        // try running one or more jobs from the current job list
        int result = threadJobListState[currentJobList].jobList->RunJobs( threadNum, threadJobListState[currentJobList], singleJob );

        // Analyze how job running went
        if  ( ( result & idParallelJobList_Threads::RUN_DONE ) != 0 ) {
            // done with this job list so remove it from the local list (threadJobListState[currentJobList])
        } else  if  ( ( result & idParallelJobList_Threads::RUN_STALLED ) != 0 ) {
            lastStalledJobList = currentJobList;
        } else  {
            lastStalledJobList = -1;
        }
    }
}

int idParallelJobList::RunJobs( unsigned int  threadNum, threadJobListState_t & state, bool  singleJob )
{
    do
    {
        // try to lock to fetch a new job
        if ( fetchLock.Increment() == 1 )
        {
            // grab a new job
            state.nextJobIndex = currentJob.Increment() - 1;

            // release the fetch lock
            fetchLock.Decrement();
        }
        else
        {
            // release the fetch lock
            fetchLock.Decrement();
            // another thread is fetching right now so consider stalled
            return  ( result | RUN_STALLED );
        }

        // Run job
        jobList[state.nextJobIndex].function( jobList[state.nextJobIndex].data );

        // if at the end of the job list we're done
        if  ( state.nextJobIndex >= jobList.Num() ) {
            return  ( result | RUN_DONE );
        }
        return  ( result | RUN_PROGRESS );
    }
    while(!singleJob);

    return result;
}

// Common.cpp 文件 idCommonLocal::Init 函数会调用 gameThread.StartWorkerThread( "Game/Draw", CORE_1B, THREAD_BELOW_NORMAL, 0x100000 ); 开启 Game 线程
- idGameThread::Run
  - idCommonLocal::Draw
    - idGame::Draw
      - idPlayerView::RenderPlayerView
        - idPlayerView::SingleView
          - idRenderWorld::RenderScene
            - build params
            - ::R_RenderView(params)    //This is the frontend (tr_frontend_main.cpp)
              {
                  R_SetupViewMatrix
                  R_SetupProjectionMatrix

                  // identify all the visible portal areas, and create view lights and view entities for all the the entityDefs and lightDefs that are in the visible portal areas
                  // 填充 tr.viewDef.viewLights 和 tr.viewDef.viewEntitys
                  static_cast<idRenderWorldLocal *>(parms->renderWorld)->FindViewLightsAndEntities()
                  {
                      PointInArea              //Walk the BSP and find the current Area
                      FlowViewThroughPortals   //Recursively pass portals to find lights and entities interacting with the view.
                  }

                  tr.frontEndJobList->Wait();  // wait for any shadow volume jobs from the previous frame to finish
                  R_AddLights();               // add any pre-generated light shadows, and calculate the light shader values
                  R_AddModels();               // adds ambient surfaces and create any necessary interaction surfaces to add to the light lists

                  R_AddInGameGuis(...);        // build up the GUIs on world surfaces
                  R_OptimizeViewLightsList();  // any viewLight that didn't have visible surfaces can have it's shadows removed
                  R_SortDrawSurfs(...);        // sort all the ambient surfaces for translucency ordering
                  R_GenerateSubViews

                  R_AddDrawViewCmd();          // add the rendering commands for this viewDef
              }

// render backend thread
- WinMain
  - idCommonLocal::Frame()
    // 生成静态中间交互数据 idRenderWorldLocal::interactionTable
    - idCommonLocal::ExecuteMapChange
      - idRenderWorldLocal::InitFromMap
        - idRenderWorldLocal::ReadBinaryModel
          - idRenderModelMD5::LoadBinaryModel
            - vertexCache.AllocStaticVertex(deform.verts, ALIGN(..., VERTEX_CACHE_ALIGN ) );
      - idRenderWorldLocal::GenerateAllInteractions()
        - idInteraction** R_ClearedStaticAlloc(size)   // 为interactionTable分配内存 interactionTable中存储的是idInteraction* 指针
        - idInteraction::AllocAndLink(edef, ldef)
          - interaction = idRenderWorldLocal::interactionAllocator                     // 为 idInteraction分配内存
          - idRenderEntityLocal::firstInteraction/lastInteraction = interaction        // 填充更新 idRenderEntityLocal
          - idRenderLightLocal::firstInteraction/lastInteraction  = interaction        // 填充更新 idRenderLightLocal
          - interaction.entityDef = edef; interaction.lightDef  = ldef;                // 填充 interaction 的 entityDef lightDef
          - interactionTable[index] = interaction                                      // 填充/更新 interactionTable 内容
        - idInteraction::UnlinkAndFree
          - interactionTable[index] = NULL                                             // 重置 interactionTable 指定项为 NULL
          - idRenderWorldLocal::interactionAllocator.Free(interaction);                // 释放 interaction
        - idInteraction::CreateStaticInteraction
          - interaction.surfaces                                                       // 填充 interaction 的 entityDef lightDef
          - idInteraction::MakeEmpty
            - interactionTable[index] = INTERACTION_EMPTY                              // 更新 interactionTable 内容
      - idRenderSystemLocal::EndLevelLoad
          - idRenderModelManagerLocal::EndLevelLoad
            - R_CreateStaticBuffersForTri
              - vertexCache.AllocStaticIndex( tri.indexes, ALIGN(..., INDEX_CACHE_ALIGN ) );
              - vertexCache.AllocStaticVertex( tri.verts, ALIGN(..., VERTEX_CACHE_ALIGN ) );
              - vertexCache.AllocStaticVertex( tri.staticShadowVertexes, shadowSize );

// render frontend thread
- R_AddModels
  - R_AddSingleModel
    // 处理动态物体
    - R_EntityDefDynamicModel
    - idRenderMatrix::CullBoundsToMVP( vEntity->mvp, tris->bounds );               // 判断模型可见性
    - vertexCache.AllocIndex(tri->indexes, ALIGN(..., INDEX_CACHE_ALIGN ) );       // 上传索引数据
    - vertexCache.AllocVertex(tri->verts, ALIGN(..., VERTEX_CACHE_ALIGN ) );       // 上传顶点数据

    // 使用静态中间交互数据
    - staticInteractions[numContactedLights] = world->interactionTable[];          // 筛出摄像机可见的交互
    - surfInter = &interaction->surfaces[surfaceNum];                              // 得到对应的surf
    - surfInter->lightTrisIndexCache; surfInter->shadowIndexCache;                 // 填充 viewEntity_t::drawSurfs
  - R_LinkDrawSurfToView                                                           // 将前一步得到的 drawSurfs 转移到 tr.viewDef（viewDef_t::drawSurfs）

// 下面为其中一种 render frontend 生成的绘制命令
struct drawSurfsCommand_t
{
    renderCommand_t     commandId;
    renderCommand_t *   next;
    viewDef_t *         viewDef;
};

// viewDefs are allocated on the frame temporary stack memory
struct viewDef_t {
    renderView_t        renderView;             // specified in the call to DrawScene()

    float               projectionMatrix[16];
    idRenderMatrix      projectionRenderMatrix; // tech5 version of projectionMatrix
    viewEntity_t        worldSpace;

    idRenderWorldLocal *renderWorld;

    // drawSurfs are the visible surfaces of the viewEntities, sorted
    // by the material sort parameter
    drawSurf_t **       drawSurfs;              // we don't use an idList for this, because
    int                 numDrawSurfs;           // it is allocated in frame temporary memory
    int                 maxDrawSurfs;           // may be resized

    viewLight_t *       viewLights;             // chain of all viewLights effecting view
    viewEntity_t *      viewEntitys;            // chain of all viewEntities effecting view, including off screen ones casting shadows

    // .......
};

// viewLights are allocated on the frame temporary stack memory
// a viewLight contains everything that the back end needs out of an idRenderLightLocal,
// which the front end may be modifying simultaniously if running in SMP mode.
// a viewLight may exist even without any surfaces, and may be relevent for fogging,
// but should never exist if its volume does not intersect the view frustum
struct viewLight_t {
    viewLight_t *           next;

    // back end should NOT reference the lightDef, because it can change when running SMP
    idRenderLightLocal *    lightDef;

    // R_AddSingleLight builds this list of entities that need to be added
    // to the viewEntities list because they potentially cast shadows into
    // the view, even though the aren't directly visible
    shadowOnlyEntity_t *    shadowOnlyViewEntities;

    enum interactionState_t {
        INTERACTION_UNCHECKED,
        INTERACTION_NO,
        INTERACTION_YES
    };
    byte *                  entityInteractionState;     // [numEntities]

    idVec3                  globalLightOrigin;          // global light origin used by backend
    idPlane                 lightProject[4];            // light project used by backend
    idPlane                 fogPlane;                   // fog plane for backend fog volume rendering
    idRenderMatrix          inverseBaseLightProject;    // the matrix for deforming the 'zeroOneCubeModel' to exactly cover the light volume in world space
    const idMaterial *      lightShader;                // light shader used by backend
    const float *           shaderRegisters;            // shader registers used by backend
    idImage *               falloffImage;               // falloff image used by backend

    drawSurf_t *            globalShadows;              // shadow everything
    drawSurf_t *            localInteractions;          // don't get local shadows
    drawSurf_t *            localShadows;               // don't shadow local surfaces
    drawSurf_t *            globalInteractions;         // get shadows from everything
    drawSurf_t *            translucentInteractions;    // translucent interactions don't get shadows

    // R_AddSingleLight will build a chain of parameters here to setup shadow volumes
    preLightShadowVolumeParms_t *   preLightShadowVolumes;
};

// a viewEntity is created whenever a idRenderEntityLocal is considered for inclusion
// in the current view, but it may still turn out to be culled.
// viewEntity are allocated on the frame temporary stack memory
// a viewEntity contains everything that the back end needs out of a idRenderEntityLocal,
// which the front end may be modifying simultaneously if running in SMP mode.
// A single entityDef can generate multiple viewEntity_t in a single frame, as when seen in a mirror
struct viewEntity_t {
    viewEntity_t *          next;

    // back end should NOT reference the entityDef, because it can change when running SMP
    idRenderEntityLocal *   entityDef;

    // for scissor clipping, local inside renderView viewport
    // scissorRect.Empty() is true if the viewEntity_t was never actually
    // seen through any portals, but was created for shadow casting.
    // a viewEntity can have a non-empty scissorRect, meaning that an area
    // that it is in is visible, and still not be visible.
    idScreenRect            scissorRect;

    float                   modelMatrix[16];        // local coords to global coords
    float                   modelViewMatrix[16];    // local coords to eye coords

    idRenderMatrix          mvp;

    // parallelAddModels will build a chain of surfaces here that will need to
    // be linked to the lights or added to the drawsurf list in a serial code section
    drawSurf_t *            drawSurfs;

    // R_AddSingleModel will build a chain of parameters here to setup shadow volumes
    staticShadowVolumeParms_t *     staticShadowVolumes;
    dynamicShadowVolumeParms_t *    dynamicShadowVolumes;
    // ......
};

class idInteraction {
public:
    // this may be 0 if the light and entity do not actually intersect
    // -1 = an untested interaction
    int                     numSurfaces;

    // if there is a whole-entity optimized shadow hull, it will
    // be present as a surfaceInteraction_t with a NULL ambientTris, but
    // possibly having a shader to specify the shadow sorting order
    // (FIXME: actually try making shadow hulls?  we never did.)
    surfaceInteraction_t *  surfaces;

    // get space from here, if NULL, it is a pre-generated shadow volume from dmap
    idRenderEntityLocal *   entityDef;
    idRenderLightLocal *    lightDef;

    idInteraction *         lightNext;              // for lightDef chains
    idInteraction *         lightPrev;
    idInteraction *         entityNext;             // for entityDef chains
    idInteraction *         entityPrev;

    bool                    staticInteraction;      // true if the interaction was created at map load time in static buffer space
    // ......
};

// render backend thread
- WinMain
  - idCommonLocal::Frame()
    - idRenderSystemLocal::SwapCommandBuffers
      - SwapCommandBuffers_FinishRendering()                      // 等待之前的commandBuffers 执行完成
        - GL_BlockingSwapBuffers()
          - GLimp_SwapBuffers()
      - SwapCommandBuffers_FinishCommandBuffers()                 // 返回前一帧 render front生成的 commandBuffer
          - R_ToggleSmpFrame()                                    // 切换commandBuffer (交替使用两个frameData 对象)
    - gameThread.RunGameAndDraw();
      - gameThread.WaitForThread()                                // 等待 frontend 执行完成 (这里 signalWorkerDone 信号应该已经是触发状态，因此该 Wait 会立即返回)
        - signalWorkerDone.Wait( idSysSignal::WAIT_INFINITE )
      - idGameThread::SignalWork()                                // 触发 frontend 继续执行
        - moreWorkToDo = true;
        - signalWorkerDone.Clear();
        - signalMoreWorkToDo.Raise();
    - idRenderSystemLocal::RenderCommandBuffers                   // 渲染前一帧记录的 commandBuffer
      - RB_ExecuteBackEndCommands
        - RB_DrawView(cmds, 0)
          - RB_DrawViewInternal(cmd->viewDef, stereoEye)
    - gameThread.WaitForThread()                                  // 等待 frontend 执行完成 ()
        - signalWorkerDone.Wait( idSysSignal::WAIT_INFINITE )

// render frontend thread
idSysThread::ThreadProc() // Thread.cpp
{
    for( ; ; ) {
        thread->signalMutex.Lock();
        if ( thread->moreWorkToDo )
        {
            thread->moreWorkToDo = false;
            thread->signalMoreWorkToDo.Clear();                                   // 本次循环即将完成工作，因此设置signalMoreWorkToDo 信号为未触发，即没有更多工作需要做
            thread->signalMutex.Unlock();
        }
        else
        {
            thread->signalWorkerDone.Raise();                                     // 前一次循环完成了工作，因此设置 signalWorkerDone 信号为触发，即工作完成
            thread->signalMutex.Unlock();
            thread->signalMoreWorkToDo.Wait( idSysSignal::WAIT_INFINITE );        // 阻塞等待更多工作
            continue;
        }

        if ( thread->isTerminating ) {
            break;
        }

        retVal = thread->Run();                                                   // 执行 render frontend 工作
    }
}

- idGameThread::Run
  - idGameLocal::RunFrame                       // game 更新逻辑
    - SortActiveEntityList()
    - entity->GetPhysics()->UpdateTime(time)
    - RunEntityThink
    - entity->activeNode.Remove
  - idCommonLocal::Draw()                       // render frontend 生成中间表示数据、中间交互数据
    - R_RenderView(params)                      // (tr_frontend_main.cpp)
      - R_AddDrawViewCmd                        
        - R_GetCommandBuffer                    // 将新生成的渲染命令添加到 frameData 中

if ( glConfig.syncAvailable ) {
    swapIndex ^= 1;

    if ( qglIsSync( renderSync[swapIndex] ) ) {                                               // 判断 renderSync[swapIndex] 是否是同步对象
        qglDeleteSync( renderSync[swapIndex] );                                               // 删除同步对象
    }
    // draw something tiny to ensure the sync is after the swap
    const int start = Sys_Milliseconds();
    qglScissor( 0, 0, 1, 1 );
    qglEnable( GL_SCISSOR_TEST );
    qglClear( GL_COLOR_BUFFER_BIT );
    renderSync[swapIndex] = qglFenceSync( GL_SYNC_GPU_COMMANDS_COMPLETE, 0 );                 // 创建同步对象
    const int end = Sys_Milliseconds();
    if ( r_showSwapBuffers.GetBool() && end - start > 1 ) {
        common->Printf( "%i msec to start fence\n", end - start );
    }

    GLsync  syncToWaitOn;
    if ( r_syncEveryFrame.GetBool() ) {
        syncToWaitOn = renderSync[swapIndex];
    } else {
        syncToWaitOn = renderSync[!swapIndex];
    }

    if ( qglIsSync( syncToWaitOn ) ) {
        for ( GLenum r = GL_TIMEOUT_EXPIRED; r == GL_TIMEOUT_EXPIRED; ) {
            r = qglClientWaitSync( syncToWaitOn, GL_SYNC_FLUSH_COMMANDS_BIT, 1000 * 1000 );   // 等待同步对象完成
        }
    }
}