COP2/COP2_CookScheduler.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 * 
 * Produced by:
 *      Luke Moore
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        COP2_CookScheduler.h
 *
 * COMMENTS:
 *      This singleton class determines the order that cop nodes will be
 *      cooked, starts up the threads, and tells each thread what to do
 *      next.
 */

#ifndef __COP2_CookScheduler_h__
#define __COP2_CookScheduler_h__

#include "COP2_API.h"
#include <UT/UT_Rect.h>
#include <UT/UT_RefArray.h>
#include <UT/UT_PtrArray.h>
#include <UT/UT_Lock.h>
#include <UT/UT_IntArray.h>
#include <LM/LM_Defines.h>
#include <LM/LM_ProductInfo.h>

#include <TIL/TIL_Defines.h>
#include "COP2_ThreadCookParms.h"
class TIL_Raster;
class TIL_TileMPlay;
class TIL_Plane;
class TIL_Sequence;
class OP_Context;
class COP2_Node;
class COP2_Context;
class COP2_CookAreaInfo;
class COP2_CheckpointWrapper;
class COP2_CheckpointPlaneWrapper;
class COP2_CookAreaList;

class COP2_API COP2_CookScheduler
{
public:
    COP2_CookScheduler();

    // These methods are called by COP2_Node::cookToRaster():
    // ---------------------------------------------------------------------
    void cookNodeToRaster(COP2_Node &node, UT_PtrArray<OP_Context *> &contexts,
                          UT_PtrArray<const TIL_Plane *> &ref_planes,
                          UT_PtrArray<const int *> &compmap,
                          UT_RefArray<UT_InclusiveRect> &bounds,
                          UT_PtrArray<TIL_Raster *> &rasters,
                          UT_PtrArray<TIL_Raster *> *tile_rasters,
                          int tile_index,
                          TIL_TileMPlay *output_device,
                          UT_IntArray &array_indices, int compindex,
                          float black, float white,
                          int ignore_bwpoints, 
                          float gamma, bool clean_up_regions,
                          int &num_threads, bool &completed);


    // These methods are used by/called by threads:
    // ---------------------------------------------------------------------

    // This static method is the starting point of a thread.  The data
    // is a pointer to an integer containing the thread number.
    static void *threadStartCallback(void *data);

    // Threads call this method to find out which plane they should cook
    // next. If blocked is true, we are temporarily out of data to cook.
    COP2_ThreadCookParms *getThreadCookParms(int thread_index,
                                             bool &blocked);

    // Threads call this method when they're done cooking a plane.
    void         doneWithThreadCookParms(COP2_ThreadCookParms &thread_parms);

    // When checkpointing is on, one of the threads calls this method to update
    // the progress meter in the viewport.
    float        getPercentageComplete(int num_extra_tiles_cooked) const;

    // Misc methods:
    // ---------------------------------------------------------------------

    // This method is used by the tile cache to determine if a plane is
    // still checkpointed.
    static bool  isPlaneStillCheckpointedCallback(void *opaque_cop_node,
                                                  const char *plane_name,
                                                  float cook_time);

    // Other parts of the code call this method to see if checkpointing is
    // being used.
    bool         isUsingCheckpointing() const { return myUseCheckpointing; }

    // Other parts of the code call this method to see if anything is currently
    // being cooked.
    bool         isCookingSomething() const { return myFinalNode != 0; }

    // This method returns the scale factor for the cooking resolution,
    // relative to the full resolution.
    void         getResScaleFactor(float &xres_scale_factor,
                                   float &yres_scale_factor) const;

    // This method applies the cooking resolution scale factor to the
    // sequence's resolution, returning the scaled resolution.
    void         getScaledRes(const TIL_Sequence &sequence,
                              int &scaled_xres, int &scaled_yres);

    // This method returns how many threads the cook scheduler will use if
    // invoked.  It is called by COP2_Node::cookFlipbook() so it can break
    // up the different tiles across different threads.
    int          getNumThreadsToUse() const;

