gml_GRItem_ClippingCache.h

00001 // gml_GRItem_ClippingCache.h --
00002 //
00003 //  Declares the "gml_TGRItem_ClippingCache" class. An object of this class is used to
00004 //    remember (cache) the clipping buffer level used by a GRItem. The clipping plane
00005 //    is typically 8bit so there are 8 clipping levels available.
00006 //
00007 //  Copyright (c) 2004 CLIPS-IMAG.
00008 //
00009 //  See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00010 //  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00011 //
00012 //  Jan. 10, 2005: (FB)
00013 //    Create an opaque type for a cache slot. Create a method to get the clipping buffer
00014 //      level from a cache slot.
00015 //    Removed reference to a clipper's clipper in "GetCacheSlot".
00016 //
00017 //  November 2004:
00018 //    renamed from gml_CacheList to gml_GRItem_ClippingCache
00019 //
00020 //  October 2004:
00021 //    renamed from gml_GRItem_CacheList to gml_CacheList
00022 //
00023 //  Created on July 2004 (Sylvie Rouillard).
00024 
00025 #ifndef __GML_GRITEM_CLIPPINGCACHE__
00026 #define __GML_GRITEM_CLIPPINGCACHE__
00027 
00028 #include "gml/base/gml_Types.h"
00029 #include "gml/base/gml_List.h"
00030 
00031 
00032 
00033 // gml_TGRItem_ClippingCache --
00034 //
00035 //  WARNING: this class is not thread safe: slots should not be requested / used / released
00036 //  from different threads.
00037 
00038 typedef gml_TPointer gml_TGRItem_ClippingCacheSlot;
00039 
00040 class gml_TGRItem_ClippingCache
00041 {
00042 public:
00043 
00044   // Init --
00045   //
00046   //  <nbLevel> is the number of available clipping levels. Must be at least 2.
00047   
00048   gml_TError            Init (int nbLevel);
00049 
00050   // Dispose --
00051 
00052   void                  Dispose ();
00053 
00054   // Reset --
00055   //
00056   //  Set all clipping levels as available.
00057 
00058   void Reset ();
00059   
00060   // GetCacheSlot --
00061   //
00062   //  Requests a slot in the cache.
00063   //    <client>      is the client object which will be allocated the slot.
00064   //  Returns the allocated slot. The clipping level can be retrieved by passing
00065   //    the returned value to "GetLevelFromSlot".
00066   //
00067   //  WARNING! The slot attributed to the client may soon be attributed to another client
00068   //    if the cache is full. Thus, before using a slot, if not immediately after "GetCacheSlot",
00069   //    one should call "IsInCache" to check if the slot is still allocated to the client.
00070   
00071   gml_TGRItem_ClippingCacheSlot
00072                         GetCacheSlot (gml_TPointer client);
00073   
00074   // GetLevelFromSlot --
00075   //
00076   //  Returns the clipping plane level of the cache slot <slot>.
00077 
00078   int                   GetLevelFromSlot (gml_TGRItem_ClippingCacheSlot slot);
00079   
00080   // IsInCache --
00081   //
00082   //  Returns true if the slot <slot> is allocated to client object <client>, else returns false.
00083   //  Returns false if <slot> is NULL.
00084 
00085   gml_TBoolean          IsInCache (gml_TGRItem_ClippingCacheSlot slot, gml_TPointer client);
00086 
00087   // ReleaseSlot --
00088   //
00089   //  Returns the slot <slot> to the cache if it is still alocated to client <client>:
00090   //    this slot is no longer used by the client and can be reallocated to another client.
00091   //  If <slot> is NULL or <slot> client is not <client>, the function simply returns.
00092 
00093   void                  ReleaseSlot (gml_TGRItem_ClippingCacheSlot slot, gml_TPointer client);
00094 
00095 
00096 
00097 protected:
00098 
00099   int                   fNbLevel; /* number of element in the cache (from 0 to level-1)   */
00100   gml_TList*            fFree;    /* list of free slots                                   */
00101   gml_TList*            fUsed;    /* list of used slots                                   */
00102 
00103 };
00104 
00105 #endif //__GML_GRITEM_CLIPPINGCACHE__