    // There return true if GPU and SPU units are available to assist the CPU
    // with computation.
    bool         canUseGPU() const;
    bool         canUseCellSPU() const;
    

    // This method returns how many threads are currently in use by the cook
    // scheduler as it's cooking.  It is called when COP2_Node updates the
    // performance monitor.
    int          getNumThreadsUsedInCook() const;

    const COP2_CookAreaInfo * getAreaInfo(COP2_Context &context,
                                          const COP2_Node *node) const;

    // finds dependencies in 'ancestor' for 'cooknode'. Returns false if
    // no dependencies exist.
    bool         getDependentsFor(COP2_Context &context,
                                  COP2_Node *cooknode,
                                  COP2_Node *ancestor,
                                  UT_PtrArray<COP2_Context *> &dependencies);

    // prints the cached planes and cook order, with bounds, to stderr.
    void         debugDumpPlaneOrder();

    // gets all the planes that this node requires in the current cook.
    // Must be called within a cook. Do not delete the planes!
    //
    void  getPlanesForNode(COP2_Node *node,
                           UT_PtrArray<const TIL_Plane *> &planes,
                           UT_IntArray &array_index) const;
    void blockUntilReady();
private:
    // Methods to set up the cook/clean up after the cook:
    // ---------------------------------------------------------------------

    void                 setOutputRaster(
                                UT_PtrArray<TIL_Raster *> &raster,
                                UT_PtrArray<TIL_Raster *> *tile_rasters,
                                int tile_index,
                                TIL_TileMPlay *output_device,
                                int compindex);

    void                 setFinalPlanesToCook(
                                COP2_Node &node,
                                UT_PtrArray<OP_Context *> &contexts,
                                UT_PtrArray<const TIL_Plane *> &ref_planes,
                                UT_IntArray &array_indicies,
                                UT_RefArray<UT_InclusiveRect> &bounds,
                                bool clean_up_regions);

    void                 setThreadCommonParms(
                                float black,
                                float white,
                                int ignore_bwpoints,
                                float gamma);

    void                 setRasterInThreadParms(
                                COP2_Node &node,
                                int thread_index,
                                const TIL_Plane *for_plane,
                                float t);

    void                 clearCookInformation();


    // Methods to choose the cook order:
    // ---------------------------------------------------------------------

    void                 createListOfPlanesBeingCooked(
                            COP2_CheckpointPlaneWrapper &root_plane_wrapper);

    COP2_CheckpointWrapper *getOrCreateNodeCheckpointWrapper(COP2_Node &node);

    UT_PtrArray<COP2_CheckpointPlaneWrapper *> buildDependencyTree();

    UT_PtrArray<COP2_CheckpointPlaneWrapper *> createWrappersForFinalOutput();

    bool                 isPlaneCached(COP2_CheckpointPlaneWrapper &wrapper);

    void                 checkpointCachedPlanes();

    void                 getPossibleInputAreasForPlane(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                COP2_CookAreaList &input_areas);

    void                 determinePlaneDependencies(
                                COP2_CheckpointWrapper &wrapper,
                                int &num_tiles, int &num_planes);

    void                 applyResScaleFactor(
                                int full_xres, int full_yres,
                                int &scaled_xres, int &scaled_yres);

    COP2_CheckpointPlaneWrapper *findCookOrderTarget(
                            UT_PtrArray<COP2_CheckpointPlaneWrapper *> &votes,
                            COP2_CheckpointPlaneWrapper *last_plane);

    COP2_CheckpointPlaneWrapper *findCookOrderCurrent(
                                COP2_CheckpointPlaneWrapper &target);

    COP2_CheckpointPlaneWrapper *findCookOrderCurrent(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                COP2_CheckpointPlaneWrapper *result,
                                int &max_depth,
                                int &min_parents);

    COP2_CheckpointPlaneWrapper *determineNextPlaneInCookOrder(
                            UT_PtrArray<COP2_CheckpointPlaneWrapper *> &
                                                            current_locks,
                            UT_PtrArray<COP2_CheckpointPlaneWrapper *> &votes);

    void                 determineCookingOrder();

    // Methods to handle requests for planes to cook and notifications that
    // planes are done cooking:
    // ---------------------------------------------------------------------

    COP2_CheckpointWrapper *findPlaneForThreadToCook(int thread_index);

    void                 doneCookingPlane(
                                int thread_index,
                                COP2_Node &node,
                                const TIL_Plane &plane,
                                float time);

    COP2_CheckpointPlaneWrapper *getPlaneToCook(int thread_index,
                                                bool &blocked);

    bool                 isPlaneBeingCookedByAnyThread(
                                COP2_CheckpointPlaneWrapper &plane_wrapper);

    bool                 isPlaneBeingCookedByThreadOtherThan(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                int thread_index);

    void                 getNumThreadsCookingNodeAndPlane(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                int &threads_in_node, int &threads_in_plane,
                                int &threads_in_op_type);

    void                 markPlaneAsBeingCooked(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                int thread_index);

    int                  findPlaneParmIndexForWrapperPlane(
                                int thread_index,
                                int total_num_threads,
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                bool &cooked_by_another_thread);

    void                 unlockCheckpointsAfterCookingPlane(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                int thread_index);

    void                 unlockAllCheckpointedPlanes(int thread_index);

    void                 uncheckpointPlane(
                                COP2_CheckpointPlaneWrapper &plane_wrapper,
                                int thread_index);

    void                 cleanUpAfterCookingNode(
                                            COP2_CheckpointWrapper &wrapper);

    // Data:
    COP2_CommonCookParms myCommonParms;
    COP2_PlaneCookParms  myPlaneParms[TIL_MAX_THREADS];
    COP2_ThreadCookParms myThreadParms[TIL_MAX_THREADS];

    UT_Lock              myLock;
    UT_Lock              myMessageLock;
    
    COP2_Node           *myFinalNode;
    UT_PtrArray<OP_Context *> myFinalContexts;
    UT_PtrArray<const TIL_Plane *> myFinalPlanes;
    UT_IntArray          myFinalArrayIndices;
    UT_RefArray<UT_InclusiveRect> myFinalBounds;
    bool                 myCleanUpRegionsOfFinalNode;
    float                myXResScaleFactor;
    float                myYResScaleFactor;

    UT_PtrArray<TIL_Raster *> myRasters;
    UT_PtrArray<TIL_Raster *> *myTileRasters;
    UT_PtrArray<const int *>  myCompMaps;
    TIL_TileMPlay       *myOutputDevice;
    int                  myTileIndex;
    int                  myCompIndex;

    // The set of planes being cooked:
    UT_PtrArray<COP2_CheckpointPlaneWrapper *> myPlaneSet;
    // The order in which the planes will be cooked:
    UT_PtrArray<COP2_CheckpointPlaneWrapper *> myPlaneOrder;
    // The input planes that are already in the cache:
    UT_PtrArray<COP2_CheckpointPlaneWrapper *> myCachedPlanes;

    UT_PtrArray<COP2_Node *> myNodesWithWrappers;

    int                  myIndexToNextPlaneToCook; // updated as planes cook

    // For each thread that's cooking, this array contains a pointer to the
    // wrapper for the plane that thread is cooking, or 0 if that thread
    // isn't cooking any planes.
    COP2_CheckpointPlaneWrapper *myPlanesCookedByThreads[TIL_MAX_THREADS];

    int                  myNumPlanesCooked;
    int                  myNumTilesCooked;
    int                  myTotalNumPlanes;
    int                  myTotalNumTiles;

    bool                 myUseCheckpointing;    // is checkpointing turned on?
    bool                 myCheckpointAllFlag;   // ignore cached nodes
    bool                 myAllowGPUInOtherThreads;
    bool                 myGPUFatalError;
};

// This function returns the singleton instance of the cook scheduler.
COP2_API extern COP2_CookScheduler &COP2getCookScheduler();

#endif

---