Index: ps/trunk/source/gui/CGUI.cpp
===================================================================
--- ps/trunk/source/gui/CGUI.cpp	(revision 3585)
+++ ps/trunk/source/gui/CGUI.cpp	(revision 3586)
@@ -1,1888 +1,1895 @@
 /*
 CGUI
 by Gustav Larsson
 gee@pyro.nu
 */
 
 #include "precompiled.h"
 
 #include <string>
 
 #include <stdarg.h>
 
 #include "lib/res/graphics/unifont.h"
 
 #include "GUI.h"
 
 // Types - when including them into the engine.
 #include "CButton.h"
 #include "CImage.h"
 #include "CText.h"
 #include "CCheckBox.h"
 #include "CRadioButton.h"
 #include "CInput.h"
 #include "CList.h"
 #include "CDropDown.h"
 #include "CProgressBar.h"
 #include "CTooltip.h"
 #include "MiniMap.h"
 
 #include "ps/XML/Xeromyces.h"
 #include "ps/Font.h"
 
 #include "Pyrogenesis.h"
 #include "input.h"
 #include "OverlayText.h"
 // TODO Gee: Whatever include CRect/CPos/CSize
 #include "Overlay.h"
 
 #include "scripting/ScriptingHost.h"
 #include "Hotkey.h"
 #include "ps/Globals.h"
 #include "lib/timer.h"
 
 // namespaces used
 using namespace std;
 const double SELECT_DBLCLICK_RATE = 0.5;
 #include "ps/CLogger.h"
 #define LOG_CATEGORY "gui"
 
 
 // Class for global JavaScript object
 JSClass GUIClass = {
 	"GUIClass", 0,
 	JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_PropertyStub,
 	JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, JS_FinalizeStub,
 };
 
 
 //-------------------------------------------------------------------
 //	called from main loop when (input) events are received.
 //	event is passed to other handlers if false is returned.
 //	trampoline: we don't want to make the implementation (in CGUI) static
 //-------------------------------------------------------------------
 InReaction gui_handler(const SDL_Event* ev)
 {
 	return g_GUI.HandleEvent(ev);
 }
 
 
 InReaction CGUI::HandleEvent(const SDL_Event* ev)
 {
 	InReaction ret = IN_PASS;
 
 	if (ev->type == SDL_GUIHOTKEYPRESS)
 	{
 		const CStr& objectName = *(CStr*) ev->user.data1;
 		IGUIObject* object = FindObjectByName(objectName);
 		if (! object)
 		{
 			LOG(ERROR, LOG_CATEGORY, "Cannot find hotkeyed object '%s'", objectName.c_str());
 		}
 		else
 		{
 			object->HandleMessage( SGUIMessage( GUIM_PRESSED ) );
 			object->ScriptEvent("press");
 		}
 	}
 
 	else if (ev->type == SDL_MOUSEMOTION)
 	{
 		// Yes the mouse position is stored as float to avoid
 		//  constant conversions when operating in a
 		//  float-based environment.
 		m_MousePos = CPos((float)ev->motion.x, (float)ev->motion.y);
 
 		GUI<SGUIMessage>::RecurseObject(GUIRR_HIDDEN | GUIRR_GHOST, m_BaseObject, 
 										&IGUIObject::HandleMessage, 
 										SGUIMessage(GUIM_MOUSE_MOTION));
 	}
 
 	// Update m_MouseButtons. (BUTTONUP is handled later.)
 	else if (ev->type == SDL_MOUSEBUTTONDOWN)
 	{
 		switch (ev->button.button)
 		{
 		case SDL_BUTTON_LEFT:
 		case SDL_BUTTON_RIGHT:
 		case SDL_BUTTON_MIDDLE:
 			m_MouseButtons |= BIT(ev->button.button);
 			break;
 		default:
 			break;
 		}
 	}
 
 // JW: (pre|post)process omitted; what're they for? why would we need any special button_released handling?
 
 	// Only one object can be hovered
 	IGUIObject *pNearest = NULL;
 
 	// TODO Gee: (2004-09-08) Big TODO, don't do the below if the SDL_Event is something like a keypress!
 	try
 	{
 		// TODO Gee: Optimizations needed!
 		//  these two recursive function are quite overhead heavy.
 
 		// pNearest will after this point at the hovered object, possibly NULL
 		GUI<IGUIObject*>::RecurseObject(GUIRR_HIDDEN | GUIRR_GHOST, m_BaseObject, 
 										&IGUIObject::ChooseMouseOverAndClosest, 
 										pNearest);
 
 		// Is placed in the UpdateMouseOver function
 		//if (ev->type == SDL_MOUSEMOTION && pNearest)
 		//	pNearest->ScriptEvent("mousemove");
 
 		// Now we'll call UpdateMouseOver on *all* objects,
 		//  we'll input the one hovered, and they will each
 		//  update their own data and send messages accordingly
 		
 		GUI<IGUIObject*>::RecurseObject(GUIRR_HIDDEN | GUIRR_GHOST, m_BaseObject, 
 										&IGUIObject::UpdateMouseOver, 
 										pNearest);
 
 		if (ev->type == SDL_MOUSEBUTTONDOWN)
 		{
 			switch (ev->button.button)
 			{
 			case SDL_BUTTON_LEFT:
 				if (pNearest)
 				{
 					if (pNearest != m_FocusedObject)
 					{
 						// Update focused object
 						if (m_FocusedObject)
 							m_FocusedObject->HandleMessage(SGUIMessage(GUIM_LOST_FOCUS));
 						m_FocusedObject = pNearest;
 						m_FocusedObject->HandleMessage(SGUIMessage(GUIM_GOT_FOCUS));
 					}
 
 					pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_PRESS_LEFT));
 					pNearest->ScriptEvent("mouseleftpress");
 
 					// Block event, so things on the map (behind the GUI) won't be pressed
 					ret = IN_HANDLED;
 				}
 				else if (m_FocusedObject)
 				{
 					m_FocusedObject->HandleMessage(SGUIMessage(GUIM_LOST_FOCUS));
 					//if (m_FocusedObject-> TODO SelfishFocus?
 					m_FocusedObject = 0;
 				}
 				break;
 
 			case SDL_BUTTON_WHEELDOWN: // wheel down
 				if (pNearest)
 				{
 					pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_WHEEL_DOWN));
 					pNearest->ScriptEvent("mousewheeldown");
 
 					ret = IN_HANDLED;
 				}
 				break;
 
 			case SDL_BUTTON_WHEELUP: // wheel up
 				if (pNearest)
 				{
 					pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_WHEEL_UP));
 					pNearest->ScriptEvent("mousewheelup"); 
 
 					ret = IN_HANDLED;
 				}
 				break;
 
 			default:
 				break;
 			}
 		}
 		else 
 		if (ev->type == SDL_MOUSEBUTTONUP)
 		{
 			switch (ev->button.button)
 			{
 			case SDL_BUTTON_LEFT:
 				if (pNearest)
 				{
 					double timeElapsed = get_time() - pNearest->m_LastClickTime[SDL_BUTTON_LEFT];
 					pNearest->m_LastClickTime[SDL_BUTTON_LEFT] = get_time();
 					
 					//Double click?
 					if (timeElapsed < SELECT_DBLCLICK_RATE)
 					{
 						pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_DBLCLICK_LEFT));
 						pNearest->ScriptEvent("mouseleftdoubleclick");
 					}
 					else
 					{
 						pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_RELEASE_LEFT));
 						pNearest->ScriptEvent("mouseleftrelease");
 					}
 
 					ret = IN_HANDLED;
 				}
 				break;
 			case SDL_BUTTON_RIGHT:
 				if (pNearest)
 				{
 					double timeElapsed = get_time() - pNearest->m_LastClickTime[SDL_BUTTON_RIGHT];
 					pNearest->m_LastClickTime[SDL_BUTTON_RIGHT] = get_time();
 					
 					//Double click?
 					if (timeElapsed < SELECT_DBLCLICK_RATE)
 					{
 						pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_DBLCLICK_RIGHT));
 						//pNearest->ScriptEvent("mouserightdoubleclick");
 					}
 					else
 					{
 						pNearest->HandleMessage(SGUIMessage(GUIM_MOUSE_RELEASE_RIGHT));
 						//pNearest->ScriptEvent("mouserightrelease");
 					}
 
 					ret = IN_HANDLED;
 				}
 				break;
 			}
 
 			// Reset all states on all visible objects
 			GUI<>::RecurseObject(GUIRR_HIDDEN, m_BaseObject, 
 									&IGUIObject::ResetStates);
 
 			// It will have reset the mouse over of the current hovered, so we'll
 			//  have to restore that
 			if (pNearest)
 				pNearest->m_MouseHovering = true;
 		}
 	}
 	catch (PS_RESULT e)
 	{
 		UNUSED2(e);
 		debug_warn("CGUI::HandleEvent error");
 		// TODO Gee: Handle
 	}
 // JW: what's the difference between mPress and mDown? what's the code below responsible for?
 /*
 	// Generally if just mouse is clicked
 	if (m_pInput->mDown(NEMM_BUTTON1) && pNearest)
 	{
 		pNearest->HandleMessage(GUIM_MOUSE_DOWN_LEFT);
 	}
 */
 
 	// BUTTONUP's effect on m_MouseButtons is handled after
 	// everything else, so that e.g. 'press' handlers (activated
 	// on button up) see which mouse button had been pressed.
 	if (ev->type == SDL_MOUSEBUTTONUP)
 	{
 		switch (ev->button.button)
 		{
 		case SDL_BUTTON_LEFT:
 		case SDL_BUTTON_RIGHT:
 		case SDL_BUTTON_MIDDLE:
 			m_MouseButtons &= ~BIT(ev->button.button);
 			break;
 		default:
 			break;
 		}
 	}
 
 	// Handle keys for input boxes
 	if (GetFocusedObject())
 	{
 		if (
 			(ev->type == SDL_KEYDOWN &&
 				ev->key.keysym.sym != SDLK_ESCAPE &&
 				!g_keys[SDLK_LCTRL] && !g_keys[SDLK_RCTRL] &&
 				!g_keys[SDLK_LALT] && !g_keys[SDLK_RALT]) 
 			|| ev->type == SDL_HOTKEYDOWN
 			)
 		{
 			ret = GetFocusedObject()->ManuallyHandleEvent(ev);
 		}
 		// else will return IN_PASS because we never used the button.
 	}
 
 	return ret;
 }
 
 void CGUI::TickObjects()
 {
 	CStr action = "tick";
 	GUI<CStr>::RecurseObject(0, m_BaseObject, 
 							&IGUIObject::ScriptEvent, action);
 
 	// Also update tooltips:
 
 	// TODO: Efficiency
 	IGUIObject* pNearest = NULL;
 	GUI<IGUIObject*>::RecurseObject(GUIRR_HIDDEN | GUIRR_GHOST, m_BaseObject, 
 		&IGUIObject::ChooseMouseOverAndClosest, 
 		pNearest);
 
 	m_Tooltip.Update(pNearest, m_MousePos, this);
 }
 
 void CGUI::SendEventToAll(CStr EventName)
 {
+	// janwas 2006-03-03: spoke with Ykkrosh about EventName case.
+	// when registering, case is converted to lower - this avoids surprise
+	// if someone were to get the case wrong and then not notice their
+	// handler is never called. however, until now, the other end
+	// (sending events here) wasn't converting to lower case,
+	// leading to a similar problem.
+	// now fixed; case is irrelevant since all are converted to lower.
 	GUI<CStr>::RecurseObject(0, m_BaseObject, 
-		&IGUIObject::ScriptEvent, EventName);
+		&IGUIObject::ScriptEvent, EventName.LowerCase());
 }
 
 //-------------------------------------------------------------------
 //  Constructor / Destructor
 //-------------------------------------------------------------------
 CGUI::CGUI() : m_MouseButtons(0), m_FocusedObject(NULL), m_InternalNameNumber(0)
 {
 	m_BaseObject = new CGUIDummyObject;
 	m_BaseObject->SetGUI(this);
 
 	// Construct the parent object for all GUI JavaScript things
 	m_ScriptObject = JS_NewObject(g_ScriptingHost.getContext(), &GUIClass, NULL, NULL);
 	debug_assert(m_ScriptObject != NULL); // How should it handle errors?
 	JS_AddRoot(g_ScriptingHost.getContext(), &m_ScriptObject);
 
 	// This will make this invisible, not add
 	//m_BaseObject->SetName(BASE_OBJECT_NAME);
 }
 
 CGUI::~CGUI()
 {
 	if (m_BaseObject)
 		delete m_BaseObject;
 
 	if (m_ScriptObject)
 		// Let it be garbage-collected
 		JS_RemoveRoot(g_ScriptingHost.getContext(), &m_ScriptObject);
 }
 
 //-------------------------------------------------------------------
 //  Functions
 //-------------------------------------------------------------------
 IGUIObject *CGUI::ConstructObject(const CStr& str)
 {
 	if (m_ObjectTypes.count(str) > 0)
 		return (*m_ObjectTypes[str])();
 	else
 	{
 		// Error reporting will be handled with the NULL return.
 		return NULL;
 	}
 }
 
 void CGUI::Initialize()
 {
 	// Add base types!
 	//  You can also add types outside the GUI to extend the flexibility of the GUI.
 	//  Pyrogenesis though will have all the object types inserted from here.
 	AddObjectType("empty",			&CGUIDummyObject::ConstructObject);
 	AddObjectType("button",			&CButton::ConstructObject);
 	AddObjectType("image",			&CImage::ConstructObject);
 	AddObjectType("text",			&CText::ConstructObject);
 	AddObjectType("checkbox",		&CCheckBox::ConstructObject);
 	AddObjectType("radiobutton",	&CRadioButton::ConstructObject);
 	AddObjectType("progressbar",	&CProgressBar::ConstructObject);
     AddObjectType("minimap",        &CMiniMap::ConstructObject);
 	AddObjectType("input",			&CInput::ConstructObject);
 
 	// The following line was commented out, I don't know if that's me or not, or
 	//  for what reason, but I'm gonna uncomment, if anything breaks, just let me
 	//  know, or if it wasn't I that commented it out, do let me know why.
 	//  -- Gee 20-07-2005
 	AddObjectType("list",			&CList::ConstructObject);
 	//
 
 	AddObjectType("dropdown",		&CDropDown::ConstructObject);
 }
 
 void CGUI::Process()
 {
 /*
 
 	// TODO Gee: check if m_pInput is valid, otherwise return
 ///	debug_assert(m_pInput);
 
 	// Pre-process all objects
 	try
 	{
 		GUI<EGUIMessage>::RecurseObject(0, m_BaseObject, &IGUIObject::HandleMessage, GUIM_PREPROCESS);
 	}
 	catch (PS_RESULT e)
 	{
 		return;
 	}
 
 	// Check mouse over
 	try
 	{
 		// Only one object can be hovered
 		//  check which one it is, if any !
 		IGUIObject *pNearest = NULL;
 
 		GUI<IGUIObject*>::RecurseObject(GUIRR_HIDDEN, m_BaseObject, &IGUIObject::ChooseMouseOverAndClosest, pNearest);
 		
 		// Now we'll call UpdateMouseOver on *all* objects,
 		//  we'll input the one hovered, and they will each
 		//  update their own data and send messages accordingly
 		GUI<IGUIObject*>::RecurseObject(GUIRR_HIDDEN, m_BaseObject, &IGUIObject::UpdateMouseOver, pNearest);
 
 		// If pressed
 		if (m_pInput->mPress(NEMM_BUTTON1) && pNearest)
 		{
 			pNearest->HandleMessage(GUIM_MOUSE_PRESS_LEFT);
 		}
 		else
 		// If released
 		if (m_pInput->mRelease(NEMM_BUTTON1) && pNearest)
 		{
 			pNearest->HandleMessage(GUIM_MOUSE_RELEASE_LEFT);
 		}
 
 		// Generally if just mouse is clicked
 		if (m_pInput->mDown(NEMM_BUTTON1) && pNearest)
 		{
 			pNearest->HandleMessage(GUIM_MOUSE_DOWN_LEFT);
 		}
 
 	}
 	catch (PS_RESULT e)
 	{
 		return;
 	}
 
 	// Post-process all objects
 	try
 	{
 		GUI<EGUIMessage>::RecurseObject(0, m_BaseObject, &IGUIObject::HandleMessage, GUIM_POSTPROCESS);
 	}
 	catch (PS_RESULT e)
 	{
 		return;
 	}
 */
 }
 
 void CGUI::Draw()
 {
 	// Clear the depth buffer, so the GUI is
 	// drawn on top of everything else
 	glClear(GL_DEPTH_BUFFER_BIT);
 	glPushMatrix();
 
 	guiLoadIdentity();
 
 	try
 	{
 		// Recurse IGUIObject::Draw() with restriction: hidden
 		//  meaning all hidden objects won't call Draw (nor will it recurse its children)
 		GUI<>::RecurseObject(GUIRR_HIDDEN, m_BaseObject, &IGUIObject::Draw);
 	}
 	catch (PS_RESULT e)
 	{
 		UNUSED2(e);
 		glPopMatrix();
 
 		// TODO Gee: Report error.
 		debug_warn("CGUI::Draw error");
 		return;
 	}
 	glPopMatrix();
 }
 
 void CGUI::DrawSprite(CGUISpriteInstance& Sprite,
 					  int CellID,
 					  const float& Z,
 					  const CRect& Rect,
 					  const CRect& UNUSED(Clipping))
 {
 	// If the sprite doesn't exist (name == ""), don't bother drawing anything
 	if (Sprite.IsEmpty())
 		return;
 
 	// TODO: Clipping?
 
 	glPushMatrix();
 	glTranslatef(0.0f, 0.0f, Z);
 
 	Sprite.Draw(Rect, CellID, m_Sprites);
 
 	glPopMatrix();
 
 }
 
 void CGUI::Destroy()
 {
 	// We can use the map to delete all
 	//  now we don't want to cancel all if one Destroy fails
 	map_pObjects::iterator it;
 	for (it = m_pAllObjects.begin(); it != m_pAllObjects.end(); ++it)
 	{
 		try
 		{
 			it->second->Destroy();
 		}
 		catch (PS_RESULT e)
 		{
 			UNUSED2(e);
 			debug_warn("CGUI::Destroy error");
 			// TODO Gee: Handle
 		}
 		
 		delete it->second;
 	}
 
 	for (std::map<CStr, CGUISprite>::iterator it2 = m_Sprites.begin(); it2 != m_Sprites.end(); ++it2)
 		for (std::vector<SGUIImage>::iterator it3 = it2->second.m_Images.begin(); it3 != it2->second.m_Images.end(); ++it3)
 			delete it3->m_Effects;
 
 	// Clear all
 	m_pAllObjects.clear();
 	m_Sprites.clear();
 	m_Icons.clear();
 }
 
 void CGUI::UpdateResolution()
 {
 	// Update ALL cached
 	GUI<>::RecurseObject(0, m_BaseObject, &IGUIObject::UpdateCachedSize );
 }
 
 void CGUI::AddObject(IGUIObject* pObject)
 {
 	try
 	{
 		// Add CGUI pointer
 		GUI<CGUI*>::RecurseObject(0, pObject, &IGUIObject::SetGUI, this);
 
 		// Add child to base object
 		m_BaseObject->AddChild(pObject); // can throw
 
 		// Cache tree
 		GUI<>::RecurseObject(0, pObject, &IGUIObject::UpdateCachedSize);
 
 		// Loaded
 		GUI<SGUIMessage>::RecurseObject(0, pObject, &IGUIObject::HandleMessage, SGUIMessage(GUIM_LOAD));
 	}
 	catch (PS_RESULT e)
 	{
 		throw e;
 	}
 }
 
 void CGUI::UpdateObjects()
 {
 	// We'll fill a temporary map until we know everything
 	//  succeeded
 	map_pObjects AllObjects;
 
 	try
 	{
 		// Fill freshly
 		GUI< map_pObjects >::RecurseObject(0, m_BaseObject, &IGUIObject::AddToPointersMap, AllObjects );
 	}
 	catch (PS_RESULT e)
 	{
 		// Throw the same error
 		throw e;
 	}
 
 	// Else actually update the real one
 	m_pAllObjects.swap(AllObjects);
 }
 
 bool CGUI::ObjectExists(const CStr& Name) const
 {
 	return m_pAllObjects.count(Name) != 0;
 }
 
 IGUIObject* CGUI::FindObjectByName(const CStr& Name) const
 {
 	map_pObjects::const_iterator it = m_pAllObjects.find(Name);
 	if (it == m_pAllObjects.end())
 		return NULL;
 	else
 		return it->second;
 }
 
 
 // private struct used only in GenerateText(...)
 struct SGenerateTextImage
 {
 	float m_YFrom,			// The image's starting location in Y
 		  m_YTo,			// The image's end location in Y
 		  m_Indentation;	// The image width in other words
 
 	// Some help functions
 	// TODO Gee: CRect => CPoint ?
 	void SetupSpriteCall(const bool Left, SGUIText::SSpriteCall &SpriteCall, 
 						 const float width, const float y,
 						 const CSize &Size, const CStr &TextureName, 
 						 const float BufferZone, const int CellID)
 	{
 		// TODO Gee: Temp hardcoded values
 		SpriteCall.m_Area.top = y+BufferZone;
 		SpriteCall.m_Area.bottom = y+BufferZone + Size.cy;
 		
 		if (Left)
 		{
 			SpriteCall.m_Area.left = BufferZone;
 			SpriteCall.m_Area.right = Size.cx+BufferZone;
 		}
 		else
 		{
 			SpriteCall.m_Area.left = width-BufferZone - Size.cx;
 			SpriteCall.m_Area.right = width-BufferZone;
 		}
 
 		SpriteCall.m_CellID = CellID;
 		SpriteCall.m_Sprite = TextureName;
 
 		m_YFrom = SpriteCall.m_Area.top-BufferZone;
 		m_YTo = SpriteCall.m_Area.bottom+BufferZone;
 		m_Indentation = Size.cx+BufferZone*2;
 	}
 };
 
 SGUIText CGUI::GenerateText(const CGUIString &string,
 							const CStr& Font, const float &Width, const float &BufferZone, 
 							const IGUIObject *pObject)
 {
 	SGUIText Text; // object we're generating
 	
 	if (string.m_Words.size() == 0)
 		return Text;
 
 	float x=BufferZone, y=BufferZone; // drawing pointer
 	int from=0;
 	bool done=false;
 
 	bool FirstLine = true;	// Necessary because text in the first line is shorter
 							// (it doesn't count the line spacing)
 
 	// Images on the left or the right side.
 	vector<SGenerateTextImage> Images[2];
 	int pos_last_img=-1;	// Position in the string where last img (either left or right) were encountered.
 							//  in order to avoid duplicate processing.
 
 	// Easier to read.
 	bool WordWrapping = (Width != 0);
 
 	// Go through string word by word
 	for (int i=0; i<(int)string.m_Words.size()-1 && !done; ++i)
 	{
 		// Pre-process each line one time, so we know which floating images
 		//  will be added for that line.
 
 		// Generated stuff is stored in Feedback.
 		CGUIString::SFeedback Feedback;
 
 		// Preliminary line_height, used for word-wrapping with floating images.
 		float prelim_line_height=0.f;
 
 		// Width and height of all text calls generated.
 		string.GenerateTextCall(Feedback, Font,
 								string.m_Words[i], string.m_Words[i+1],
 								FirstLine);
 
 		// Loop through our images queues, to see if images has been added.
 		
 		// Check if this has already been processed.
 		//  Also, floating images are only applicable if Word-Wrapping is on
 		if (WordWrapping && i > pos_last_img)
 		{
 			// Loop left/right
 			for (int j=0; j<2; ++j)
 			{
 				for (vector<CStr>::const_iterator it = Feedback.m_Images[j].begin(); 
 					it != Feedback.m_Images[j].end();
 					++it)
 				{
 					SGUIText::SSpriteCall SpriteCall;
 					SGenerateTextImage Image;
 
 					// Y is if no other floating images is above, y. Else it is placed
 					//  after the last image, like a stack downwards.
 					float _y;
 					if (Images[j].size() > 0)
 						_y = MAX(y, Images[j].back().m_YTo);
 					else
 						_y = y; 
 
 					// Get Size from Icon database
 					SGUIIcon icon = GetIcon(*it);
 
 					CSize size = icon.m_Size;
 					Image.SetupSpriteCall((j==CGUIString::SFeedback::Left), SpriteCall, Width, _y, size, icon.m_SpriteName, BufferZone, icon.m_CellID);
 
 					// Check if image is the lowest thing.
 					Text.m_Size.cy = MAX(Text.m_Size.cy, Image.m_YTo);
 
 					Images[j].push_back(Image);
 					Text.m_SpriteCalls.push_back(SpriteCall);
 				}
 			}
 		}
 
 		pos_last_img = MAX(pos_last_img, i);
 
 		x += Feedback.m_Size.cx;
 		prelim_line_height = MAX(prelim_line_height, Feedback.m_Size.cy);
 
 		// If Width is 0, then there's no word-wrapping, disable NewLine.
 		if ((WordWrapping && (x > Width-BufferZone || Feedback.m_NewLine)) || i == (int)string.m_Words.size()-2)
 		{
 			// Change 'from' to 'i', but first keep a copy of its value.
 			int temp_from = from;
 			from = i;
 
 			static const int From=0, To=1;
 			//int width_from=0, width_to=width;
 			float width_range[2];
 			width_range[From] = BufferZone;
 			width_range[To] = Width - BufferZone;
 
 			// Floating images are only applicable if word-wrapping is enabled.
 			if (WordWrapping)
 			{
 				// Decide width of the line. We need to iterate our floating images.
 				//  this won't be exact because we're assuming the line_height
 				//  will be as our preliminary calculation said. But that may change,
 				//  although we'd have to add a couple of more loops to try straightening
 				//  this problem out, and it is very unlikely to happen noticeably if one
 				//  structures his text in a stylistically pure fashion. Even if not, it
 				//  is still quite unlikely it will happen.
 				// Loop through left and right side, from and to.
 				for (int j=0; j<2; ++j)
 				{
 					for (vector<SGenerateTextImage>::const_iterator it = Images[j].begin(); 
 						it != Images[j].end(); 
 						++it)
 					{
 						// We're working with two intervals here, the image's and the line height's.
 						//  let's find the union of these two.
 						float union_from, union_to;
 
 						union_from = MAX(y, it->m_YFrom);
 						union_to = MIN(y+prelim_line_height, it->m_YTo);
 						
 						// The union is not empty
 						if (union_to > union_from)
 						{
 							if (j == From)
 								width_range[From] = MAX(width_range[From], it->m_Indentation);
 							else
 								width_range[To] = MIN(width_range[To], Width - it->m_Indentation);
 						}
 					}
 				}
 			}
 
 			// Reset X for the next loop
 			x = width_range[From];
 
 			// Now we'll do another loop to figure out the height of
 			//  the line (the height of the largest character). This
 			//  couldn't be determined in the first loop (main loop)
 			//  because it didn't regard images, so we don't know
 			//  if all characters processed, will actually be involved
 			//  in that line.
 			float line_height=0.f;
 			for (int j=temp_from; j<=i; ++j)
 			{
 				// We don't want to use Feedback now, so we'll have to use
 				//  another.
 				CGUIString::SFeedback Feedback2;
 
 				// Don't attach object, it'll suppress the errors
 				//  we want them to be reported in the final GenerateTextCall()
 				//  so that we don't get duplicates.
 				string.GenerateTextCall(Feedback2, Font,
 										string.m_Words[j], string.m_Words[j+1],
 										FirstLine);
 
 				// Append X value.
 				x += Feedback2.m_Size.cx;
 
 				if (WordWrapping && x > width_range[To] && j!=temp_from && !Feedback2.m_NewLine)
 					break;
 
 				// Let line_height be the maximum m_Height we encounter.
 				line_height = MAX(line_height, Feedback2.m_Size.cy);
 
 				if (WordWrapping && Feedback2.m_NewLine)
 					break;
 			}
 
 			// Reset x once more
 			x = width_range[From];
 			// Move down, because font drawing starts from the baseline
 			y += line_height;
 
 			// Do the real processing now
 			for (int j=temp_from; j<=i; ++j)
 			{
 				// We don't want to use Feedback now, so we'll have to use
 				//  another one.
 				CGUIString::SFeedback Feedback2;
 
 				// Defaults
 				string.GenerateTextCall(Feedback2, Font,
 										string.m_Words[j], string.m_Words[j+1], 
 										FirstLine, pObject);
 
 				// Iterate all and set X/Y values
 				// Since X values are not set, we need to make an internal
 				//  iteration with an increment that will append the internal
 				//  x, that is what x_pointer is for.
 				float x_pointer=0.f;
 
 				vector<SGUIText::STextCall>::iterator it;
 				for (it = Feedback2.m_TextCalls.begin(); it != Feedback2.m_TextCalls.end(); ++it)
 				{
 					it->m_Pos = CPos(x + x_pointer, y);
 
 					x_pointer += it->m_Size.cx;
 
 					if (it->m_pSpriteCall)
 					{
 						it->m_pSpriteCall->m_Area += it->m_Pos - CSize(0,it->m_pSpriteCall->m_Area.GetHeight());
 					}
 				}
 
 				// Append X value.
 				x += Feedback2.m_Size.cx;
 
 				Text.m_Size.cx = MAX(Text.m_Size.cx, x+BufferZone);
 
 				// The first word overrides the width limit, what we
 				//  do, in those cases, are just drawing that word even
 				//  though it'll extend the object.
 				if (WordWrapping) // only if word-wrapping is applicable
 				{
 					if (Feedback2.m_NewLine)
 					{
 						from = j+1;
 
 						// Sprite call can exist within only a newline segment,
 						//  therefore we need this.
 						Text.m_SpriteCalls.insert(Text.m_SpriteCalls.end(), Feedback2.m_SpriteCalls.begin(), Feedback2.m_SpriteCalls.end());
 						break;
 					}
 					else
 					if (x > width_range[To] && j==temp_from)
 					{
 						from = j+1;
 						// do not break, since we want it to be added to m_TextCalls
 					}
 					else
 					if (x > width_range[To])
 					{
 						from = j;
 						break;
 					}
 				}
 
 				// Add the whole Feedback2.m_TextCalls to our m_TextCalls.
 				Text.m_TextCalls.insert(Text.m_TextCalls.end(), Feedback2.m_TextCalls.begin(), Feedback2.m_TextCalls.end());
 				Text.m_SpriteCalls.insert(Text.m_SpriteCalls.end(), Feedback2.m_SpriteCalls.begin(), Feedback2.m_SpriteCalls.end());
 
 				if (j == (int)string.m_Words.size()-2)
 					done = true;
 			}
 
 			// Reset X
 			x = 0.f;
 
 			// Update height of all
 			Text.m_Size.cy = MAX(Text.m_Size.cy, y+BufferZone);
 
 			FirstLine = false;
 
 			// Now if we entered as from = i, then we want
 			//  i being one minus that, so that it will become
 			//  the same i in the next loop. The difference is that
 			//  we're on a new line now.
 			i = from-1;
 		}
 	}
 
 	return Text;
 }
 
 void CGUI::DrawText(SGUIText &Text, const CColor &DefaultColor, 
 					const CPos &pos, const float &z, const CRect &clipping)
 {
 	// TODO Gee: All these really necessary? Some
 	//  are defaults and if you changed them
 	//  the opposite value at the end of the functions,
 	//  some things won't be drawn correctly. 
 	glEnable(GL_TEXTURE_2D);
 	glDisable(GL_CULL_FACE);
 
 	glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
 	glEnable(GL_BLEND);
 	glDisable(GL_ALPHA_TEST);
 
 	glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE);
 
 	if (clipping != CRect())
 	{
 		double eq[4][4] = 
 		{ 
 			{  0.0,  1.0, 0.0, -clipping.top },
 			{  1.0,  0.0, 0.0, -clipping.left },
 			{  0.0, -1.0, 0.0, clipping.bottom },
 			{ -1.0,  0.0, 0.0, clipping.right }
 		};
 
 		for (int i=0; i<4; ++i)
 		{
 			glClipPlane(GL_CLIP_PLANE0+i, eq[i]);
 			glEnable(GL_CLIP_PLANE0+i);
 		}
 	}
 
 	CFont* font = NULL;
 	CStr LastFontName;
 
 	for (vector<SGUIText::STextCall>::const_iterator it = Text.m_TextCalls.begin(); 
 		 it != Text.m_TextCalls.end(); 
 		 ++it)
 	{
 		// If this is just a placeholder for a sprite call, continue
 		if (it->m_pSpriteCall)
 			continue;
 
 		// Switch fonts when necessary, but remember the last one used
 		if (it->m_Font != LastFontName)
 		{
 			delete font;
 			font = new CFont(it->m_Font);
 			font->Bind();
 			LastFontName = it->m_Font;
 		}
 
 		CColor color = it->m_UseCustomColor ? it->m_Color : DefaultColor;
 
 		glPushMatrix();
 
 		// TODO Gee: (2004-09-04) Why are font corrupted if inputted float value?
 		glTranslatef((GLfloat)int(pos.x+it->m_Pos.x), (GLfloat)int(pos.y+it->m_Pos.y), z);
 		glColor4fv(color.FloatArray());
 		glwprintf(L"%ls", it->m_String.c_str()); // "%ls" is necessary in case m_String contains % symbols
 
 		glPopMatrix();
 
 	}
 
 	if (font)
 		delete font;
 
 	for (list<SGUIText::SSpriteCall>::iterator it=Text.m_SpriteCalls.begin(); 
 		 it!=Text.m_SpriteCalls.end(); 
 		 ++it)
 	{
 		DrawSprite(it->m_Sprite, it->m_CellID, z, it->m_Area + pos);
 	}
 
 	// TODO To whom it may concern: Thing were not reset, so
 	//  I added this line, modify if incorrect --
 	if (clipping != CRect())
 	{
 		for (int i=0; i<4; ++i)
 			glDisable(GL_CLIP_PLANE0+i);
 	}	
 	glDisable(GL_TEXTURE_2D);
 	// -- GL
 }
 
 bool CGUI::GetPreDefinedColor(const CStr &name, CColor &Output)
 {
 	if (m_PreDefinedColors.count(name) == 0)
 	{
 		return false;
 	}
 	else
 	{
 		Output = m_PreDefinedColors[name];
 		return true;
 	}
 }
 
 void CGUI::ReportParseError(const char *str, ...)
 {
 	va_list argp;
 	char buffer[512];
 	memset(buffer,0,sizeof(buffer));
 	
 	va_start(argp, str);
 	vsnprintf2(buffer, sizeof(buffer), str, argp);
 	va_end(argp);
 
 	// Print header
 	if (m_Errors==0)
 	{
 		LOG(ERROR, LOG_CATEGORY, "*** GUI Tree Creation Errors:");
 	}
 
 	// Important, set ParseError to true
 	++m_Errors;
 
 	LOG(ERROR, LOG_CATEGORY, buffer);
 }
 
 /**
  * @callgraph
  */
 void CGUI::LoadXMLFile(const string &Filename)
 {
 	// Reset parse error
 	//  we can later check if this has increased
 	m_Errors = 0;
 
 	CXeromyces XeroFile;
 	if (XeroFile.Load(Filename.c_str()) != PSRETURN_OK)
 		// Fail silently
 		return;
 
 	XMBElement node = XeroFile.getRoot();
 
 	// Check root element's (node) name so we know what kind of
 	//  data we'll be expecting
 	CStr root_name (XeroFile.getElementString(node.getNodeName()));
 
 	try
 	{
 
 		if (root_name == "objects")
 		{
 			Xeromyces_ReadRootObjects(node, &XeroFile);
 
 			// Re-cache all values so these gets cached too.
 			//UpdateResolution();
 		}
 		else
 		if (root_name == "sprites")
 		{
 			Xeromyces_ReadRootSprites(node, &XeroFile);
 		}
 		else
 		if (root_name == "styles")
 		{
 			Xeromyces_ReadRootStyles(node, &XeroFile);
 		}
 		else
 		if (root_name == "setup")
 		{
 			Xeromyces_ReadRootSetup(node, &XeroFile);
 		}
 		else
 		{
 			debug_warn("CGUI::LoadXMLFile error");
 			// TODO Gee: Output in log
 		}
 	}
 	catch (PSERROR_GUI& e)
 	{
 		LOG(ERROR, LOG_CATEGORY, "Errors loading GUI file %s (%s)", Filename.c_str(), e.getCode());
 		return;
 	}
 
 	// Now report if any other errors occured
 	if (m_Errors > 0)
 	{
 ///		g_console.submit("echo GUI Tree Creation Reports %d errors", m_Errors);
 	}
 
 }
 
 //===================================================================
 //	XML Reading Xeromyces Specific Sub-Routines
 //===================================================================
 
 void CGUI::Xeromyces_ReadRootObjects(XMBElement Element, CXeromyces* pFile)
 {
 	int el_script = pFile->getElementID("script");
 
 	// Iterate main children
 	//  they should all be <object> or <script> elements
 	XMBElementList children = Element.getChildNodes();
 	for (int i=0; i<children.Count; ++i)
 	{
 		//debug_printf("Object %d\n", i);
 		XMBElement child = children.item(i);
 
 		if (child.getNodeName() == el_script)
 			// Execute the inline script
 			Xeromyces_ReadScript(child, pFile);
 		else
 			// Read in this whole object into the GUI
 			Xeromyces_ReadObject(child, pFile, m_BaseObject);
 	}
 }
 
 void CGUI::Xeromyces_ReadRootSprites(XMBElement Element, CXeromyces* pFile)
 {
 	// Iterate main children
 	//  they should all be <sprite> elements
 	XMBElementList children = Element.getChildNodes();
 	for (int i=0; i<children.Count; ++i)
 	{
 		XMBElement child = children.item(i);
 
 		// Read in this whole object into the GUI
 		Xeromyces_ReadSprite(child, pFile);
 	}
 }
 
 void CGUI::Xeromyces_ReadRootStyles(XMBElement Element, CXeromyces* pFile)
 {
 	// Iterate main children
 	//  they should all be <styles> elements
 	XMBElementList children = Element.getChildNodes();
 	for (int i=0; i<children.Count; ++i)
 	{
 		XMBElement child = children.item(i);
 
 		// Read in this whole object into the GUI
 		Xeromyces_ReadStyle(child, pFile);
 	}
 }
 
 void CGUI::Xeromyces_ReadRootSetup(XMBElement Element, CXeromyces* pFile)
 {
 	// Iterate main children
 	//  they should all be <icon>, <scrollbar> or <tooltip>.
 	XMBElementList children = Element.getChildNodes();
 	for (int i=0; i<children.Count; ++i)
 	{
 		XMBElement child = children.item(i);
 
 		// Read in this whole object into the GUI
 
 		CStr name (pFile->getElementString(child.getNodeName()));
 
 		if (name == "scrollbar")
 		{
 			Xeromyces_ReadScrollBarStyle(child, pFile);
 		}
 		else
 		if (name == "icon")
 		{
 			Xeromyces_ReadIcon(child, pFile);
 		}
 		else
 		if (name == "tooltip")
 		{
 			Xeromyces_ReadTooltip(child, pFile);
 		}
 		else
 		if (name == "color")
 		{
 			Xeromyces_ReadColor(child, pFile);
 		}
 		else
 		{
 			debug_warn("Invalid data - DTD shouldn't allow this");
 		}
 	}
 }
 
 void CGUI::Xeromyces_ReadObject(XMBElement Element, CXeromyces* pFile, IGUIObject *pParent)
 {
 	debug_assert(pParent);
 	int i;
 
 	// Our object we are going to create
 	IGUIObject *object = NULL;
 
 	XMBAttributeList attributes = Element.getAttributes();
 
 	// Well first of all we need to determine the type
 	CStr type (attributes.getNamedItem(pFile->getAttributeID("type")));
 
 	// Construct object from specified type
 	//  henceforth, we need to do a rollback before aborting.
 	//  i.e. releasing this object
 	object = ConstructObject(type);
 
 	if (!object)
 	{
 		// Report error that object was unsuccessfully loaded
 		ReportParseError("Unrecognized type \"%s\"", type.c_str());
 		return;
 	}
 
 	// Cache some IDs for element attribute names, to avoid string comparisons
 	#define ELMT(x) int elmt_##x = pFile->getElementID(#x)
 	#define ATTR(x) int attr_##x = pFile->getAttributeID(#x)
 	ELMT(object);
 	ELMT(action);
 	ATTR(style);
 	ATTR(type);
 	ATTR(name);
 	ATTR(hotkey);
 	ATTR(z);
 	ATTR(on);
 	ATTR(file);
 
 	//
 	//	Read Style and set defaults
 	//
 	//	If the setting "style" is set, try loading that setting.
 	//
 	//	Always load default (if it's available) first!
 	//
 	CStr argStyle (attributes.getNamedItem(attr_style));
 
 	if (m_Styles.count("default") == 1)
 		object->LoadStyle(*this, "default");
 
     if (argStyle.Length())
 	{
 		// additional check
 		if (m_Styles.count(argStyle) == 0)
 		{
 			ReportParseError("Trying to use style '%s' that doesn't exist.", argStyle.c_str());
 		}
 		else object->LoadStyle(*this, argStyle);
 	}
 	
 
 	//
 	//	Read Attributes
 	//
 
 	bool NameSet = false;
 	bool ManuallySetZ = false; // if z has been manually set, this turn true
 
 	CStr hotkeyTag;
 
 	// Now we can iterate all attributes and store
 	for (i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 
 		// If value is "null", then it is equivalent as never being entered
 		if ((CStr)attr.Value == "null")
 			continue;
 
 		// Ignore "type" and "style", we've already checked it
 		if (attr.Name == attr_type || attr.Name == attr_style)
 			continue;
 
 		// Also the name needs some special attention
 		if (attr.Name == attr_name)
 		{
 			object->SetName((CStr)attr.Value);
 			NameSet = true;
 			continue;
 		}
 
 		// Wire up the hotkey tag, if it has one
 		if (attr.Name == attr_hotkey)
 			hotkeyTag = attr.Value;
 
 		if (attr.Name == attr_z)
 			ManuallySetZ = true;
 
 		// Try setting the value
 		if (object->SetSetting(pFile->getAttributeString(attr.Name), (CStr)attr.Value, true) != PS_OK)
 		{
 			ReportParseError("(object: %s) Can't set \"%s\" to \"%s\"", object->GetPresentableName().c_str(), pFile->getAttributeString(attr.Name).c_str(), CStr(attr.Value).c_str());
 
 			// This is not a fatal error
 		}
 	}
 
 	// Check if name isn't set, generate an internal name in that case.
 	if (!NameSet)
 	{
 		object->SetName(CStr("__internal(") + CStr(m_InternalNameNumber) + CStr(")"));
 		++m_InternalNameNumber;
 	}
 
 	// Attempt to register the hotkey tag, if one was provided
 	if (hotkeyTag.Length())
 		hotkeyRegisterGUIObject(object->GetName(), hotkeyTag);
 
 	CStrW caption (Element.getText());
 	if (caption.Length())
 	{
 		// Set the setting caption to this
 		object->SetSetting("caption", caption, true);
 
 		// There is no harm if the object didn't have a "caption"
 	}
 
 
 	//
 	//	Read Children
 	//
 
 	// Iterate children
 	XMBElementList children = Element.getChildNodes();
 
 	for (i=0; i<children.Count; ++i)
 	{
 		// Get node
 		XMBElement child = children.item(i);
 
 		// Check what name the elements got
 		int element_name = child.getNodeName();
 
 		if (element_name == elmt_object)
 		{
 			// Call this function on the child
 			Xeromyces_ReadObject(child, pFile, object);
 		}
 		else if (element_name == elmt_action)
 		{
 			// Scripted <action> element
 
 			// Check for a 'file' parameter
 			CStr file (child.getAttributes().getNamedItem(attr_file));
 
 			CStr code;
 
 			// If there is a file, open it and use it as the code
 			if (file.Length())
 			{
 				CVFSFile scriptfile;
 				if (scriptfile.Load(file) != PSRETURN_OK)
 				{
 					LOG(ERROR, LOG_CATEGORY, "Error opening action file '%s'", file.c_str());
 					throw PSERROR_GUI_JSOpenFailed();
 				}
 
 				code = scriptfile.GetAsString();
 			}
 
 			// Read the inline code (concatenating to the file code, if both are specified)
 			code += (CStr)child.getText();
 
 			CStr action = (CStr)child.getAttributes().getNamedItem(attr_on);
 			object->RegisterScriptHandler(action.LowerCase(), code, this);
 		}
 		else
 		{
 			// Try making the object read the tag.
 			if (!object->HandleAdditionalChildren(child, pFile))
 			{
 				LOG(ERROR, LOG_CATEGORY, "(object: %s) Reading unknown children for its type");
 			}
 		}
 	} 
 
 	//
 	//	Check if Z wasn't manually set
 	//
 	if (!ManuallySetZ)
 	{
 		// Set it automatically to 10 plus its parents
 		if (pParent==NULL)
 		{
 			debug_warn("CGUI::Xeromyces_ReadObject error");
 			// TODO Gee: Report error
 		}
 		else
 		{
 			bool absolute;
 			GUI<bool>::GetSetting(object, "absolute", absolute);
 
 			// If the object is absolute, we'll have to get the parent's Z buffered,
 			//  and add to that!
 			if (absolute)
 			{
 				GUI<float>::SetSetting(object, "z", pParent->GetBufferedZ() + 10.f, true);
 			}
 			else
 			// If the object is relative, then we'll just store Z as "10"
 			{
 				GUI<float>::SetSetting(object, "z", 10.f, true);
 			}
 		}
 	}
 
 
 	//
 	//	Input Child
 	//
 
 	try
 	{
 		if (pParent == m_BaseObject)
 			AddObject(object);
 		else
 			pParent->AddChild(object);
 	}
 	catch (PS_RESULT e)
 	{ 
 		ReportParseError(e);
 	}
 }
 
 void CGUI::Xeromyces_ReadScript(XMBElement Element, CXeromyces* pFile)
 {
 
 	// Check for a 'file' parameter
 	CStr file (Element.getAttributes().getNamedItem( pFile->getAttributeID("file") ));
 
 	// If there is a file specified, open and execute it
 	if (file.Length())
 		g_ScriptingHost.RunScript(file, m_ScriptObject);
 
 	// Execute inline scripts
 	CStr code (Element.getText());
 	if (code.Length())
 		g_ScriptingHost.RunMemScript(code.c_str(), code.Length(), "Some XML file", Element.getLineNumber(), m_ScriptObject);
 }
 
 void CGUI::Xeromyces_ReadSprite(XMBElement Element, CXeromyces* pFile)
 {
 	// Sprite object we're adding
 	CGUISprite sprite;
 	
 	// and what will be its reference name
 	CStr name;
 
 	//
 	//	Read Attributes
 	//
 
 	// Get name, we know it exists because of DTD requirements
 	name = Element.getAttributes().getNamedItem( pFile->getAttributeID("name") );
 
 	if (m_Sprites.find(name) != m_Sprites.end())
 		LOG(WARNING, LOG_CATEGORY, "Sprite name '%s' used more than once; first definition will be discarded", (const char*)name);
 
 	//
 	//	Read Children (the images)
 	//
 
 	SGUIImageEffects* effects = NULL;
 
 	// Iterate children
 	XMBElementList children = Element.getChildNodes();
 
 	for (int i=0; i<children.Count; ++i)
 	{
 		// Get node
 		XMBElement child = children.item(i);
 
 		CStr ElementName (pFile->getElementString(child.getNodeName()));
 
 		if (ElementName == "image")
 		{
 			Xeromyces_ReadImage(child, pFile, sprite);
 		}
 		else if (ElementName == "effect")
 		{
 			debug_assert(! effects); // DTD should only allow one effect per sprite
 			effects = new SGUIImageEffects;
 			Xeromyces_ReadEffects(child, pFile, *effects);
 		}
 		else
 		{
 			debug_warn("Invalid data - DTD shouldn't allow this");
 		}
 	}
 
 	// Apply the effects to every image (unless the image overrides it with
 	// different effects)
 	if (effects)
 		for (std::vector<SGUIImage>::iterator it = sprite.m_Images.begin(); it != sprite.m_Images.end(); ++it)
 			if (! it->m_Effects)
 				it->m_Effects = new SGUIImageEffects(*effects); // do a copy just so it can be deleted correctly later
 
 	delete effects;
 
 	//
 	//	Add Sprite
 	//
 
 	m_Sprites[name] = sprite;
 }
 
 void CGUI::Xeromyces_ReadImage(XMBElement Element, CXeromyces* pFile, CGUISprite &parent)
 {
 
 	// Image object we're adding
 	SGUIImage image;
 	
 	// Set defaults (or maybe do that in DTD?)
 	image.m_TextureSize = CClientArea("0 0 100% 100%");
 	image.m_Size = CClientArea("0 0 100% 100%");
 	
 	// TODO Gee: Setup defaults here (or maybe they are in the SGUIImage ctor)
 
 	//
 	//	Read Attributes
 	//
 
 	// Now we can iterate all attributes and store
 	XMBAttributeList attributes = Element.getAttributes();
 	for (int i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 		CStr attr_name (pFile->getAttributeString(attr.Name));
 		CStr attr_value (attr.Value);
 
 		if (attr_name == "texture")
 		{
 			CStr TexFilename ("art/textures/ui/");
 			TexFilename += attr_value;
 
 			image.m_TextureName = TexFilename;
 		}
 		else
 		if (attr_name == "size")
 		{
 			CClientArea ca;
 			if (!GUI<CClientArea>::ParseString(attr_value, ca))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_Size = ca;
 		}
 		else
 		if (attr_name == "texture_size")
 		{
 			CClientArea ca;
 			if (!GUI<CClientArea>::ParseString(attr_value, ca))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_TextureSize = ca;
 		}
 		else
 		if (attr_name == "real_texture_placement")
 		{
 			CRect rect;
 			if (!GUI<CRect>::ParseString(attr_value, rect))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_TexturePlacementInFile = rect;
 		}
 		else
 		if (attr_name == "cell_size")
 		{
 			CSize size;
 			if (!GUI<CSize>::ParseString(attr_value, size))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_CellSize = size;
 		}
 		else
 		if (attr_name == "z_level")
 		{
 			float z_level;
 			if (!GUI<float>::ParseString(attr_value, z_level))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_DeltaZ = z_level/100.f;
 		}
 		else
 		if (attr_name == "backcolor")
 		{
 			CColor color;
 			if (!GUI<CColor>::ParseString(attr_value, color))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_BackColor = color;
 		}
 		else
 		if (attr_name == "bordercolor")
 		{
 			CColor color;
 			if (!GUI<CColor>::ParseString(attr_value, color))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_BorderColor = color;
 		}
 		else
 		if (attr_name == "border")
 		{
 			bool b;
 			if (!GUI<bool>::ParseString(attr_value, b))
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			else image.m_Border = b;
 		}
 		else
 		{
 			debug_warn("Invalid data - DTD shouldn't allow this");
 		}
 	}
 
 	// Look for effects
 	XMBElementList children = Element.getChildNodes();
 	for (int i=0; i<children.Count; ++i)
 	{
 		XMBElement child = children.item(i);
 		CStr ElementName (pFile->getElementString(child.getNodeName()));
 		if (ElementName == "effect")
 		{
 			debug_assert(! image.m_Effects); // DTD should only allow one effect per sprite
 			image.m_Effects = new SGUIImageEffects;
 			Xeromyces_ReadEffects(child, pFile, *image.m_Effects);
 		}
 		else
 		{
 			debug_warn("Invalid data - DTD shouldn't allow this");
 		}
 	}
 
 	//
 	//	Input
 	//
 
 	parent.AddImage(image);	
 }
 
 void CGUI::Xeromyces_ReadEffects(XMBElement Element, CXeromyces* pFile, SGUIImageEffects &effects)
 {
 	XMBAttributeList attributes = Element.getAttributes();
 	for (int i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 		CStr attr_name (pFile->getAttributeString(attr.Name));
 		CStr attr_value (attr.Value);
 
 #define COLOR(xml, mem, alpha) \
 		if (attr_name == xml) \
 		{ \
 			CColor color; \
 			if (!GUI<int>::ParseColor(attr_value, color, alpha)) \
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str()); \
 			else effects.m_##mem = color; \
 		} \
 		else
 
 
 #define BOOL(xml, mem) \
 		if (attr_name == xml) \
 		{ \
 			effects.m_##mem = true; \
 		} \
 		else
 
 		COLOR("add_color", AddColor, 0.f)
 		COLOR("multiply_color", MultiplyColor, 255.f)
 		BOOL("grayscale", Greyscale)
 
 		{
 			debug_warn("Invalid data - DTD shouldn't allow this");
 		}
 	}
 }
 
 void CGUI::Xeromyces_ReadStyle(XMBElement Element, CXeromyces* pFile)
 {
 	// style object we're adding
 	SGUIStyle style;
 	CStr name;
 	
 	//
 	//	Read Attributes
 	//
 
 	// Now we can iterate all attributes and store
 	XMBAttributeList attributes = Element.getAttributes();
 	for (int i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 		CStr attr_name (pFile->getAttributeString(attr.Name));
 		CStr attr_value (attr.Value);
 
 		// The "name" setting is actually the name of the style
 		//  and not a new default
 		if (attr_name == "name")
 			name = attr_value;
 		else
 			style.m_SettingsDefaults[attr_name] = attr_value;
 	}
 
 	//
 	//	Add to CGUI
 	//
 
 	m_Styles[name] = style;
 }
 
 void CGUI::Xeromyces_ReadScrollBarStyle(XMBElement Element, CXeromyces* pFile)
 {
 	// style object we're adding
 	SGUIScrollBarStyle scrollbar;
 	CStr name;
 	
 	//
 	//	Read Attributes
 	//
 
 	// Now we can iterate all attributes and store
 	XMBAttributeList attributes = Element.getAttributes();
 	for (int i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 		CStr attr_name = pFile->getAttributeString(attr.Name);
 		CStr attr_value (attr.Value);
 
 		if (attr_value == "null")
 			continue;
 
 		if (attr_name == "name")
 			name = attr_value;
 		else
 		if (attr_name == "width")
 		{
 			float f;
 			if (!GUI<float>::ParseString(attr_value, f))
 			{
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			}
 			scrollbar.m_Width = f;
 		}
 		else
 		if (attr_name == "minimum_bar_size")
 		{
 			float f;
 			if (!GUI<float>::ParseString(attr_value, f))
 			{
 				ReportParseError("Error parsing '%s' (\"%s\")", attr_name.c_str(), attr_value.c_str());
 			}
 			scrollbar.m_MinimumBarSize = f;
 		}
 		else
 		if (attr_name == "sprite_button_top")
 			scrollbar.m_SpriteButtonTop = attr_value;
 		else
 		if (attr_name == "sprite_button_top_pressed")
 			scrollbar.m_SpriteButtonTopPressed = attr_value;
 		else
 		if (attr_name == "sprite_button_top_disabled")
 			scrollbar.m_SpriteButtonTopDisabled = attr_value;
 		else
 		if (attr_name == "sprite_button_top_over")
 			scrollbar.m_SpriteButtonTopOver = attr_value;
 		else
 		if (attr_name == "sprite_button_bottom")
 			scrollbar.m_SpriteButtonBottom = attr_value;
 		else
 		if (attr_name == "sprite_button_bottom_pressed")
 			scrollbar.m_SpriteButtonBottomPressed = attr_value;
 		else
 		if (attr_name == "sprite_button_bottom_disabled")
 			scrollbar.m_SpriteButtonBottomDisabled = attr_value;
 		else
 		if (attr_name == "sprite_button_bottom_over")
 			scrollbar.m_SpriteButtonBottomOver = attr_value;
 		else
 		if (attr_name == "sprite_back_vertical")
 			scrollbar.m_SpriteBackVertical = attr_value;
 		else
 		if (attr_name == "sprite_bar_vertical")
 			scrollbar.m_SpriteBarVertical = attr_value;
 		else
 		if (attr_name == "sprite_bar_vertical_over")
 			scrollbar.m_SpriteBarVerticalOver = attr_value;
 		else
 		if (attr_name == "sprite_bar_vertical_pressed")
 			scrollbar.m_SpriteBarVerticalPressed = attr_value;
 	}
 
 	//
 	//	Add to CGUI 
 	//
 
 	m_ScrollBarStyles[name] = scrollbar;
 }
 
 void CGUI::Xeromyces_ReadIcon(XMBElement Element, CXeromyces* pFile)
 {
 	// Icon we're adding
 	SGUIIcon icon;
 	CStr name;
 
 	XMBAttributeList attributes = Element.getAttributes();
 	for (int i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 		CStr attr_name (pFile->getAttributeString(attr.Name));
 		CStr attr_value (attr.Value);
 
 		if (attr_value == "null")
 			continue;
 
 		if (attr_name == "name")
 			name = attr_value;
 		else
 		if (attr_name == "sprite")
 			icon.m_SpriteName = attr_value;
 		else
 		if (attr_name == "size")
 		{
 			CSize size;
 			if (!GUI<CSize>::ParseString(attr_value, size))
 				ReportParseError("Error parsing '%s' (\"%s\") inside <icon>.", attr_name.c_str(), attr_value.c_str());
 			icon.m_Size = size;
 		}
 		else
 		if (attr_name == "cell_id")
 		{
 			int cell_id;
 			if (!GUI<int>::ParseString(attr_value, cell_id))
 				ReportParseError("Error parsing '%s' (\"%s\") inside <icon>.", attr_name.c_str(), attr_value.c_str());
 			icon.m_CellID = cell_id;
 		}
 		else
 		{
 			debug_warn("Invalid data - DTD shouldn't allow this");
 		}
 	}
 
 	m_Icons[name] = icon;
 }
 
 void CGUI::Xeromyces_ReadTooltip(XMBElement Element, CXeromyces* pFile)
 {
 	// Read the tooltip, and store it as a specially-named object
 
 	IGUIObject* object = new CTooltip;
 
 	XMBAttributeList attributes = Element.getAttributes();
 	for (int i=0; i<attributes.Count; ++i)
 	{
 		XMBAttribute attr = attributes.item(i);
 		CStr attr_name (pFile->getAttributeString(attr.Name));
 		CStr attr_value (attr.Value);
 
 		if (attr_name == "name")
 		{
 			object->SetName("__tooltip_" + attr_value);
 		}
 		else
 		{
 			object->SetSetting(attr_name, attr_value);
 		}
 	}
 
 	AddObject(object);
 }
 
 // Reads Custom Color
 void CGUI::Xeromyces_ReadColor(XMBElement Element, CXeromyces* pFile)
 {
 	// Read the color and stor in m_PreDefinedColors
 
 	XMBAttributeList attributes = Element.getAttributes();
 
 	//IGUIObject* object = new CTooltip;
 	CColor color;
 	CStr name = attributes.getNamedItem(pFile->getAttributeID("name"));
 
 	// Try parsing value 
 	CStr value (Element.getText());
 	if (value.Length())
 	{
 		// Try setting color to value
 		if (!color.ParseString(value, 255.f))
 		{
 			ReportParseError("Unable to create custom color '%s'. Invalid color syntax.", name.c_str());
 		}
 		else
 		{
 			// input color
 			m_PreDefinedColors[name] = color;
 		}
 	}
 }
Index: ps/trunk/source/lib/res/file/compression.cpp
===================================================================
--- ps/trunk/source/lib/res/file/compression.cpp	(revision 3585)
+++ ps/trunk/source/lib/res/file/compression.cpp	(revision 3586)
@@ -1,489 +1,499 @@
 // Compression/Decompression interface
 // Copyright (c) 2005 Jan Wassenberg
 //
 // This program is free software; you can redistribute it and/or
 // modify it under the terms of the GNU General Public License as
 // published by the Free Software Foundation; either version 2 of the
 // License, or (at your option) any later version.
 //
 // This program is distributed in the hope that it will be useful, but
 // WITHOUT ANY WARRANTY; without even the implied warranty of
 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 // General Public License for more details.
 //
 // Contact info:
 //   Jan.Wassenberg@stud.uni-karlsruhe.de
 //   http://www.stud.uni-karlsruhe.de/~urkt/
 
 #include "precompiled.h"
 
 #include <deque>
 
 #include "lib/res/mem.h"
 #include "lib/allocators.h"
 #include "lib/timer.h"
 #include "compression.h"
 
 // provision for removing all ZLib code (all inflate calls will fail).
 // used for checking DLL dependency; might also simulate corrupt Zip files.
 //#define NO_ZLIB
 
 #ifndef NO_ZLIB
 # define ZLIB_DLL
 # include <zlib.h>
 
 # if MSC_VERSION
 #  ifdef NDEBUG
 #   pragma comment(lib, "zlib1.lib")
 #  else
 #   pragma comment(lib, "zlib1d.lib")
 #  endif
 # endif
 #endif
 
 TIMER_ADD_CLIENT(tc_zip_inflate);
 TIMER_ADD_CLIENT(tc_zip_memcpy);
 
 
 /*
 what is value added of zlib layer?
 it gets the zlib interface cororrect - e.g. checking for return vals.
 code can then just use our more simple interfacde
 
 inf_*: in-memory inflate routines (zlib wrapper)
 decompresses blocks from file_io callback.
 */
 
 static LibError LibError_from_zlib(int err)
 {
 	switch(err)
 	{
 	case Z_OK:
 		return ERR_OK;
 	case Z_STREAM_END:
 		return ERR_EOF;
 	case Z_MEM_ERROR:
 		return ERR_NO_MEM;
 	case Z_DATA_ERROR:
 		return ERR_CORRUPTED;
 	case Z_STREAM_ERROR:
 		return ERR_INVALID_PARAM;
 	default:
 		return ERR_FAIL;
 	}
 	UNREACHABLE;
 }
 
 
 
 // must be dynamically allocated - need one for every open AFile,
 // and z_stream is large.
 class Compressor
 {
 public:
 	Compressor(ContextType type_)
 	{
 		type = type_;
 	}
 
 	virtual ~Compressor()
 	{
 		mem_free(out_mem);
 
 		// free all remaining input buffers that we copied (rare)
 		for(size_t i = 0; i < pending_bufs.size(); i++)
 			free(pending_bufs[i].mem_to_free);
 	}
 
 
 	virtual LibError init() = 0;
 
 	virtual LibError reset()
 	{
 		next_out = 0;
 		avail_out = 0;
 		return ERR_OK;
 	}
 
 	virtual LibError alloc_output(size_t in_size) = 0;
 
 	// consume as much of the given input buffer as possible. the data is
 	// decompressed/compressed into the previously established output buffer.
 	// reports how many bytes were consumed and produced; either or both
 	// can be 0 if input size is small or not enough room in output buffer.
 	// caller is responsible for saving any leftover input data,
 	// which is why we pass back in_consumed.
 	virtual LibError consume(const void* in, size_t in_size, size_t& in_consumed, size_t& out_produced) = 0;
 
 	virtual LibError finish(void** out, size_t* out_size) = 0;
 
 	virtual void release() = 0;
 
 
 	void set_output(void* out, size_t out_size)
 	{
 		// must only be set once, because finish() returns the
 		// output buffer set as: next_out - total_out.
 		debug_assert(next_out == 0 && avail_out == 0);
 		next_out = out;
 		avail_out = out_size;
 	}
 	void* get_output()
 	{
 		debug_assert(next_out != 0);
 		return next_out;
 	}
 	ssize_t feed(const void* in, size_t in_size)
 	{
 		size_t out_total = 0;	// returned unless error occurs
 		LibError err;
 
 		// note: calling with in_size = 0 is allowed and just means
 		// we don't queue a new buffer. this can happen when compressing
 		// newly decompressed data if nothing was output (due to
 		// small compressed input buffer).
 		if(in_size != 0)
 			pending_bufs.push_back(Buf(in, in_size, 0));
 
 		// work off all queued input buffers until output buffer is filled.
 		while(!pending_bufs.empty())
 		{
 			Buf& buf = pending_bufs.front();
 
 			size_t in_consumed, out_consumed;
 			err = consume(buf.cdata, buf.csize, in_consumed, out_consumed);
 			if(err < 0)
 				return err;
 
 			out_total += out_consumed;
 			debug_assert(in_consumed <= buf.csize);
 			// all input consumed - dequeue input buffer
 			if(in_consumed == buf.csize)
 			{
 				free(buf.mem_to_free);	// no-op unless we allocated it
 				pending_bufs.pop_front();
 			}
 			// limited by output space - mark input buffer as partially used
 			else
 			{
 				buf.cdata += in_consumed;
 				buf.csize -= in_consumed;
 
 				// buffer was allocated by caller and may be freed behind our
 				// backs after returning (which we must because output buffer
 				// is full). allocate a copy of the remaining input data.
 				if(!buf.mem_to_free)
 				{
 					void* cdata_copy = malloc(buf.csize);
 					if(!cdata_copy)
 						return ERR_NO_MEM;
 					memcpy2(cdata_copy, buf.cdata, buf.csize);
 					buf.cdata = (const u8*)cdata_copy;
 				}
 
 				return (ssize_t)out_total;
 			}
 		}
 
 		return (ssize_t)out_total;
 	}
 
 
 protected:
 	ContextType type;
 	CompressionMethod method;
 
 	// output buffer - assigned once by set_output
 	void* next_out;
 	size_t avail_out;
 
 	// output memory allocated by allow_output_impl
 	void* out_mem;
 	size_t out_mem_size;
 
 	struct Buf
 	{
 		const u8* cdata;
 		size_t csize;
 		void* mem_to_free;
 		Buf(const void* cdata_, size_t csize_, void* mem_to_free_)
 		{
 			cdata = (const u8*)cdata_;
 			csize = csize_;
 			mem_to_free = mem_to_free_;
 		}
 	};
 	// note: a 'list' (deque is more efficient) is necessary.
 	// lack of output space can result in leftover input data;
 	// since we do not want feed() to always have to check for and
 	// use up any previous remnants, we allow queuing them.
 	std::deque<Buf> pending_bufs;
 
 	LibError alloc_output_impl(size_t required_out_size)
 	{
 		size_t alloc_size = required_out_size;
 
 		// .. already had a buffer
 		if(out_mem)
 		{
 			// it was big enough - reuse
 			if(out_mem_size >= required_out_size)
 				goto have_out_mem;
 
 			// free previous
 			// note: mem.cpp doesn't support realloc; don't use Pool etc. because
 			// maximum file size may be huge (more address space than we can afford)
 			mem_free(out_mem);
 
 			// TODO: make sure difference in required_out_size vs. out_mem_size
 			// is big enough - i.e. don't only increment in small chunks.
 			// set alloc_size...
 
 			// fall through..
 		}
 
 		// .. need to allocate anew
 		out_mem = mem_alloc(alloc_size, 32*KiB);
 		if(!out_mem)
 			WARN_RETURN(ERR_NO_MEM);
 		out_mem_size = alloc_size;
 
 have_out_mem:
 		// must only be set once, because finish() returns the
 		// output buffer set as: next_out - total_out.
 		debug_assert(next_out == 0 && avail_out == 0);
 
 		next_out  = out_mem;
 		avail_out = out_mem_size;
 
 		return ERR_OK;
 	}
 
 };	// class Compressor
 
 
 #ifndef NO_ZLIB
 
 class ZLibCompressor : public Compressor
 {
 	z_stream zs;
 
 public:
 	// default ctor cannot be generated
 	ZLibCompressor(ContextType type)
 		: Compressor(type), zs() {}
 
 	virtual LibError init()
 	{
 		memset(&zs, 0, sizeof(zs));
 
 		int ret;
 		if(type == CT_COMPRESSION)
 		{
+			// note: with Z_BEST_COMPRESSION, 78% percent of
+			// archive builder CPU time is spent in ZLib, even though
+			// that is interleaved with IO; everything else is negligible.
+			// we therefore enable this only in final builds; during
+			// development, 1.5% bigger archives are definitely worth much
+			// faster build time.
+#ifdef FINAL
 			const int level      = Z_BEST_COMPRESSION;
+#else
+			const int level      = Z_BEST_SPEED;
+#endif
 			const int windowBits = -MAX_WBITS;	// max window size; omit ZLib header
-			const int memLevel   = 8;					// default; total mem ~= 256KiB
+			const int memLevel   = 9;					// max speed; total mem ~= 384KiB
 			const int strategy   = Z_DEFAULT_STRATEGY;	// normal data - not RLE
 			ret = deflateInit2(&zs, level, Z_DEFLATED, windowBits, memLevel, strategy);
 		}
 		else
 		{
 			const int windowBits = -MAX_WBITS;	// max window size; omit ZLib header
 			ret = inflateInit2(&zs, windowBits);
 		}
 		CHECK_ERR(LibError_from_zlib(ret));
 		return ERR_OK;
 	}
 
 	virtual LibError reset()
 	{
 		Compressor::reset();
 		int ret;
 		if(type == CT_COMPRESSION)
 			ret = deflateReset(&zs);
 		else
 			ret = inflateReset(&zs);
 		CHECK_ERR(LibError_from_zlib(ret));
 		return ERR_OK;
 	}
 
 
 	// out:
 	// compression ratios can be enormous (1000x), so we require
 	// callers to allocate the output buffer themselves
 	// (since they know the actual size).
 	// allocate buffer
 	// caller can't do it because they don't know what compression ratio
 	// will be achieved.
 	virtual LibError alloc_output(size_t in_size)
 	{
 		if(type == CT_COMPRESSION)
 		{
 			size_t required_size = (size_t)deflateBound(&zs, (uLong)in_size);
 			RETURN_ERR(alloc_output_impl(required_size));
 			return ERR_OK;
 		}
 		else
 			WARN_RETURN(ERR_LOGIC);
 	}
 
 
 	virtual LibError consume(const void* in, size_t in_size, size_t& in_consumed, size_t& out_consumed)
 	{
 		zs.avail_in = (uInt)in_size;
 		zs.next_in  = (Byte*)in;
 		zs.next_out  = (Byte*)next_out;
 		zs.avail_out = (uInt)avail_out;
 		const size_t prev_avail_in  = zs.avail_in;
 		const size_t prev_avail_out = zs.avail_out;
 
 		int ret;
 		if(type == CT_COMPRESSION)
 			ret = deflate(&zs, 0);
 		else
 			ret = inflate(&zs, Z_SYNC_FLUSH);
 		// sanity check: if ZLib reports end of stream, all input data
 		// must have been consumed.
 		if(ret == Z_STREAM_END)
 		{
 			debug_assert(zs.avail_in == 0);
 			ret = Z_OK;
 		}
 
 		debug_assert(prev_avail_in >= zs.avail_in && prev_avail_out >= avail_out);
 		in_consumed  = prev_avail_in - zs.avail_in;
 		out_consumed = prev_avail_out- zs.avail_out;
 		next_out  = zs.next_out;
 		avail_out = zs.avail_out;
 
 		CHECK_ERR(LibError_from_zlib(ret));
 		return ERR_OK;
 	}
 
 
 	virtual LibError finish(void** out, size_t* out_size)
 	{
 		if(type == CT_COMPRESSION)
 		{
 			// notify zlib that no more data is forthcoming and have it flush output.
 			// our output buffer has enough space due to use of deflateBound;
 			// therefore, deflate must return Z_STREAM_END.
 			int ret = deflate(&zs, Z_FINISH);
 			if(ret != Z_STREAM_END)
 				debug_warn("deflate: unexpected Z_FINISH behavior");
 		}
 		else
 		{
 			// nothing to do - decompression always flushes immediately
 		}
 
 		*out = zs.next_out - zs.total_out;
 		*out_size = zs.total_out;
 		return ERR_OK;
 	}
 
 
 	virtual void release()
 	{
 		// can have both input or output data remaining
 		// (if not all data in uncompressed stream was needed)
 
 		int ret;
 		if(type == CT_COMPRESSION)
 			ret = deflateEnd(&zs);
 		else
 			ret = inflateEnd(&zs);
 		WARN_ERR(LibError_from_zlib(ret));
 	}
 };
 
 #endif	// #ifndef NO_ZLIB
 
 
 //-----------------------------------------------------------------------------
 
 // allocator
 static const size_t MAX_COMPRESSOR_SIZE = sizeof(ZLibCompressor);
 static SingleAllocator<u8[MAX_COMPRESSOR_SIZE]> compressor_allocator;
 
 uintptr_t comp_alloc(ContextType type, CompressionMethod method)
 {
 	void* c_mem = compressor_allocator.alloc();
 	if(!c_mem)
 		return 0;
 	Compressor* c;
 
 #include "nommgr.h"	// protect placement new and free() from macros
 	switch(method)
 	{
 #ifndef NO_ZLIB
 	case CM_DEFLATE:
 		cassert(sizeof(ZLibCompressor) <= MAX_COMPRESSOR_SIZE);
 		c = new(c_mem) ZLibCompressor(type);
 		break;
 #endif
 	default:
 		debug_warn("unknown compression type");
 		compressor_allocator.free(c_mem);
 		return 0;
 #include "mmgr.h"
 	}
 #include "mmgr.h"
 
 	c->init();
 	return (uintptr_t)c;
 }
 
 LibError comp_reset(uintptr_t c_)
 {
 	Compressor* c = (Compressor*)c_;
 	return c->reset();
 }
 
 // subsequent calls to comp_feed will unzip into <out>.
 void comp_set_output(uintptr_t c_, void* out, size_t out_size)
 {
 	Compressor* c = (Compressor*)c_;
 	c->set_output(out, out_size);
 }
 
 LibError comp_alloc_output(uintptr_t c_, size_t in_size)
 {
 	Compressor* c = (Compressor*)c_;
 	return c->alloc_output(in_size);
 }
 
 void* comp_get_output(uintptr_t c_)
 {
 	Compressor* c = (Compressor*)c_;
 	return c->get_output();
 }
 
 // unzip into output buffer. returns bytes written
 // (may be 0, if not enough data is passed in), or < 0 on error.
 ssize_t comp_feed(uintptr_t c_, const void* in, size_t in_size)
 {
 	Compressor* c = (Compressor*)c_;
 	return c->feed(in, in_size);
 }
 
 LibError comp_finish(uintptr_t c_, void** out, size_t* out_size)
 {
 	Compressor* c = (Compressor*)c_;
 	return c->finish(out, out_size);
 }
 
 void comp_free(uintptr_t c_)
 {
 	// no-op if context is 0 (i.e. was never allocated)
 	if(!c_)
 		return;
 
 	Compressor* c = (Compressor*)c_;
 	c->release();
 
 	c->~Compressor();
 #include "nommgr.h"
 	compressor_allocator.free(c);
 #include "mmgr.h"
 }
Index: ps/trunk/source/lib/res/file/file_cache.cpp
===================================================================
--- ps/trunk/source/lib/res/file/file_cache.cpp	(revision 3585)
+++ ps/trunk/source/lib/res/file/file_cache.cpp	(revision 3586)
@@ -1,1149 +1,1268 @@
 #include "precompiled.h"
 
 #include <map>
 
 #include "lib/allocators.h"
 #include "lib/byte_order.h"
 #include "lib/adts.h"
 #include "file_internal.h"
 
 //-----------------------------------------------------------------------------
 
 // block cache: intended to cache raw compressed data, since files aren't aligned
 // in the archive; alignment code would force a read of the whole block,
 // which would be a slowdown unless we keep them in memory.
 //
 // keep out of async code (although extra work for sync: must not issue/wait
 // if was cached) to simplify things. disadvantage: problems if same block
 // is issued twice, before the first call completes (via wait_io).
 // that won't happen though unless we have threaded file_ios =>
 // rare enough not to worry about performance.
 //
 // since sync code allocates the (temp) buffer, it's guaranteed
 // to remain valid.
 //
 
 class BlockMgr
 {
 	static const size_t MAX_BLOCKS = 32;
 	enum BlockStatus
 	{
 		BS_PENDING,
 		BS_COMPLETE,
 		BS_INVALID
 	};
 	struct Block
 	{
 		BlockId id;
 		// initialized in BlockMgr ctor and remains valid
 		void* mem;
 		BlockStatus status;
 		int refs;
 
 		Block()
 			: id(block_cache_make_id(0, 0)), status(BS_INVALID), refs(0) {}
 	};
 	// access pattern is usually ring buffer, but in rare cases we
 	// need to skip over locked items, even though they are the oldest.
 	Block blocks[MAX_BLOCKS];
 	uint oldest_block;
 
 	// use Pool to allocate mem for all blocks because it guarantees
 	// page alignment (required for IO) and obviates manually aligning.
 	Pool pool;
 
 public:
 	BlockMgr()
 		: blocks(), oldest_block(0)
 	{
 		(void)pool_create(&pool, MAX_BLOCKS*FILE_BLOCK_SIZE, FILE_BLOCK_SIZE);
 		for(Block* b = blocks; b < blocks+MAX_BLOCKS; b++)
 		{
 			b->mem = pool_alloc(&pool, 0);
 			debug_assert(b->mem);	// shouldn't ever fail
 		}
 	}
 
 	void shutdown()
 	{
 		(void)pool_destroy(&pool);
 	}
 
 	void* alloc(BlockId id)
 	{
 		Block* b;
 		for(b = blocks; b < blocks+MAX_BLOCKS; b++)
 		{
 			if(block_eq(b->id, id))
 				debug_warn("allocating block that is already in list");
 		}
 
 		for(size_t i = 0; i < MAX_BLOCKS; i++)
 		{
 			b = &blocks[oldest_block];
 			oldest_block = (oldest_block+1)%MAX_BLOCKS;
 
 			// normal case: oldest item can be reused
 			if(b->status != BS_PENDING && b->refs == 0)
 				goto have_block;
 
 			// wacky special case: oldest item is currently locked.
 			// skip it and reuse the next.
 			//
 			// to see when this can happen, consider IO depth = 4.
 			// let the Block at blocks[oldest_block] contain data that
 			// an IO wants. the 2nd and 3rd blocks are not in cache and
 			// happen to be taken from near the end of blocks[].
 			// attempting to issue block #4 fails because its buffer would
 			// want the first slot (which is locked since the its IO
 			// is still pending).
 			if(b->status == BS_COMPLETE && b->refs > 0)
 				continue;
 
 			debug_warn("status and/or refs have unexpected values");
 		}
 
 		debug_warn("all blocks are locked");
 		return 0;
 have_block:
 
 		b->id = id;
 		b->status = BS_PENDING;
 		return b->mem;
 	}
 
 	void mark_completed(BlockId id)
 	{
 		for(Block* b = blocks; b < blocks+MAX_BLOCKS; b++)
 		{
 			if(block_eq(b->id, id))
 			{
 				debug_assert(b->status == BS_PENDING);
 				b->status = BS_COMPLETE;
 				return;
 			}
 		}
 		debug_warn("mark_completed: block not found, but ought still to be in cache");
 	}
 
 	void* find(BlockId id)
 	{
 		// linear search is ok, since we only keep a few blocks.
 		for(Block* b = blocks; b < blocks+MAX_BLOCKS; b++)
 		{
 			if(block_eq(b->id, id))
 			{
 				 if(b->status == BS_COMPLETE)
 				 {
 					 debug_assert(b->refs >= 0);
 					 b->refs++;
 					 return b->mem;
 				 }
 
 				 debug_warn("block referenced while still in progress");
 				 return 0;
 			}
 		}
 		return 0;	// not found
 	}
 
 	void release(BlockId id)
 	{
 		for(Block* b = blocks; b < blocks+MAX_BLOCKS; b++)
 		{
 			if(block_eq(b->id, id))
 			{
 				b->refs--;
 				debug_assert(b->refs >= 0);
 				return;
 			}
 		}
 		debug_warn("release: block not found, but ought still to be in cache");
 	}
 
 	void invalidate(const char* atom_fn)
 	{
 		for(Block* b = blocks; b < blocks+MAX_BLOCKS; b++)
 		{
 			if(b->id.atom_fn == atom_fn)
 			{
 				if(b->refs)
 					debug_warn("invalidating block that is currently in-use");
 				b->status = BS_INVALID;
 			}
 		}
 	}
 };
 static BlockMgr block_mgr;
 
 
 bool block_eq(BlockId b1, BlockId b2)
 {
 	return b1.atom_fn == b2.atom_fn && b1.block_num == b2.block_num;
 }
 
 // create an id for use with the cache that uniquely identifies
 // the block from the file <atom_fn> starting at <ofs>.
 BlockId block_cache_make_id(const char* atom_fn, const off_t ofs)
 {
 	// <atom_fn> is guaranteed to be unique (see file_make_unique_fn_copy).
 	// block_num should always fit in 32 bits (assuming maximum file size
 	// = 2^32 * FILE_BLOCK_SIZE ~= 2^48 -- plenty). we don't bother
 	// checking this.
 	const u32 block_num = (u32)(ofs / FILE_BLOCK_SIZE);
 	BlockId id = { atom_fn, block_num };
 	return id;
 }
 
 void* block_cache_alloc(BlockId id)
 {
 	return block_mgr.alloc(id);
 }
 
 void block_cache_mark_completed(BlockId id)
 {
 	block_mgr.mark_completed(id);
 }
 
 void* block_cache_find(BlockId id)
 {
 	void* ret = block_mgr.find(id);
 	stats_block_cache(ret? CR_HIT : CR_MISS);
 	return ret;
 }
 
 void block_cache_release(BlockId id)
 {
 	return block_mgr.release(id);
 }
 
 
 //-----------------------------------------------------------------------------
 
 // >= AIO_SECTOR_SIZE or else waio will have to realign.
 // chosen as exactly 1 page: this allows write-protecting file buffers
 // without worrying about their (non-page-aligned) borders.
 // internal fragmentation is considerable but acceptable.
 static const size_t BUF_ALIGN = 4*KiB;
 
 /*
 CacheAllocator
 
 the biggest worry of a file cache is fragmentation. there are 2
 basic approaches to combat this:
 1) 'defragment' periodically - move blocks around to increase
    size of available 'holes'.
 2) prevent fragmentation from occurring at all via
    deliberate alloc/free policy.
 
 file_io returns cache blocks directly to the user (zero-copy IO),
 so only currently unreferenced blocks can be moved (while holding a
 lock, to boot). it is believed that this would severely hamper
 defragmentation; we therefore go with the latter approach.
 
 basic insight is: fragmentation occurs when a block is freed whose
 neighbors are not free (thus preventing coalescing). this can be
 prevented by allocating objects of similar lifetimes together.
 typical workloads (uniform access frequency) already show such behavior:
 the Landlord cache manager evicts files in an LRU manner, which matches
 the allocation policy.
 
 references:
 "The Memory Fragmentation Problem - Solved?" (Johnstone and Wilson)
 "Dynamic Storage Allocation - A Survey and Critical Review" (Johnstone and Wilson)
 
 policy:
 - allocation: use all available mem first, then look at freelist
 - freelist: good fit, address-ordered, always split blocks
 - free: immediately coalesce
 mechanism:
 - coalesce: boundary tags in freed memory with magic value
 - freelist: 2**n segregated doubly-linked, address-ordered
 */
 static const size_t MAX_CACHE_SIZE = 96*MiB;
 class CacheAllocator
 {
 public:
 	CacheAllocator()
 		: bitmap(0), freelists()
 	{
 		// (safe to call this from ctor as of 2006-02-02)
 		(void)pool_create(&pool, MAX_CACHE_SIZE, 0);
 	}
 
 	void shutdown()
 	{
 		(void)pool_destroy(&pool);
 	}
 
 	void* alloc(size_t size)
 	{
 		// safely handle 0 byte allocations. according to C/C++ tradition,
 		// we allocate a unique address, which ends up wasting 1 page.
 		if(!size)
 			size = 1;
 
 		const size_t size_pa = round_up(size, BUF_ALIGN);
 		const uint size_class = size_class_of(size_pa);
 		void* p;
 
 		// try to reuse a freed entry
 		p = alloc_from_class(size_class, size_pa);
 		if(p)
 			goto success;
 
 		// grab more space from pool
 		p = pool_alloc(&pool, size_pa);
 		if(p)
 			goto success;
 
 		// last resort: split a larger element
 		p = alloc_from_larger_class(size_class, size_pa);
 		if(p)
 			goto success;
 
 		// failed - can no longer expand and nothing big enough was
 		// found in freelists.
 		// file cache will decide which elements are least valuable,
 		// free() those and call us again.
 		return 0;
 
 success:
 		stats_notify_alloc(size_pa);
 		return p;
 	}
 
-	void make_read_only(u8* p, size_t size)
-	{
-		u8* p_pa = (u8*)round_down((uintptr_t)p, BUF_ALIGN);
-		const size_t size_pa = round_up(size, BUF_ALIGN);
-		(void)mprotect(p_pa, size_pa, PROT_READ);
-	}
-
 	// rationale: don't call this "free" because that would run afoul of the
 	// memory tracker's redirection macro and require #include "nommgr.h".
 	void dealloc(u8* p, size_t size)
 	{
 		const size_t size_pa = round_up(size, BUF_ALIGN);
 		// make sure entire (aligned!) range is within pool.
 		if(!pool_contains(&pool, p) || !pool_contains(&pool, p+size_pa-1))
 		{
 			debug_warn("invalid pointer");
 			return;
 		}
 
 		// (re)allow writes
 		//
 		// note: unfortunately we cannot unmap this buffer's memory
 		// (to make sure it is not used) because we write a header/footer
 		// into it to support coalescing.
 		(void)mprotect(p, size_pa, PROT_READ|PROT_WRITE);
 
 		coalesce_and_free(p, size_pa);
 
 		stats_notify_free(size_pa);
 	}
 
+	// make given range read-only via MMU.
+	// write access is restored when buffer is freed.
+	//
+	// p and size are the user-visible values; we round up/down to
+	// cover the entire allocation (except maybe lots of initial padding).
+	// rationale: this avoids need for consulting exact_buf_oracle,
+	// which is a bit slow.
+	void make_read_only(u8* p, size_t size)
+	{
+		u8* p_pa = (u8*)round_down((uintptr_t)p, BUF_ALIGN);
+		const size_t size_pa = round_up(size, BUF_ALIGN);
+		(void)mprotect(p_pa, size_pa, PROT_READ);
+	}
+
 	// free all allocations and reset state to how it was just after
 	// (the first and only) init() call.
 	void reset()
 	{
 		pool_free_all(&pool);
 		bitmap = 0;
 		memset(freelists, 0, sizeof(freelists));
 		stats_reset();
 	}
 
 private:
 	Pool pool;
 
-	static uint size_class_of(size_t size_pa)
-	{
-		return log2((uint)size_pa);
-	}
-
-	// value of LSB 1-bit
-	static uint ls1(uint x)
-	{
-		return (x & -(int)x);
-	}
-
 	//-------------------------------------------------------------------------
 	// boundary tags for coalescing
 	static const u32 HEADER_ID = FOURCC('C','M','A','H');
 	static const u32 FOOTER_ID = FOURCC('C','M','A','F');
 	static const u32 MAGIC = FOURCC('\xFF','\x55','\xAA','\x01');
 	struct Header
 	{
 		Header* prev;
 		Header* next;
 		size_t size_pa;
 		u32 id;
 		u32 magic;
 	};
 	// we could use struct Header for Footer as well, but keeping them
 	// separate and different can avoid coding errors (e.g. mustn't pass a
 	// Footer to freelist_remove!)
 	struct Footer
 	{
 		// note: deliberately reordered fields for safety
 		u32 magic;
 		u32 id;
 		size_t size_pa;
 	};
 	// must be enough room to stash Header+Footer within the freed allocation.
 	cassert(BUF_ALIGN >= sizeof(Header)+sizeof(Footer));
 
 	// expected_id identifies the tag type (either HEADER_ID or
 	// FOOTER_ID). returns whether the given id, magic and size_pa
 	// values are consistent with such a tag.
 	//
 	// note: these magic values are all that differentiates tags from
 	// user data. this isn't 100% reliable, but we can't insert extra
 	// boundary tags because the memory must remain aligned.
 	bool is_valid_tag(u32 expected_id, u32 id, u32 magic, size_t size_pa) const
 	{
 		if(id != expected_id || magic != MAGIC)
 			return false;
 		TEST(size_pa % BUF_ALIGN == 0);
 		TEST(size_pa <= MAX_CACHE_SIZE);
 		return true;
 	}
 
 	// add p to freelist; if its neighbor(s) are free, merges them all into
 	// one big region and frees that.
 	// notes:
 	// - correctly deals with p lying at start/end of pool.
 	// - p and size_pa are trusted: [p, p+size_pa) lies within the pool.
 	void coalesce_and_free(u8* p, size_t size_pa)
 	{
 		// CAVEAT: Header and Footer are wiped out by freelist_remove -
 		// must use them before that.
 
 		// expand (p, size_pa) to include previous allocation if it's free.
 		// (unless p is at start of pool region)
 		if(p != pool.da.base)
 		{
 			const Footer* footer = (const Footer*)(p-sizeof(Footer));
 			if(is_valid_tag(FOOTER_ID, footer->id, footer->magic, footer->size_pa))
 			{
 				p       -= footer->size_pa;
 				size_pa += footer->size_pa;
 				Header* header = (Header*)p;
 				freelist_remove(header);
 			}
 		}
 
 		// expand size_pa to include following memory if it was allocated
 		// and is currently free.
 		// (unless it starts beyond end of currently committed region)
 		Header* header = (Header*)(p+size_pa);
 		if((u8*)header < pool.da.base+pool.da.cur_size)
 		{
 			if(is_valid_tag(HEADER_ID, header->id, header->magic, header->size_pa))
 			{
 				size_pa += header->size_pa;
 				freelist_remove(header);
 			}
 		}
 
 		freelist_add(p, size_pa);
 	}
 
 	//-------------------------------------------------------------------------
 	// freelist
-	uintptr_t bitmap;
+
+	// segregated, i.e. one list per size class.
 	// note: we store Header nodes instead of just a pointer to head of
 	// list - this wastes a bit of mem but greatly simplifies list insertion.
 	Header freelists[sizeof(uintptr_t)*CHAR_BIT];
 
+	// bit i set iff size class i's freelist is not empty.
+	// in conjunction with ls1, this allows finding a non-empty list in O(1).
+	uintptr_t bitmap;
+
+	// "size class" i (>= 0) contains allocations of size (2**(i-1), 2**i]
+	// except for i=0, which corresponds to size=1.
+	static uint size_class_of(size_t size_pa)
+	{
+		return log2((uint)size_pa);
+	}
+
+	// value of LSB 1-bit.
+	static uint ls1(uint x)
+	{
+		return (x & -(int)x);
+	}
+
 	void freelist_add(u8* p, size_t size_pa)
 	{
 		TEST((uintptr_t)p % BUF_ALIGN == 0);
 		TEST(size_pa % BUF_ALIGN == 0);
 		const uint size_class = size_class_of(size_pa);
 
 		// write header and footer into the freed mem
 		// (its prev and next link fields will be set below)
 		Header* header = (Header*)p;
 		header->id = HEADER_ID;
 		header->magic = MAGIC;
 		header->size_pa = size_pa;
 		Footer* footer = (Footer*)(p+size_pa-sizeof(Footer));
 		footer->id = FOOTER_ID;
 		footer->magic = MAGIC;
 		footer->size_pa = size_pa;
 
 		Header* prev = &freelists[size_class];
 		// find node after which to insert (address ordered freelist)
 		while(prev->next && header <= prev->next)
 			prev = prev->next;
 
 		header->next = prev->next;
 		header->prev = prev;
 		if(prev->next)
 			prev->next->prev = header;
 		prev->next = header;
 
         bitmap |= BIT(size_class);
 	}
 
 	void freelist_remove(Header* header)
 	{
 		TEST((uintptr_t)header % BUF_ALIGN == 0);
 
 		Footer* footer = (Footer*)((u8*)header+header->size_pa-sizeof(Footer));
 		TEST(is_valid_tag(HEADER_ID, header->id, header->magic, header->size_pa));
 		TEST(is_valid_tag(FOOTER_ID, footer->id, footer->magic, footer->size_pa));
 		TEST(header->size_pa == footer->size_pa);
 		const uint size_class = size_class_of(header->size_pa);
 
 		header->prev->next = header->next;
 		if(header->next)
 			header->next->prev = header->prev;
 
 		// if freelist is now empty, clear bit in bitmap.
 		if(!freelists[size_class].next)
 			bitmap &= ~BIT(size_class);
 
 		// wipe out header and footer to prevent accidental reuse
 		memset(header, 0xEE, sizeof(Header));
 		memset(footer, 0xEE, sizeof(Footer));
 	}
 
+	// returns 0 if nothing big enough is in size_class's freelist.
 	void* alloc_from_class(uint size_class, size_t size_pa)
 	{
 		// return first suitable entry in (address-ordered) list
 		for(Header* cur = freelists[size_class].next; cur; cur = cur->next)
 		{
 			if(cur->size_pa >= size_pa)
 			{
 				u8* p = (u8*)cur;
 				const size_t remnant_pa = cur->size_pa - size_pa;
 
 				freelist_remove(cur);
 
 				if(remnant_pa)
 					freelist_add(p+size_pa, remnant_pa);
 
 				return p;
 			}
 		}
 
 		return 0;
 	}
 
+	// returns 0 if there is no big enough entry in any freelist.
 	void* alloc_from_larger_class(uint start_size_class, size_t size_pa)
 	{
 		uint classes_left = bitmap;
 		// .. strip off all smaller classes
 		classes_left &= (~0 << start_size_class);
+
+		// for each non-empty freelist (loop doesn't incur overhead for
+		// empty freelists)
 		while(classes_left)
 		{
 			const uint class_size = ls1(classes_left);
 			classes_left &= ~class_size;	// remove from classes_left
 			const uint size_class = size_class_of(class_size);
+
+			// .. try to alloc
 			void* p = alloc_from_class(size_class, size_pa);
 			if(p)
 				return p;
 		}
 
 		// apparently all classes above start_size_class are empty,
 		// or the above would have succeeded.
 		TEST(bitmap < BIT(start_size_class+1));
 		return 0;
 	}
 
 	//-------------------------------------------------------------------------
 	// stats and validation
 	size_t allocated_size_total_pa, free_size_total_pa;
 
 	void stats_notify_alloc(size_t size_pa) { allocated_size_total_pa += size_pa; }
 	void stats_notify_free(size_t size_pa) { free_size_total_pa += size_pa; }
 	void stats_reset() { allocated_size_total_pa = free_size_total_pa = 0; }
 
 	void self_check() const
 	{
 		debug_assert(allocated_size_total_pa+free_size_total_pa == pool.da.cur_size);
 
 		// make sure freelists contain exactly free_size_total_pa bytes
 		size_t freelist_size_total_pa = 0;
 		uint classes_left = bitmap;
 		while(classes_left)
 		{
 			const uint class_size = ls1(classes_left);
 			classes_left &= ~class_size;	// remove from classes_left
 			const uint size_class = size_class_of(class_size);
 			for(const Header* p = &freelists[size_class]; p; p = p->next)
 				freelist_size_total_pa += p->size_pa;
 		}
 		debug_assert(free_size_total_pa == freelist_size_total_pa);
 	}
 };	// CacheAllocator
 
 static CacheAllocator cache_allocator;
 
 //-----------------------------------------------------------------------------
 
-// list of FileIOBufs currently held by the application.
+/*
+list of FileIOBufs currently held by the application.
+
+note: "currently held" means between a file_buf_alloc/file_buf_retrieve
+and file_buf_free.
+additionally, the buffer may be stored in file_cache if file_cache_add
+was called; it remains there until evicted in favor of another buffer.
+
+rationale: users are strongly encouraged to access buffers as follows:
+"alloc, use, free; alloc next..". this means only a few (typically one) are
+active at a time. a list of these is more efficient to go through (O(1))
+than having to scan file_cache for the buffer (O(N)).
+
+see also discussion at declaration of FileIOBuf.
+*/
 class ExtantBufMgr
 {
-	struct ExtantBuf
-	{
-		FileIOBuf buf;
-		// this would also be available via TFile, but we want users
-		// to be able to allocate file buffers (and they don't know tf).
-		// therefore, we store this separately.
-		size_t size;
-		// which file was this buffer taken from?
-		// we search for given atom_fn as part of file_cache_retrieve
-		// (since we are responsible for already extant bufs).
-		// also useful for tracking down buf 'leaks' (i.e. someone
-		// forgetting to call file_buf_free).
-		const char* atom_fn;
-		//
-		uint refs;
-		// used to check if this buffer was freed immediately
-		// (before allocating the next). that is the desired behavior
-		// because it avoids fragmentation and leaks.
-		uint epoch;
-		ExtantBuf(FileIOBuf buf_, size_t size_, const char* atom_fn_, uint epoch_)
-			: buf(buf_), size(size_), atom_fn(atom_fn_), refs(1), epoch(epoch_) {}
-	};
-	std::vector<ExtantBuf> extant_bufs;
-
 public:
 	ExtantBufMgr()
 		: extant_bufs(), epoch(1) {}
 
-	// return index of ExtantBuf that contains <buf>, or -1.
-	ssize_t find(FileIOBuf buf)
+	// issues a warning if any buffers from the file <atom_fn> are extant.
+	void warn_if_extant(const char* atom_fn)
 	{
-		debug_assert(buf != 0);
 		for(size_t i = 0; i < extant_bufs.size(); i++)
 		{
-			ExtantBuf& eb = extant_bufs[i];
-			if(matches(eb, buf))
-				return (ssize_t)i;
+			if(extant_bufs[i].atom_fn == atom_fn)
+				debug_warn("file has extant buffers but isn't expected to");
 		}
-
-		return -1;
-	}
-
-	// issues a warning if <buf> is not on the extant list or if
-	// size doesn't match that stored in the list.
-	void warn_if_not_extant(FileIOBuf buf, size_t size)
-	{
-		ssize_t idx = find(buf);
-		if(idx == -1)
-			debug_warn("not in extant list");
-		else
-			debug_assert(extant_bufs[idx].size == size);
 	}
 
+	// add given buffer to extant list.
+	// long_lived indicates if this buffer will not be freed immediately
+	// (more precisely, before allocating the next buffer); see the
+	// FILE_LONG_LIVED flag.
+	// note: reuses a previous extant_bufs[] slot if one is unused.
 	void add(FileIOBuf buf, size_t size, const char* atom_fn, bool long_lived)
 	{
 		// cache_allocator also does this; we need to follow suit so that
 		// matches() won't fail due to zero-length size.
 		if(!size)
 			size = 1;
 
 		// don't do was-immediately-freed check for long_lived buffers.
 		const uint this_epoch = long_lived? 0 : epoch++;
 
 		debug_assert(buf != 0);
 		// look for holes in array and reuse those
 		for(size_t i = 0; i < extant_bufs.size(); i++)
 		{
 			ExtantBuf& eb = extant_bufs[i];
 			if(eb.atom_fn == atom_fn)
 				debug_warn("already exists!");
 			// slot currently empty
 			if(!eb.buf)
 			{
 				debug_assert(eb.refs == 0);
 				eb.refs    = 1;
 				eb.buf     = buf;
 				eb.size    = size;
 				eb.atom_fn = atom_fn;
 				eb.epoch   = this_epoch;
 				return;
 			}
 		}
 		// add another entry
 		extant_bufs.push_back(ExtantBuf(buf, size, atom_fn, this_epoch));
 	}
 
+	// indicate that a reference has been taken for <buf>;
+	// parameters are the same as for add().
 	void add_ref(FileIOBuf buf, size_t size, const char* atom_fn, bool long_lived)
 	{
 		ssize_t idx = find(buf);
+		// this buf was already on the extant list
 		if(idx != -1)
 			extant_bufs[idx].refs++;
+		// it was in cache and someone is 'reactivating' it, i.e. moving it
+		// to the extant list.
 		else
 			add(buf, size, atom_fn, long_lived);
 	}
 
+	// return atom_fn that was passed when add()-ing this buf, or 0 if
+	// it's not on extant list.
 	const char* get_owner_filename(FileIOBuf buf)
 	{
 		ssize_t idx = find(buf);
 		if(idx != -1)
 			return extant_bufs[idx].atom_fn;
 		else
 			return 0;
 	}
 
-
-	bool find_and_remove(FileIOBuf buf, FileIOBuf& exact_buf, size_t& size, const char*& atom_fn)
+	// return false and warn if buf is not on extant list; otherwise,
+	// pass back its size/owner filename and decrement reference count.
+	// the return value indicates whether it reached 0, i.e. was
+	// actually removed from the extant list.
+	bool find_and_remove(FileIOBuf buf, size_t& size, const char*& atom_fn)
 	{
 		ssize_t idx = find(buf);
 		if(idx == -1)
 		{
 			debug_warn("buf is not on extant list! double free?");
 			return false;
 		}
 
 		ExtantBuf& eb = extant_bufs[idx];
-		exact_buf = eb.buf;
 		size      = eb.size;
 		atom_fn   = eb.atom_fn;
 
 		if(eb.epoch != 0 && eb.epoch != epoch-1)
 			debug_warn("buf not released immediately");
 		epoch++;
 
 		bool actually_removed = false;
 		// no more references
 		if(--eb.refs == 0)
 		{
 			// mark slot in extant_bufs[] as reusable
 			memset(&eb, 0, sizeof(eb));
 
 			actually_removed = true;
 		}
 
 		return actually_removed;
 	}
 
+	// wipe out the entire list without freeing any FileIOBuf.
+	// only meant to be used in file_cache_reset: since the allocator
+	// is completely reset, there's no need to free outstanding items first.
 	void clear()
 	{
 		extant_bufs.clear();
 	}
 
+	// if buf is not in extant list, complain; otherwise, mark it as
+	// coming from the file <atom_fn>.
+	// this is needed in the following case: uncompressed reads from archive
+	// boil down to a file_io of the archive file. the buffer is therefore
+	// tagged with the archive filename instead of the desired filename.
+	// afile_read sets things right by calling this.
 	void replace_owner(FileIOBuf buf, const char* atom_fn)
 	{
 		ssize_t idx = find(buf);
 		if(idx != -1)
 			extant_bufs[idx].atom_fn = atom_fn;
 		else
 			debug_warn("to-be-replaced buf not found");
 	}
 
+	// display list of all extant buffers in debug outut.
+	// meant to be called at exit, at which time any remaining buffers
+	// must apparently have been leaked.
 	void display_all_remaining()
 	{
 		debug_printf("Leaked FileIOBufs:\n");
 		for(size_t i = 0; i < extant_bufs.size(); i++)
 		{
 			ExtantBuf& eb = extant_bufs[i];
 			if(eb.buf)
 				debug_printf("  %p (0x%08x) %s\n", eb.buf, eb.size, eb.atom_fn);
 		}
 		debug_printf("--------\n");
 	}
 
 private:
-	bool matches(ExtantBuf& eb, FileIOBuf buf)
+	struct ExtantBuf
+	{
+		// treat as user-visible padded buffer, although it may already be
+		// the correct exact_buf.
+		// rationale: file_cache_retrieve gets padded_buf from file_cache
+		// and then calls add_ref. if not already in extant list, that
+		// would be added, whereas file_buf_alloc's add() would specify
+		// the exact_buf. assuming it's padded_buf is safe because
+		// exact_buf_oracle can be used to get exact_buf from that.
+		FileIOBuf buf;
+
+		// treat as user-visible size, although it may already be the
+		// correct exact_size.
+		// rationale: this would also be available via TFile, but we want
+		// users to be able to allocate file buffers (and they don't know tf).
+		// therefore, we store this separately.
+		size_t size;
+
+		// which file was this buffer taken from?
+		// we search for given atom_fn as part of file_cache_retrieve
+		// (since we are responsible for already extant bufs).
+		// also useful for tracking down buf 'leaks' (i.e. someone
+		// forgetting to call file_buf_free).
+		const char* atom_fn;
+
+		// active references, i.e. how many times file_buf_free must be
+		// called until this buffer is freed and removed from extant list.
+		uint refs;
+
+		// used to check if this buffer was freed immediately
+		// (before allocating the next). that is the desired behavior
+		// because it avoids fragmentation and leaks.
+		uint epoch;
+
+		ExtantBuf(FileIOBuf buf_, size_t size_, const char* atom_fn_, uint epoch_)
+			: buf(buf_), size(size_), atom_fn(atom_fn_), refs(1), epoch(epoch_) {}
+	};
+
+	std::vector<ExtantBuf> extant_bufs;
+
+	// see if buf (which may have been adjusted upwards to skip over padding)
+	// falls within eb's buffer.
+	bool matches(const ExtantBuf& eb, FileIOBuf buf) const
 	{
 		return (eb.buf <= buf && buf < (u8*)eb.buf+eb.size);
 	}
 
+	// return index of ExtantBuf that contains <buf>, or -1.
+	ssize_t find(FileIOBuf buf) const
+	{
+		debug_assert(buf != 0);
+		for(size_t i = 0; i < extant_bufs.size(); i++)
+		{
+			const ExtantBuf& eb = extant_bufs[i];
+			if(matches(eb, buf))
+				return (ssize_t)i;
+		}
+
+		return -1;	// not found
+	}
+
 	uint epoch;
 };	// ExtantBufMgr
 static ExtantBufMgr extant_bufs;
 
 //-----------------------------------------------------------------------------
 
 // HACK: key type is really const char*, but the file_cache's STL (hash_)map
 // stupidly assumes that is a "string". (comparison can be done via
 // pointer compare, due to atom_fn mechanism) we define as void* to avoid
 // this behavior - it breaks the (const char*)1 self-test hack and is
 // inefficient.
 static Cache<const void*, FileIOBuf> file_cache;
 
+/*
+mapping of padded_buf to the original exact_buf and exact_size.
+
+rationale: cache stores the user-visible (padded) buffer, but we need
+to pass the original to cache_allocator.
+since not all buffers end up padded (only happens if reading
+uncompressed files from archive), it is more efficient to only
+store bookkeeping information for those who need it (rather than
+maintaining a complete list of allocs in cache_allocator).
+*/
 class ExactBufOracle
 {
 public:
-	void add(FileIOBuf exact_buf, FileIOBuf padded_buf)
+	typedef std::pair<FileIOBuf, size_t> BufAndSize;
+
+	// associate padded_buf with exact_buf and exact_size;
+	// these can later be retrieved via get().
+	// should only be called if necessary, i.e. they are not equal.
+	// assumes and verifies that the association didn't already exist
+	// (otherwise it's a bug, because it's removed when buf is freed)
+	void add(FileIOBuf exact_buf, size_t exact_size, FileIOBuf padded_buf)
 	{
 		debug_assert((uintptr_t)exact_buf % BUF_ALIGN == 0);
 		debug_assert(exact_buf < padded_buf);
 
 		std::pair<Padded2Exact::iterator, bool> ret;
-		ret = padded2exact.insert(std::make_pair(padded_buf, exact_buf));
+		const BufAndSize item = std::make_pair(exact_buf, exact_size);
+		ret = padded2exact.insert(std::make_pair(padded_buf, item));
 		// make sure it wasn't already in the map
 		debug_assert(ret.second == true);
 	}
 
+	// remove association; should be called when freeing <padded_buf>.
 	void remove(FileIOBuf padded_buf)
 	{
 		padded2exact.erase(padded_buf);
 	}
 
-	FileIOBuf get(FileIOBuf padded_buf, bool remove_afterwards = false)
+	// return exact_buf and exact_size that were associated with <padded_buf>.
+	// can optionally remove that association afterwards (slightly more
+	// efficient than a separate remove() call).
+	BufAndSize get(FileIOBuf padded_buf, size_t size, bool remove_afterwards = false)
 	{
 		Padded2Exact::iterator it = padded2exact.find(padded_buf);
 
-		FileIOBuf exact_buf;
+		BufAndSize ret;
+		// not found => must already be exact_buf. will be verified below.
 		if(it == padded2exact.end())
-			exact_buf = padded_buf;
+			ret = std::make_pair(padded_buf, size);
 		else
 		{
-			exact_buf = it->second;
+			ret = it->second;
+
 			if(remove_afterwards)
 				padded2exact.erase(it);
 		}
 
-		debug_assert((uintptr_t)exact_buf % BUF_ALIGN == 0);
-		return exact_buf;
+		// exact_buf must be aligned, or something is wrong.
+		debug_assert((uintptr_t)ret.first  % BUF_ALIGN == 0);
+		return ret;
 	}
 
 private:
-	typedef std::map<FileIOBuf, FileIOBuf> Padded2Exact;
+	typedef std::map<FileIOBuf, BufAndSize> Padded2Exact;
 	Padded2Exact padded2exact;
 };
 static ExactBufOracle exact_buf_oracle;
 
-
+// translate <padded_buf> to the exact buffer and free it.
+// convenience function used by file_buf_alloc and file_buf_free.
 static void free_padded_buf(FileIOBuf padded_buf, size_t size)
 {
-	FileIOBuf exact_buf = exact_buf_oracle.get(padded_buf, true);
-
-	size_t exact_size = size + ((u8*)padded_buf-(u8*)exact_buf);
-	exact_size = round_up(exact_size, BUF_ALIGN);
-
+	const bool remove_afterwards = true;
+	ExactBufOracle::BufAndSize exact = exact_buf_oracle.get(padded_buf, size, remove_afterwards);
+	FileIOBuf exact_buf = exact.first; size_t exact_size = exact.second;
 	cache_allocator.dealloc((u8*)exact_buf, exact_size);
 }
 
 
+// allocate a new buffer of <size> bytes (possibly more due to internal
+// fragmentation). never returns 0.
+// <atom_fn>: owner filename (buffer is intended to be used for data from
+//   this file).
+// <long_lived>: indicates the buffer will not be freed immediately
+//   (i.e. before the next buffer alloc) as it normally should.
+//   this flag serves to suppress a warning and better avoid fragmentation.
+//   caller sets this when FILE_LONG_LIVED is specified.
 FileIOBuf file_buf_alloc(size_t size, const char* atom_fn, bool long_lived)
 {
 	FileIOBuf buf;
 	uint attempts = 0;
 	for(;;)
 	{
 		buf = (FileIOBuf)cache_allocator.alloc(size);
 		if(buf)
 			break;
 
 		// remove least valuable entry from cache and free its buffer.
 		FileIOBuf discarded_buf; size_t size;
 		bool removed = file_cache.remove_least_valuable(&discarded_buf, &size);
 		// only false if cache is empty, which can't be the case because
 		// allocation failed.
 		TEST(removed);
 
 		free_padded_buf(discarded_buf, size);
 
 		// note: this may seem hefty, but 300 is known to be reached.
 		// (after building archive, file cache is full; attempting to
 		// allocate ~4MB while only freeing small blocks scattered over
 		// the entire cache can take a while)
 		if(attempts++ > 500)
 			debug_warn("possible infinite loop: failed to make room in cache");
 	}
 
 	extant_bufs.add(buf, size, atom_fn, long_lived);
 
 	stats_buf_alloc(size, round_up(size, BUF_ALIGN));
 	return buf;
 }
 
 
+// mark <buf> as no longer needed. if its reference count drops to 0,
+// it will be removed from the extant list. if it had been added to the
+// cache, it remains there until evicted in favor of another buffer.
+LibError file_buf_free(FileIOBuf buf)
+{
+	if(!buf)
+		return ERR_OK;
+
+	size_t size; const char* atom_fn;
+	bool actually_removed = extant_bufs.find_and_remove(buf, size, atom_fn);
+	if(actually_removed)
+	{
+		FileIOBuf buf_in_cache;
+		// it's still in cache - leave its buffer intact.
+		if(file_cache.retrieve(atom_fn, buf_in_cache, 0, false))
+		{
+			// sanity checks: what's in cache must match what we have.
+			// note: don't compare actual_size with cached size - they are
+			// usually different.
+			debug_assert(buf_in_cache == buf);
+		}
+		// buf is not in cache - needs to be freed immediately.
+		else
+		{
+			// note: extant_bufs cannot be relied upon to store and return
+			// exact_buf - see definition of ExtantBuf.buf.
+			// we have to use exact_buf_oracle, which is a bit slow, but hey.
+			free_padded_buf(buf, size);
+		}
+	}
+
+	stats_buf_free();
+	trace_notify_free(atom_fn, size);
+
+	return ERR_OK;
+}
+
+
+// interpret file_io parameters (pbuf, size, flags, cb) and allocate a
+// file buffer if necessary.
+// called by file_io and afile_read.
 LibError file_buf_get(FileIOBuf* pbuf, size_t size,
 	const char* atom_fn, uint flags, FileIOCB cb)
 {
 	// decode *pbuf - exactly one of these is true
 	const bool temp  = (pbuf == FILE_BUF_TEMP);
 	const bool alloc = !temp && (*pbuf == FILE_BUF_ALLOC);
 	const bool user  = !temp && !alloc;
 
 	const bool is_write = (flags & FILE_WRITE) != 0;
 	const bool long_lived = (flags & FILE_LONG_LIVED) != 0;
 
 	// reading into temp buffers - ok.
 	if(!is_write && temp && cb != 0)
 		return ERR_OK;
 
 	// reading and want buffer allocated.
 	if(!is_write && alloc)
 	{
 		*pbuf = file_buf_alloc(size, atom_fn, long_lived);
 		if(!*pbuf)	// very unlikely (size totally bogus or cache hosed)
 			WARN_RETURN(ERR_NO_MEM);
 		return ERR_OK;
 	}
 
 	// writing from user-specified buffer - ok
 	if(is_write && user)
 		return ERR_OK;
 
 	WARN_RETURN(ERR_INVALID_PARAM);
 }
 
 
-void file_buf_add_padding(FileIOBuf buf, size_t padding)
-{
-	debug_assert(padding != 0 && padding < FILE_BLOCK_SIZE);
-	FileIOBuf padded_buf = (FileIOBuf)((u8*)buf + padding);
-	exact_buf_oracle.add(buf, padded_buf);
-}
-
 
-LibError file_buf_free(FileIOBuf buf)
+// inform us that the buffer address will be increased by <padding>-bytes.
+// this happens when reading uncompressed files from archive: they
+// start at unaligned offsets and file_io rounds offset down to
+// next block boundary. the buffer therefore starts with padding, which
+// is skipped so the user only sees their data.
+// we make note of the new buffer address so that it can be freed correctly
+// by passing the new padded buffer.
+void file_buf_add_padding(FileIOBuf exact_buf, size_t exact_size, size_t padding)
 {
-	if(!buf)
-		return ERR_OK;
-
-	// note: don't use exact_buf_oracle here - just scanning through
-	// extant list and comparing range is faster + simpler.
-
-	FileIOBuf exact_buf; size_t exact_size; const char* atom_fn;
-	bool actually_removed = extant_bufs.find_and_remove(buf, exact_buf, exact_size, atom_fn);
-	if(actually_removed)
-	{
-		FileIOBuf buf_in_cache;
-		if(file_cache.retrieve(atom_fn, buf_in_cache, 0, false))
-		{
-			// sanity checks: what's in cache must match what we have.
-			// note: don't compare actual_size with cached size - they are
-			// usually different.
-			debug_assert(buf_in_cache == buf);
-		}
-		// buf is not in cache - needs to be freed immediately.
-		else
-		{
-			exact_buf_oracle.remove(buf);
-			cache_allocator.dealloc((u8*)exact_buf, exact_size);
-		}
-	}
-
-	stats_buf_free();
-	trace_notify_free(atom_fn, exact_size);
-
-	return ERR_OK;
+	debug_assert(padding != 0 && padding < FILE_BLOCK_SIZE);
+	FileIOBuf padded_buf = (FileIOBuf)((u8*)exact_buf + padding);
+	exact_buf_oracle.add(exact_buf, exact_size, padded_buf);
 }
 
 
-// mark <buf> as belonging to the file <atom_fn>. this is done after
-// reading uncompressed data from archive: file_io.cpp must allocate the
-// buffer, since only it knows how much padding is needed; however,
-// archive.cpp knows the real filename (as opposed to that of the archive,
-// which is what the file buffer is associated with). therefore,
-// we fix up the filename afterwards.
+// if buf is not in extant list, complain; otherwise, mark it as
+// coming from the file <atom_fn>.
+// this is needed in the following case: uncompressed reads from archive
+// boil down to a file_io of the archive file. the buffer is therefore
+// tagged with the archive filename instead of the desired filename.
+// afile_read sets things right by calling this.
 LibError file_buf_set_real_fn(FileIOBuf buf, const char* atom_fn)
 {
 	// note: removing and reinserting would be easiest, but would
 	// mess up the epoch field.
 	extant_bufs.replace_owner(buf, atom_fn);
 	return ERR_OK;
 }
 
 
+// "give" <buf> to the cache, specifying its size and owner filename.
+// since this data may be shared among users of the cache, it is made
+// read-only (via MMU) to make sure no one can corrupt/change it.
+//
+// note: the reference added by file_buf_alloc still exists! it must
+// still be file_buf_free-d after calling this.
 LibError file_cache_add(FileIOBuf buf, size_t size, const char* atom_fn)
 {
 	debug_assert(buf);
 
 	// decide (based on flags) if buf is to be cached; set cost
 	uint cost = 1;
 
 	cache_allocator.make_read_only((u8*)buf, size);
 	file_cache.add(atom_fn, buf, size, cost);
 
 	return ERR_OK;
 }
 
 
-
-
-
 // called by trace simulator to retrieve buffer address, given atom_fn.
 // must not change any cache state (e.g. notify stats or add ref).
 FileIOBuf file_cache_find(const char* atom_fn, size_t* psize)
 {
 	FileIOBuf buf;
-	if(!file_cache.retrieve(atom_fn, buf, psize, false))
+	bool should_refill_credit = false;
+	if(!file_cache.retrieve(atom_fn, buf, psize, should_refill_credit))
 		return 0;
 	return buf;
 }
 
 
+// check if the contents of the file <atom_fn> are in file cache.
+// if not, return 0; otherwise, return buffer address and optionally
+// pass back its size.
+// <long_lived> indicates whether this file has FILE_LONG_LIVED flag set -
+// see file_buf_alloc docs.
 FileIOBuf file_cache_retrieve(const char* atom_fn, size_t* psize, bool long_lived)
 {
 	// note: do not query extant_bufs - reusing that doesn't make sense
 	// (why would someone issue a second IO for the entire file while
 	// still referencing the previous instance?)
 
 	FileIOBuf buf = file_cache_find(atom_fn, psize);
 	if(buf)
 	{
 		extant_bufs.add_ref(buf, *psize, atom_fn, long_lived);
 		stats_buf_ref();
 	}
 
 	CacheRet cr = buf? CR_HIT : CR_MISS;
 	stats_cache(cr, *psize, atom_fn);
 
 	return buf;
 }
 
 
-/*
-a) FileIOBuf is opaque type with getter
-FileIOBuf buf;	<--------------------- how to initialize??
-file_io(.., &buf);
-data = file_buf_contents(&buf);
-file_buf_free(&buf);
-
-would obviate lookup struct but at expense of additional getter and
-trouble with init - need to set FileIOBuf to wrap user's buffer, or
-only allow us to return buffer address (which is ok)
-
-b) FileIOBuf is pointer to the buf, and secondary map associates that with BufInfo
-FileIOBuf buf;
-file_io(.., &buf);
-file_buf_free(&buf);
-
-secondary map covers all currently open IO buffers. it is accessed upon
-file_buf_free and there are only a few active at a time ( < 10)
-
-*/
-
-
-
-
-
-
-
-
-
-
-// remove all blocks loaded from the file <fn>. used when reloading the file.
+// invalidate all data loaded from the file <fn>. this ensures the next
+// load of this file gets the (presumably new) contents of the file,
+// not previous stale cache contents.
+// call after hotloading code detects file has been changed.
 LibError file_cache_invalidate(const char* P_fn)
 {
 	const char* atom_fn = file_make_unique_fn_copy(P_fn);
 
+	// note: what if the file has an extant buffer?
+	// this *could* conceivably happen during hotloading if a file is
+	// saved right when the engine wants to access it (unlikely but not
+	// impossible).
+	// what we'll do is just let them continue as if nothing had happened;
+	// invalidating is only meant to make sure that the reload's IO
+	// will load the new data (not stale stuff from cache).
+	// => nothing needs to be done.
+
 	// mark all blocks from the file as invalid
 	block_mgr.invalidate(atom_fn);
 
 	// file was cached: remove it and free that memory
 	FileIOBuf cached_buf; size_t size;
 	if(file_cache.retrieve(atom_fn, cached_buf, &size))
 	{
 		file_cache.remove(atom_fn);
-		cache_allocator.dealloc((u8*)cached_buf, size);
+		free_padded_buf(cached_buf, size);
 	}
 
 	return ERR_OK;
 }
 
 
+// reset entire state of the file cache to what it was after initialization.
+// that means completely emptying the extant list and cache.
+// used after simulating cache operation, which fills the cache with
+// invalid data.
 void file_cache_reset()
 {
-	// wipe out extant list and cache. no need to free the bufs -
+	// just wipe out extant list and cache without freeing the bufs -
 	// cache allocator is completely reset below.
 	extant_bufs.clear();
 	FileIOBuf discarded_buf; size_t size;
 	while(file_cache.remove_least_valuable(&discarded_buf, &size)) {}
 
 	cache_allocator.reset();
 }
 
 
 
 void file_cache_init()
 {
 }
 
 
 void file_cache_shutdown()
 {
 	extant_bufs.display_all_remaining();
 	cache_allocator.shutdown();
 	block_mgr.shutdown();
 }
 
 
 //-----------------------------------------------------------------------------
 // built-in self test
 //-----------------------------------------------------------------------------
 
 #if SELF_TEST_ENABLED
 namespace test {
 
 static void test_cache_allocator()
 {
 	// allocated address -> its size
 	typedef std::map<void*, size_t> AllocMap;
 	AllocMap allocations;
 
 	// put allocator through its paces by allocating several times
 	// its capacity (this ensures memory is reused)
 	srand(1);
 	size_t total_size_used = 0;
 	while(total_size_used < 4*MAX_CACHE_SIZE)
 	{
 		size_t size = rand(1, 10*MiB);
 		total_size_used += size;
 		void* p;
 		// until successful alloc:
 		for(;;)
 		{
 			p = cache_allocator.alloc(size);
 			if(p)
 				break;
 			// out of room - remove a previous allocation
 			// .. choose one at random
 			size_t chosen_idx = (size_t)rand(0, (uint)allocations.size());
 			AllocMap::iterator it = allocations.begin();
 			for(; chosen_idx != 0; chosen_idx--)
 				++it;
 			cache_allocator.dealloc((u8*)it->first, it->second);
 			allocations.erase(it);
 		}
 
 		// must not already have been allocated
 		TEST(allocations.find(p) == allocations.end());
 		allocations[p] = size;
 	}
 
 	// reset to virginal state
 	cache_allocator.reset();
 
 }
 
 static void test_file_cache()
 {
 	// we need a unique address for file_cache_add, but don't want to
 	// actually put it in the atom_fn storage (permanently clutters it).
 	// just increment this pointer (evil but works since it's not used).
 //	const char* atom_fn = (const char*)1;
 
 	// give to file_cache
 //	file_cache_add((FileIOBuf)p, size, atom_fn++);
 
 	file_cache_reset();
 	TEST(file_cache.empty());
 
 	// (even though everything has now been freed,
 	// the freelists may be a bit scattered already).
 }
 
 static void self_test()
 {
 	test_cache_allocator();
 	test_file_cache();
 }
 
 SELF_TEST_RUN;
 
 }	// namespace test
 #endif	// #if SELF_TEST_ENABLED
Index: ps/trunk/source/lib/res/file/file_io.cpp
===================================================================
--- ps/trunk/source/lib/res/file/file_io.cpp	(revision 3585)
+++ ps/trunk/source/lib/res/file/file_io.cpp	(revision 3586)
@@ -1,596 +1,596 @@
 #include "precompiled.h"
 
 #include <deque>
 
 #include "lib.h"
 #include "lib/posix.h"
 #include "lib/allocators.h"
 #include "lib/adts.h"
 #include "file_internal.h"
 
 
 //-----------------------------------------------------------------------------
 // async I/O
 //-----------------------------------------------------------------------------
 
 // we don't do any caching or alignment here - this is just a thin AIO wrapper.
 // rationale:
 // - aligning the transfer isn't possible here since we have no control
 //   over the buffer, i.e. we cannot read more data than requested.
 //   instead, this is done in file_io.
 // - transfer sizes here are arbitrary (viz. not block-aligned);
 //   that means the cache would have to handle this or also split them up
 //   into blocks, which is redundant (already done by file_io).
 // - if caching here, we'd also have to handle "forwarding" (i.e.
 //   desired block has been issued but isn't yet complete). again, it
 //   is easier to let the synchronous file_io manager handle this.
 // - finally, file_io knows more about whether the block should be cached
 //   (e.g. whether another block request will follow), but we don't
 //   currently make use of this.
 //
 // disadvantages:
 // - streamed data will always be read from disk. no problem, because
 //   such data (e.g. music, long speech) is unlikely to be used again soon.
 // - prefetching (issuing the next few blocks from archive/file during
 //   idle time to satisfy potential future IOs) requires extra buffers;
 //   this is a bit more complicated than just using the cache as storage.
 
 // FileIO must reference an aiocb, which is used to pass IO params to the OS.
 // unfortunately it is 144 bytes on Linux - too much to put in FileIO,
 // since that is stored in a 'resource control block' (see h_mgr.h).
 // we therefore allocate dynamically, but via suballocator to avoid
 // hitting the heap on every IO.
 class AiocbAllocator
 {
 	Pool pool;
 public:
 	void init()
 	{
 		(void)pool_create(&pool, 32*sizeof(aiocb), sizeof(aiocb));
 	}
 	void shutdown()
 	{
 		(void)pool_destroy(&pool);
 	}
 	aiocb* alloc()
 	{
 		return (aiocb*)pool_alloc(&pool, 0);
 	}
 	// weird name to avoid trouble with mem tracker macros
 	// (renaming is less annoying than #include "nommgr.h")
 	void free_(void* cb)
 	{
 		pool_free(&pool, cb);
 	}
 };
 static AiocbAllocator aiocb_allocator;
 
 
 // starts transferring to/from the given buffer.
 // no attempt is made at aligning or padding the transfer.
 LibError file_io_issue(File* f, off_t ofs, size_t size, void* p, FileIo* io)
 {
 	debug_printf("FILE| issue ofs=%d size=%d\n", ofs, size);
 
 	// zero output param in case we fail below.
 	memset(io, 0, sizeof(FileIo));
 
 	// check params
 	CHECK_FILE(f);
 	if(!size || !p || !io)
 		WARN_RETURN(ERR_INVALID_PARAM);
 	const bool is_write = (f->fc.flags & FILE_WRITE) != 0;
 
 	// note: cutting off at EOF is necessary to avoid transfer errors,
 	// but makes size no longer sector-aligned, which would force
 	// waio to realign (slow). we want to pad back to sector boundaries
 	// afterwards (to avoid realignment), but that is not possible here
 	// since we have no control over the buffer (there might not be
 	// enough room in it). hence, do cut-off in IOManager.
 	//
 	// example: 200-byte file. IOManager issues 16KB chunks; that is way
 	// beyond EOF, so ReadFile fails. limiting size to 200 bytes works,
 	// but causes waio to pad the transfer and use align buffer (slow).
 	// rounding up to 512 bytes avoids realignment and does not fail
 	// (apparently since NTFS files are sector-padded anyway?)
 
 	// (we can't store the whole aiocb directly - glibc's version is
 	// 144 bytes large)
 	aiocb* cb = aiocb_allocator.alloc();
 	io->cb = cb;
 	if(!cb)
 		return ERR_NO_MEM;
 	memset(cb, 0, sizeof(*cb));
 
 	// send off async read/write request
 	cb->aio_lio_opcode = is_write? LIO_WRITE : LIO_READ;
 	cb->aio_buf        = (volatile void*)p;
 	cb->aio_fildes     = f->fd;
 	cb->aio_offset     = ofs;
 	cb->aio_nbytes     = size;
 	debug_printf("FILE| issue2 io=%p nbytes=%u\n", io, cb->aio_nbytes);
 	int err = lio_listio(LIO_NOWAIT, &cb, 1, (struct sigevent*)0);
 	if(err < 0)
 	{
 		debug_printf("lio_listio: %d, %d[%s]\n", err, errno, strerror(errno));
 		(void)file_io_discard(io);
 		WARN_RETURN(LibError_from_errno());
 	}
 
 	return ERR_OK;
 }
 
 
 // indicates if the IO referenced by <io> has completed.
 // return value: 0 if pending, 1 if complete, < 0 on error.
 int file_io_has_completed(FileIo* io)
 {
 	aiocb* cb = (aiocb*)io->cb;
 	int ret = aio_error(cb);
 	if(ret == EINPROGRESS)
 		return 0;
 	if(ret == 0)
 		return 1;
 
 	WARN_RETURN(ERR_FAIL);
 }
 
 
 LibError file_io_wait(FileIo* io, void*& p, size_t& size)
 {
 	debug_printf("FILE| wait io=%p\n", io);
 
 	// zero output params in case something (e.g. H_DEREF) fails.
 	p = 0;
 	size = 0;
 
 	aiocb* cb = (aiocb*)io->cb;
 
 	// wait for transfer to complete.
 	const aiocb** cbs = (const aiocb**)&cb;	// pass in an "array"
 	while(aio_error(cb) == EINPROGRESS)
 		aio_suspend(cbs, 1, (timespec*)0);	// wait indefinitely
 
 	// query number of bytes transferred (-1 if the transfer failed)
 	const ssize_t bytes_transferred = aio_return(cb);
 	debug_printf("FILE| bytes_transferred=%d aio_nbytes=%u\n", bytes_transferred, cb->aio_nbytes);
 
 	// see if actual transfer count matches requested size.
 	// note: most callers clamp to EOF but round back up to sector size
 	// (see explanation in file_io_issue). since we're not sure what
 	// the exact sector size is (only waio knows), we can only warn of
 	// too small transfer counts (not return error).
 	debug_assert(bytes_transferred >= (ssize_t)(cb->aio_nbytes-AIO_SECTOR_SIZE));
 
 	p = (void*)cb->aio_buf;	// cast from volatile void*
 	size = bytes_transferred;
 	return ERR_OK;
 }
 
 
 LibError file_io_discard(FileIo* io)
 {
 	memset(io->cb, 0, sizeof(aiocb));	// prevent further use.
 	aiocb_allocator.free_(io->cb);
 	io->cb = 0;
 	return ERR_OK;
 }
 
 
 LibError file_io_validate(const FileIo* io)
 {
 	const aiocb* cb = (const aiocb*)io->cb;
 	// >= 0x100 is not necessarily bogus, but suspicious.
 	// this also catches negative values.
 	if((uint)cb->aio_fildes >= 0x100)
 		return ERR_1;
 	if(debug_is_pointer_bogus((void*)cb->aio_buf))
 		return ERR_2;
 	if(cb->aio_lio_opcode != LIO_WRITE && cb->aio_lio_opcode != LIO_READ && cb->aio_lio_opcode != LIO_NOP)
 		return ERR_3;
 	// all other aiocb fields have no invariants we could check.
 	return ERR_OK;
 }
 
 
 //-----------------------------------------------------------------------------
 // sync I/O
 //-----------------------------------------------------------------------------
 
 // the underlying aio implementation likes buffer and offset to be
 // sector-aligned; if not, the transfer goes through an align buffer,
 // and requires an extra memcpy2.
 //
 // if the user specifies an unaligned buffer, there's not much we can
 // do - we can't assume the buffer contains padding. therefore,
 // callers should let us allocate the buffer if possible.
 //
 // if ofs misalign = buffer, only the first and last blocks will need
 // to be copied by aio, since we read up to the next block boundary.
 // otherwise, everything will have to be copied; at least we split
 // the read into blocks, so aio's buffer won't have to cover the
 // whole file.
 
 
 // helper routine used by functions that call back to a FileIOCB.
 //
 // bytes_processed is 0 if return value != { ERR_OK, INFO_CB_CONTINUE }
 // note: don't abort if = 0: zip callback may not actually
 // output anything if passed very little data.
 LibError file_io_call_back(const void* block, size_t size,
 	FileIOCB cb, uintptr_t ctx, size_t& bytes_processed)
 {
 	if(cb)
 	{
 		stats_cb_start();
 		LibError ret = cb(ctx, block, size, &bytes_processed);
 		stats_cb_finish();
 
 		// failed - reset byte count in case callback didn't
 		if(ret != ERR_OK && ret != INFO_CB_CONTINUE)
 			bytes_processed = 0;
 
 		CHECK_ERR(ret);
 		return ret;
 	}
 	// no callback to process data: raw = actual
 	else
 	{
 		bytes_processed = size;
 		return INFO_CB_CONTINUE;
 	}
 }
 
 class IOManager
 {
 	File* f;
 	bool is_write;
 	bool no_aio;
 
 	FileIOCB cb;
 	uintptr_t cb_ctx;
 
 	off_t start_ofs;
 	FileIOBuf* pbuf;
 
 	size_t user_size;
 	size_t ofs_misalign;
 	size_t size;
 
 	// (useful, raw data: possibly compressed, but doesn't count padding)
 	size_t total_issued;
 	size_t total_transferred;
 	// if callback, sum of what it reports; otherwise, = total_transferred
 	// this is what we'll return.
 	size_t total_processed;
 
 
 	struct IOSlot
 	{
 		FileIo io;
 
 		const void* cached_block;
 
 
 		BlockId block_id;
 		// needed so that we can add the block to the cache when
 		// its IO is complete. if we add it when issuing, we'd no longer be
 		// thread-safe: someone else might find it in the cache before its
 		// transfer has completed. don't want to add an "is_complete" flag,
 		// because that'd be hard to update (on every wait_io).
 
 
 		void* temp_buf;
 
 		// used by stats_io_start/finish to measure throughput
 		double start_time;
 
 		IOSlot()
 		{
 			reset();
 		}
 		void reset()
 		{
 			memset(&io, 0, sizeof(io));
 			cached_block = 0;
 			memset(&block_id, 0, sizeof(block_id));
 			temp_buf = 0;
 			start_time = 0.0;	// required for stats
 		}
 	};
 	static const uint MAX_PENDING_IOS = 4;
 	//RingBuf<IOSlot, MAX_PENDING_IOS> queue;
 	std::deque<IOSlot> queue;
 
 	// stop issuing and processing as soon as this changes
 	LibError err;
 
 
 	ssize_t lowio()
 	{
 		const int fd = f->fd;
 
 		lseek(fd, start_ofs, SEEK_SET);
 
 		// emulate temp buffers - we take care of allocating and freeing.
 		void* dst;
 		void* dst_mem = 0;
 		if(pbuf == FILE_BUF_TEMP)
 		{
 			dst_mem = malloc(size);
 			if(!dst_mem)
 				return ERR_NO_MEM;
 			dst = dst_mem;
 		}
 		else
 			dst = (void*)*pbuf;
 
 		double start_time = 0.0;	// required for stats
 		FileOp op = is_write? FO_WRITE : FO_READ;
 		BlockId disk_pos = block_cache_make_id(f->fc.atom_fn, start_ofs);
 		stats_io_start(FI_LOWIO, op, size, disk_pos, &start_time);
 		//
 		ssize_t total_transferred;
 		if(is_write)
 			total_transferred = write(fd, dst, size);
 		else
 			total_transferred = read (fd, dst, size);
 		if(total_transferred < 0)
 		{
 			free(dst_mem);
 			WARN_RETURN(LibError_from_errno());
 		}
 		//
 		stats_io_finish(FI_LOWIO, op, &start_time);
 
 		size_t total_processed;
 		LibError ret = file_io_call_back(dst, total_transferred, cb, cb_ctx, total_processed);
 		free(dst_mem);
 		RETURN_ERR(ret);
 		return (ssize_t)total_processed;
 	}
 
 
 	// align and pad the IO to FILE_BLOCK_SIZE
 	// (reduces work for AIO implementation).
 	LibError prepare()
 	{
 		ofs_misalign = 0;
 		size = user_size;
 
 		if(!is_write && !no_aio)
 		{
 			// note: we go to the trouble of aligning the first block (instead of
 			// just reading up to the next block and letting aio realign it),
 			// so that it can be taken from the cache.
 			// this is not possible if we don't allocate the buffer because
 			// extra space must be added for the padding.
 
 			ofs_misalign = start_ofs % FILE_BLOCK_SIZE;
 			start_ofs -= (off_t)ofs_misalign;
 			size = round_up(ofs_misalign + user_size, FILE_BLOCK_SIZE);
 
 			// but cut off at EOF (necessary to prevent IO error).
 			const off_t bytes_left = f->fc.size - start_ofs;
 			if(bytes_left < 0)
 				WARN_RETURN(ERR_EOF);
 			size = MIN(size, (size_t)bytes_left);
 
 			// and round back up to sector size.
 			// see rationale in file_io_issue.
 			size = round_up(size, AIO_SECTOR_SIZE);
 		}
 
 		RETURN_ERR(file_buf_get(pbuf, size, f->fc.atom_fn, f->fc.flags, cb));
 
 		return ERR_OK;
 	}
 
 	void issue(IOSlot& slot)
 	{
 		const off_t ofs = start_ofs+(off_t)total_issued;
 		// for both reads and writes, do not issue beyond end of file/data
 		const size_t issue_size = MIN(FILE_BLOCK_SIZE, size - total_issued);
 // try to grab whole blocks (so we can put them in the cache).
 // any excess data (can only be within first or last) is
 // discarded in wait().
 
 		// check if in cache
 		slot.block_id = block_cache_make_id(f->fc.atom_fn, ofs);
 		slot.cached_block = block_cache_find(slot.block_id);
 		if(!slot.cached_block)
 		{
 			void* buf;
 
 			// if using buffer, set position in it; otherwise, use temp buffer
 			if(pbuf == FILE_BUF_TEMP)
 				buf = slot.temp_buf = block_cache_alloc(slot.block_id);
 			else
 				buf = (char*)*pbuf + total_issued;
 
 			stats_io_start(FI_AIO, is_write? FO_WRITE : FO_READ, issue_size, slot.block_id, &slot.start_time);
 			LibError ret = file_io_issue(f, ofs, issue_size, buf, &slot.io);
 			// transfer failed - loop will now terminate after
 			// waiting for all pending transfers to complete.
 			if(ret != ERR_OK)
 				err = ret;
 		}
 
 		total_issued += issue_size;
 	}
 
 	void wait(IOSlot& slot, void*& block, size_t& block_size)
 	{
 		if(slot.cached_block)
 		{
 			block = (u8*)slot.cached_block;
 			block_size = FILE_BLOCK_SIZE;
 		}
 		// wasn't in cache; it was issued, so wait for it
 		else
 		{
 			LibError ret = file_io_wait(&slot.io, block, block_size);
 			stats_io_finish(FI_AIO, is_write? FO_WRITE : FO_READ, &slot.start_time);
 			if(ret < 0)
 				err = ret;
 		}
 
 		// first time; skip past padding
 		if(total_transferred == 0)
 		{
 			block = (u8*)block + ofs_misalign;
 			block_size -= ofs_misalign;
 		}
 
 		// last time: don't include trailing padding
 		if(total_transferred + block_size > user_size)
 			block_size = user_size - total_transferred;
 
 		// we have useable data from a previous temp buffer,
 		// but it needs to be copied into the user's buffer
 		if(slot.cached_block && pbuf != FILE_BUF_TEMP)
 			memcpy2((char*)*pbuf+ofs_misalign+total_transferred, block, block_size);
 
 		total_transferred += block_size;
 	}
 
 	void process(IOSlot& slot, void* block, size_t block_size, FileIOCB cb, uintptr_t ctx)
 	{
 		if(err == INFO_CB_CONTINUE)
 		{
 			size_t bytes_processed;
 			err = file_io_call_back(block, block_size, cb, ctx, bytes_processed);
 			if(err == INFO_CB_CONTINUE || err == ERR_OK)
 				total_processed += bytes_processed;
 			// else: processing failed.
 			// loop will now terminate after waiting for all
 			// pending transfers to complete.
 		}
 
 		if(slot.cached_block)
 			block_cache_release(slot.block_id);
 		else
 		{
 			file_io_discard(&slot.io);
 			if(pbuf == FILE_BUF_TEMP)
 				block_cache_mark_completed(slot.block_id);
 		}
 	}
 
 
 	ssize_t aio()
 	{
 again:
 		{
 			// data remaining to transfer, and no error:
 			// start transferring next block.
 			if(total_issued < size && err == INFO_CB_CONTINUE && queue.size() < MAX_PENDING_IOS)
 			{
 				queue.push_back(IOSlot());
 				IOSlot& slot = queue.back();
 				issue(slot);
 				goto again;
 			}
 
 			// IO pending: wait for it to complete, and process it.
 			if(!queue.empty())
 			{
 				IOSlot& slot = queue.front();
 				void* block; size_t block_size;
 				wait(slot, block, block_size);
 				process(slot, block, block_size, cb, cb_ctx);
 				queue.pop_front();
 				goto again;
 			}
 		}
 		// (all issued OR error) AND no pending transfers - done.
 
 		debug_assert(total_issued >= total_transferred && total_transferred >= user_size);
 		return (ssize_t)total_processed;
 	}
 
 public:
 	IOManager(File* f_, off_t ofs_, size_t size_, FileIOBuf* pbuf_,
 		FileIOCB cb_, uintptr_t cb_ctx_)
 	{
 		f = f_;
 		is_write = (f->fc.flags & FILE_WRITE ) != 0;
 		no_aio =   (f->fc.flags & FILE_NO_AIO) != 0;
 
 		cb = cb_;
 		cb_ctx = cb_ctx_;
 
 		start_ofs = ofs_;
 		user_size = size_;
 		pbuf = pbuf_;
 
 		total_issued = 0;
 		total_transferred = 0;
 		total_processed = 0;
 		err = INFO_CB_CONTINUE;
 	}
 
 	// now we read the file in 64 KiB chunks, N-buffered.
 	// if reading from Zip, inflate while reading the next block.
 	ssize_t run()
 	{
 		RETURN_ERR(prepare());
 
 		ssize_t ret = no_aio? lowio() : aio();
 ///		FILE_STATS_NOTIFY_IO(fi, is_write? FO_WRITE : FO_READ, user_size, total_issued, start_time);
 
 		debug_printf("FILE| err=%d, total_processed=%u\n", err, total_processed);
 
 		// we allocated the memory: skip any leading padding
 		if(pbuf != FILE_BUF_TEMP && !is_write && ofs_misalign)
 		{
 			FileIOBuf org_buf = *pbuf;
 			*pbuf = (u8*)org_buf + ofs_misalign;
-			file_buf_add_padding(org_buf, ofs_misalign);
+			file_buf_add_padding(org_buf, size, ofs_misalign);
 		}
 
 		if(err != INFO_CB_CONTINUE && err != ERR_OK)
 			return (ssize_t)err;
 		return ret;
 	}
 
 };	// IOManager
 
 
 // transfer <size> bytes, starting at <ofs>, to/from the given file.
 // (read or write access was chosen at file-open time).
 //
 // if non-NULL, <cb> is called for each block transferred, passing <ctx>.
 // it returns how much data was actually transferred, or a negative error
 // code (in which case we abort the transfer and return that value).
 // the callback mechanism is useful for user progress notification or
 // processing data while waiting for the next I/O to complete
 // (quasi-parallel, without the complexity of threads).
 //
 // return number of bytes transferred (see above), or a negative error code.
 ssize_t file_io(File* f, off_t ofs, size_t size, FileIOBuf* pbuf,
 	FileIOCB cb, uintptr_t ctx) // optional
 {
 	debug_printf("FILE| io: size=%u ofs=%u fn=%s\n", size, ofs, f->fc.atom_fn);
 	CHECK_FILE(f);
 
 	// note: do not update stats/trace here: this includes Zip IOs,
 	// which shouldn't be reported.
 
 	IOManager mgr(f, ofs, size, pbuf, cb, ctx);
 	return mgr.run();
 }
 
 
 
 
 void file_io_init()
 {
 	aiocb_allocator.init();
 }
 
 
 void file_io_shutdown()
 {
 	aiocb_allocator.shutdown();
 }
Index: ps/trunk/source/lib/res/file/file_cache.h
===================================================================
--- ps/trunk/source/lib/res/file/file_cache.h	(revision 3585)
+++ ps/trunk/source/lib/res/file/file_cache.h	(revision 3586)
@@ -1,41 +1,93 @@
 
 struct BlockId
 {
 	const char* atom_fn;
 	u32 block_num;
 };
 
 extern bool block_eq(BlockId b1, BlockId b2);
 
 // create an id for use with the cache that uniquely identifies
 // the block from the file <atom_fn> starting at <ofs>.
 extern BlockId block_cache_make_id(const char* atom_fn, const off_t ofs);
 
 extern void* block_cache_alloc(BlockId id);
 
 extern void block_cache_mark_completed(BlockId id);
 
 extern void* block_cache_find(BlockId id);
 extern void block_cache_release(BlockId id);
 
 
 
-
+// allocate a new buffer of <size> bytes (possibly more due to internal
+// fragmentation). never returns 0.
+// <atom_fn>: owner filename (buffer is intended to be used for data from
+//   this file).
+// <long_lived>: indicates the buffer will not be freed immediately
+//   (i.e. before the next buffer alloc) as it normally should.
+//   this flag serves to suppress a warning and better avoid fragmentation.
+//   caller sets this when FILE_LONG_LIVED is specified.
+extern FileIOBuf file_buf_alloc(size_t size, const char* atom_fn, bool long_lived);
+
+// mark <buf> as no longer needed. if its reference count drops to 0,
+// it will be removed from the extant list. if it had been added to the
+// cache, it remains there until evicted in favor of another buffer.
+extern LibError file_buf_free(FileIOBuf buf);
+
+// interpret file_io parameters (pbuf, size, flags, cb) and allocate a
+// file buffer if necessary.
+// called by file_io and afile_read.
 extern LibError file_buf_get(FileIOBuf* pbuf, size_t size,
 	const char* atom_fn, uint flags, FileIOCB cb);
 
-extern void file_buf_add_padding(FileIOBuf buf, size_t padding);
-
+// inform us that the buffer address will be increased by <padding>-bytes.
+// this happens when reading uncompressed files from archive: they
+// start at unaligned offsets and file_io rounds offset down to
+// next block boundary. the buffer therefore starts with padding, which
+// is skipped so the user only sees their data.
+// we make note of the new buffer address so that it can be freed correctly
+// by passing the new padded buffer.
+extern void file_buf_add_padding(FileIOBuf exact_buf, size_t exact_size, size_t padding);
+
+// if buf is not in extant list, complain; otherwise, mark it as
+// coming from the file <atom_fn>.
+// this is needed in the following case: uncompressed reads from archive
+// boil down to a file_io of the archive file. the buffer is therefore
+// tagged with the archive filename instead of the desired filename.
+// afile_read sets things right by calling this.
 extern LibError file_buf_set_real_fn(FileIOBuf buf, const char* atom_fn);
 
-
-extern FileIOBuf file_cache_find(const char* atom_fn, size_t* size);
-extern FileIOBuf file_cache_retrieve(const char* atom_fn, size_t* size, bool long_lived);
+// "give" <buf> to the cache, specifying its size and owner filename.
+// since this data may be shared among users of the cache, it is made
+// read-only (via MMU) to make sure no one can corrupt/change it.
+//
+// note: the reference added by file_buf_alloc still exists! it must
+// still be file_buf_free-d after calling this.
 extern LibError file_cache_add(FileIOBuf buf, size_t size, const char* atom_fn);
 
-extern LibError file_cache_invalidate(const char* fn);
+// called by trace simulator to retrieve buffer address, given atom_fn.
+// must not change any cache state (e.g. notify stats or add ref).
+extern FileIOBuf file_cache_find(const char* atom_fn, size_t* psize);
+
+// check if the contents of the file <atom_fn> are in file cache.
+// if not, return 0; otherwise, return buffer address and optionally
+// pass back its size.
+// <long_lived> indicates whether this file has FILE_LONG_LIVED flag set -
+// see file_buf_alloc docs.
+extern FileIOBuf file_cache_retrieve(const char* atom_fn, size_t* psize, bool long_lived);
+
+// invalidate all data loaded from the file <fn>. this ensures the next
+// load of this file gets the (presumably new) contents of the file,
+// not previous stale cache contents.
+// call after hotloading code detects file has been changed.
+extern LibError file_cache_invalidate(const char* P_fn);
+
+// reset entire state of the file cache to what it was after initialization.
+// that means completely emptying the extant list and cache.
+// used after simulating cache operation, which fills the cache with
+// invalid data.
 extern void file_cache_reset();
 
-
 extern void file_cache_init();
 extern void file_cache_shutdown();
Index: ps/trunk/source/lib/res/file/archive.cpp
===================================================================
--- ps/trunk/source/lib/res/file/archive.cpp	(revision 3585)
+++ ps/trunk/source/lib/res/file/archive.cpp	(revision 3586)
@@ -1,856 +1,857 @@
 #include "precompiled.h"
 
 #include "lib/timer.h"
 #include "lib/allocators.h"
 #include "lib/res/res.h"
 #include "file_internal.h"
 
 
 // components:
 // - za_*: Zip archive handling
 //   passes the list of files in an archive to lookup.
 // - lookup_*: file lookup
 //   per archive: return file info (e.g. offset, size), given filename.
 // - Archive_*: Handle-based container for archive info
 //   owns archive file and its lookup mechanism.
 // - inf_*: in-memory inflate routines (zlib wrapper)
 //   decompresses blocks from file_io callback.
 // - afile_*: file from Zip archive
 //   uses lookup to get file information; holds inflate state.
 // - sync and async I/O
 //   uses file_* and inf_*.
 // - file mapping
 
 ///////////////////////////////////////////////////////////////////////////////
 //
 // lookup_*: file lookup
 // per archive: return file info (e.g. offset, size), given filename.
 //
 ///////////////////////////////////////////////////////////////////////////////
 
 
 // rationale:
 // - we don't export a "key" (currently array index) that would allow faster
 //   file lookup. this would only be useful if higher-level code were to
 //   store the key and use it more than once. also, lookup is currently fast
 //   enough. finally, this would also make our file enumerate callback
 //   incompatible with the others (due to the extra key param).
 //
 // - we don't bother with a directory tree to speed up lookup. the above
 //   is fast enough: O(1) if accessed sequentially, otherwise O(log(files)).
 
 
 ///////////////////////////////////////////////////////////////////////////////
 //
 // Archive_*: Handle-based container for archive info
 // owns archive file and its lookup mechanism.
 //
 ///////////////////////////////////////////////////////////////////////////////
 
 
 struct Archive
 {
 	File f;
 
 	ArchiveEntry* ents;
 	// number of valid entries in above array (see lookup_add_file_cb)
 	uint num_files;
 
 	// note: we need to keep track of what resources reload() allocated,
 	// so the dtor can free everything correctly.
 	uint is_open : 1;
 	uint is_loaded : 1;
 };
 
 H_TYPE_DEFINE(Archive);
 
 
 static void Archive_init(Archive*, va_list)
 {
 }
 
 static void Archive_dtor(Archive* a)
 {
 	if(a->is_loaded)
 	{
 		(void)mem_free(a->ents);
 
 		a->is_loaded = 0;
 	}
 	if(a->is_open)
 	{
 		(void)file_close(&a->f);
 		a->is_open = 0;
 	}
 }
 
 static LibError Archive_reload(Archive* a, const char* fn, Handle)
 {
 	// (note: don't warn on failure - this happens when
 	// vfs_mount blindly archive_open-s a dir)
 	RETURN_ERR(file_open(fn, FILE_CACHE_BLOCK, &a->f));
 	a->is_open = 1;
 
 	RETURN_ERR(zip_populate_archive(&a->f, a));
 	a->is_loaded = 1;
 
 	return ERR_OK;
 }
 
 static LibError Archive_validate(const Archive* a)
 {
 	RETURN_ERR(file_validate(&a->f));
 
 	if(debug_is_pointer_bogus(a->ents))
 		return ERR_1;
 
 	return ERR_OK;
 }
 
 static LibError Archive_to_string(const Archive* a, char* buf)
 {
 	snprintf(buf, H_STRING_LEN, "(%u files)", a->num_files);
 	return ERR_OK;
 }
 
 
 
 // open and return a handle to the archive indicated by <fn>.
 // somewhat slow - each file is added to an internal index.
 Handle archive_open(const char* fn)
 {
 	TIMER("archive_open");
 	return h_alloc(H_Archive, fn);
 }
 
 
 // close the archive <ha> and set ha to 0
 LibError archive_close(Handle& ha)
 {
 	return h_free(ha, H_Archive);
 }
 
 
 
 
 // look up ArchiveEntry, given filename (untrusted!).
 static LibError archive_get_file_info(Archive* a, const char* fn, uintptr_t memento, ArchiveEntry*& ent)
 {
 	if(memento)
 	{
 		ent = (ArchiveEntry*)memento;
 		return ERR_OK;
 	}
 	else
 	{
 		const char* atom_fn = file_make_unique_fn_copy(fn);
 		for(uint i = 0; i < a->num_files; i++)
 			if(a->ents[i].atom_fn == atom_fn)
 			{
 				ent = &a->ents[i];
 				return ERR_OK;
 			}
 	}
 
 	return ERR_FILE_NOT_FOUND;
 }
 
 
 // successively call <cb> for each valid file in the archive <ha>,
 // passing the complete path and <user>.
 // if it returns a nonzero value, abort and return that, otherwise 0.
 //
 // FileCB's name parameter will be the full path and unique
 // (i.e. returned by file_make_unique_fn_copy).
 LibError archive_enum(const Handle ha, const FileCB cb, const uintptr_t user)
 {
 	H_DEREF(ha, Archive, a);
 
 	struct stat s;
 	memset(&s, 0, sizeof(s));
 
 	for(uint i = 0; i < a->num_files; i++)
 	{
 		const ArchiveEntry* ent = &a->ents[i];
 		s.st_mode  = S_IFREG;
 		s.st_size  = (off_t)ent->ucsize;
 		s.st_mtime = ent->mtime;
 		const uintptr_t memento = (uintptr_t)ent;
 		LibError ret = cb(ent->atom_fn, &s, memento, user);
 		if(ret != INFO_CB_CONTINUE)
 			return ret;
 	}
 
 	return ERR_OK;
 }
 
 
 LibError archive_allocate_entries(Archive* a, size_t num_entries)
 {
 	debug_assert(num_entries != 0);	// =0 makes no sense but wouldn't be fatal
 
 	debug_assert(a->ents == 0);	// must not have been allocated yet
 	a->ents = (ArchiveEntry*)mem_alloc(num_entries * sizeof(ArchiveEntry), 32);
 	if(!a->ents)
 		WARN_RETURN(ERR_NO_MEM);
 	return ERR_OK;
 }
 
 
 // add file <fn> to the lookup data structure.
 // called from za_enum_files in order (0 <= idx < num_entries).
 // the first call notifies us of # entries, so we can allocate memory.
 //
 // note: ent is only valid during the callback! must be copied or saved.
 LibError archive_add_file(Archive* a, const ArchiveEntry* ent)
 {
 	a->ents[a->num_files++] = *ent;
 	return ERR_OK;
 }
 
 
 
 ///////////////////////////////////////////////////////////////////////////////
 //
 // afile_*: file from Zip archive
 // uses lookup to get file information; holds inflate state.
 //
 ///////////////////////////////////////////////////////////////////////////////
 
 // convenience function, allows implementation change in AFile.
 // note that size == ucsize isn't foolproof, and adding a flag to
 // ofs or size is ugly and error-prone.
 // no error checking - always called from functions that check af.
 static inline bool is_compressed(AFile* af)
 {
 	return af->method != CM_NONE;
 }
 
 
 
 
 // get file status (size, mtime). output param is zeroed on error.
 LibError afile_stat(Handle ha, const char* fn, struct stat* s)
 {
 	// zero output param in case we fail below.
 	memset(s, 0, sizeof(struct stat));
 
 	H_DEREF(ha, Archive, a);
 
 	ArchiveEntry* ent;
 	CHECK_ERR(archive_get_file_info(a, fn, 0, ent));
 
 	s->st_size  = ent->ucsize;
 	s->st_mtime = ent->mtime;
 	return ERR_OK;
 }
 
 
 
 
 LibError afile_validate(const AFile* af)
 {
 	if(!af)
 		return ERR_INVALID_PARAM;
 	// note: don't check af->ha - it may be freed at shutdown before
 	// its files. TODO: revisit once dependency support is added.
 	if(!af->fc.size)
 		return ERR_1;
 	// note: af->ctx is 0 if file is not compressed.
 
 	return ERR_OK;
 }
 
 #define CHECK_AFILE(af) CHECK_ERR(afile_validate(af))
 
 
 // open file, and fill *af with information about it.
 // return < 0 on error (output param zeroed). 
 LibError afile_open(const Handle ha, const char* fn, uintptr_t memento, int flags, AFile* af)
 {
 	// zero output param in case we fail below.
 	memset(af, 0, sizeof(*af));
 
 	H_DEREF(ha, Archive, a);
 
 	// this is needed for AFile below. optimization: archive_get_file_info
 	// wants the original filename, but by passing the unique copy
 	// we avoid work there (its file_make_unique_fn_copy returns immediately)
 	const char* atom_fn = file_make_unique_fn_copy(fn);
 
 	ArchiveEntry* ent;
 	// don't want AFile to contain a ArchiveEntry struct -
 	// its ucsize member must be 'loose' for compatibility with File.
 	// => need to copy ArchiveEntry fields into AFile.
 	RETURN_ERR(archive_get_file_info(a, atom_fn, memento, ent));
 
 	zip_fixup_lfh(&a->f, ent);
 
 	uintptr_t ctx = 0;
 	// slight optimization: do not allocate context if not compressed
 	if(ent->method != CM_NONE)
 	{
 		ctx = comp_alloc(CT_DECOMPRESSION, ent->method);
 		if(!ctx)
 			return ERR_NO_MEM;
 	}
 
 	af->fc.flags   = flags;
 	af->fc.size    = ent->ucsize;
 	af->fc.atom_fn = atom_fn;
 	af->ofs       = ent->ofs;
 	af->csize     = ent->csize;
 	af->method    = ent->method;
 	af->ha        = ha;
 	af->ctx       = ctx;
 	af->is_mapped = 0;
 	CHECK_AFILE(af);
 	return ERR_OK;
 }
 
 
 // close file.
 LibError afile_close(AFile* af)
 {
 	CHECK_AFILE(af);
 	// other AFile fields don't need to be freed/cleared
 	comp_free(af->ctx);
 	af->ctx = 0;
 	return ERR_OK;
 }
 
 
 
 ///////////////////////////////////////////////////////////////////////////////
 //
 // sync and async I/O
 // uses file_* and inf_*.
 //
 ///////////////////////////////////////////////////////////////////////////////
 
 
 static const size_t CHUNK_SIZE = 16*KiB;
 
 // begin transferring <size> bytes, starting at <ofs>. get result
 // with afile_io_wait; when no longer needed, free via afile_io_discard.
 LibError afile_io_issue(AFile* af, off_t user_ofs, size_t max_output_size, void* user_buf, AFileIo* io)
 {
 	// zero output param in case we fail below.
 	memset(io, 0, sizeof(AFileIo));
 
 	CHECK_AFILE(af);
 	H_DEREF(af->ha, Archive, a);
 
 	// not compressed; we'll just read directly from the archive file.
 	// no need to clamp to EOF - that's done already by the VFS.
 	if(!is_compressed(af))
 	{
 		// io->ctx is 0 (due to memset)
 		const off_t ofs = af->ofs+user_ofs;
 		return file_io_issue(&a->f, ofs, max_output_size, user_buf, &io->io);
 	}
 
 
 	io->ctx = af->ctx;
 	io->max_output_size = max_output_size;
 	io->user_buf = user_buf;
 
 	const off_t cofs = af->ofs + af->last_cofs;	// needed to determine csize
 
 	// read up to next chunk (so that the next read is aligned -
 	// less work for aio) or up to EOF.
 	const ssize_t left_in_chunk = CHUNK_SIZE - (cofs % CHUNK_SIZE);
 	const ssize_t left_in_file = af->csize - cofs;
 	const size_t csize = MIN(left_in_chunk, left_in_file);
 
 	void* cbuf = mem_alloc(csize, 4*KiB);
 	if(!cbuf)
 		return ERR_NO_MEM;
 
 	CHECK_ERR(file_io_issue(&a->f, cofs, csize, cbuf, &io->io));
 
 	af->last_cofs += (off_t)csize;
 	return ERR_OK;
 }
 
 
 // indicates if the IO referenced by <io> has completed.
 // return value: 0 if pending, 1 if complete, < 0 on error.
 int afile_io_has_completed(AFileIo* io)
 {
 	return file_io_has_completed(&io->io);
 }
 
 
 // wait until the transfer <io> completes, and return its buffer.
 // output parameters are zeroed on error.
 LibError afile_io_wait(AFileIo* io, void*& buf, size_t& size)
 {
 	buf = 0;
 	size = 0;
 
 	void* raw_buf;
 	size_t raw_size;
 	CHECK_ERR(file_io_wait(&io->io, raw_buf, raw_size));
 
 	// file is compressed and we need to decompress
 	if(io->ctx)
 	{
 		comp_set_output(io->ctx, (void*)io->user_buf, io->max_output_size);
 		ssize_t ucbytes_output = comp_feed(io->ctx, raw_buf, raw_size);
 		free(raw_buf);
 		RETURN_ERR(ucbytes_output);
 
 		buf = io->user_buf;
 		size = ucbytes_output;
 	}
 	else
 	{
 		buf  = raw_buf;
 		size = raw_size;
 	}
 
 	return ERR_OK;
 }
 
 
 // finished with transfer <io> - free its buffer (returned by afile_io_wait)
 LibError afile_io_discard(AFileIo* io)
 {
 	return file_io_discard(&io->io);
 }
 
 
 LibError afile_io_validate(const AFileIo* io)
 {
 	if(debug_is_pointer_bogus(io->user_buf))
 		return ERR_1;
 	// <ctx> and <max_output_size> have no invariants we could check.
 	RETURN_ERR(file_io_validate(&io->io));
 	return ERR_OK;
 }
 
 
 ///////////////////////////////////////////////////////////////////////////////
 
 
 
 
 
 class Decompressor
 {
 public:
 	Decompressor(uintptr_t comp_ctx_, size_t ucsize_max, bool use_temp_buf_, FileIOCB cb, uintptr_t cb_ctx)
 	{
 		comp_ctx = comp_ctx_;
 
 		csize_total = 0;
 		ucsize_left = ucsize_max;
 
 		use_temp_buf = use_temp_buf_;
 
 		user_cb = cb;
 		user_cb_ctx = cb_ctx;
 	}
 
 	LibError feed(const void* cblock, size_t csize, size_t* bytes_processed)
 	{
 		if(use_temp_buf)
 			RETURN_ERR(comp_alloc_output(comp_ctx, csize));
 
 		void* ucblock = comp_get_output(comp_ctx);
 
 		const size_t ucsize = comp_feed(comp_ctx, cblock, csize);
 		*bytes_processed = ucsize;
 		debug_assert(ucsize <= ucsize_left);
 		ucsize_left -= ucsize;
 
 		LibError ret = INFO_CB_CONTINUE;
 		if(user_cb)
 			ret = user_cb(user_cb_ctx, ucblock, ucsize, bytes_processed);
 		if(ucsize_left == 0)
 			ret = ERR_OK;
 		return ret;
 	}
 
 	size_t total_csize_fed() const { return csize_total; }
 
 private:
 	uintptr_t comp_ctx;
 
 	size_t csize_total;
 	size_t ucsize_left;
 
 	bool use_temp_buf;
 
 	// allow user-specified callbacks: "chain" them, because file_io's
 	// callback mechanism is already used to return blocks.
 	FileIOCB user_cb;
 	uintptr_t user_cb_ctx;
 };
 
 
 static LibError decompressor_feed_cb(uintptr_t cb_ctx,
 	const void* cblock, size_t csize, size_t* bytes_processed)
 {
 	Decompressor* d = (Decompressor*)cb_ctx;
 	return d->feed(cblock, csize, bytes_processed);
 }
 
 
 // read from the (possibly compressed) file <af> as if it were a normal file.
 // starting at the beginning of the logical (decompressed) file,
 // skip <ofs> bytes of data; read the next <size> bytes into <*pbuf>.
 //
 // if non-NULL, <cb> is called for each block read, passing <ctx>.
 // if it returns a negative error code,
 // the read is aborted and that value is returned.
 // the callback mechanism is useful for user progress notification or
 // processing data while waiting for the next I/O to complete
 // (quasi-parallel, without the complexity of threads).
 //
 // return bytes read, or a negative error code.
 ssize_t afile_read(AFile* af, off_t ofs, size_t size, FileIOBuf* pbuf, FileIOCB cb, uintptr_t cb_ctx)
 {
 	CHECK_AFILE(af);
 	H_DEREF(af->ha, Archive, a);
 
 	if(!is_compressed(af))
 	{
 		// HACK
 		// background: file_io will operate according to the
 		// *archive* file's flags, but the AFile may contain some overrides
 		// set via vfs_open. one example is FILE_LONG_LIVED -
 		// that must be copied over (temporarily) into a->f flags.
 		//
 		// we currently copy all flags - this may mean that setting
 		// global policy (e.g. "don't cache") for all archive files is
 		// difficult, but that can be worked around by forcing
 		// flag to be set in afile_open.
 		// this is better than the alternative of copying individual
 		// flags because it'd need to be updated as new flags are added.
 		a->f.fc.flags = af->fc.flags;
 
 		bool we_allocated = (pbuf != FILE_BUF_TEMP) && (*pbuf == FILE_BUF_ALLOC);
 		// no need to set last_cofs - only checked if compressed.
 		ssize_t bytes_read = file_io(&a->f, af->ofs+ofs, size, pbuf, cb, cb_ctx);
 		RETURN_ERR(bytes_read);
 		if(we_allocated)
 			(void)file_buf_set_real_fn(*pbuf, af->fc.atom_fn);
 		return bytes_read;
 	}
 
 	debug_assert(af->ctx != 0);
 
 	RETURN_ERR(file_buf_get(pbuf, size, af->fc.atom_fn, af->fc.flags, cb));
 	const bool use_temp_buf = (pbuf == FILE_BUF_TEMP);
 	if(!use_temp_buf)
 		comp_set_output(af->ctx, (void*)*pbuf, size);
 
 	const off_t cofs = af->ofs+af->last_cofs;
 	// remaining bytes in file. callback will cause IOs to stop when
 	// enough ucdata has been produced.
 	const size_t csize_max = af->csize - af->last_cofs;
 
 	Decompressor d(af->ctx, size, use_temp_buf, cb, cb_ctx);
 	ssize_t uc_transferred = file_io(&a->f, cofs, csize_max, FILE_BUF_TEMP, decompressor_feed_cb, (uintptr_t)&d);
 
 	af->last_cofs += (off_t)d.total_csize_fed();
 
 	return uc_transferred;
 }
 
 
 ///////////////////////////////////////////////////////////////////////////////
 //
 // file mapping
 //
 ///////////////////////////////////////////////////////////////////////////////
 
 
 // map the entire file <af> into memory. mapping compressed files
 // isn't allowed, since the compression algorithm is unspecified.
 // output parameters are zeroed on failure.
 //
 // the mapping will be removed (if still open) when its file is closed.
 // however, map/unmap calls should still be paired so that the mapping
 // may be removed when no longer needed.
 LibError afile_map(AFile* af, void*& p, size_t& size)
 {
 	p = 0;
 	size = 0;
 
 	CHECK_AFILE(af);
 
 	// mapping compressed files doesn't make sense because the
 	// compression algorithm is unspecified - disallow it.
 	if(is_compressed(af))
 		WARN_RETURN(ERR_IS_COMPRESSED);
 
 	// note: we mapped the archive in archive_open, but unmapped it
 	// in the meantime to save memory in case it wasn't going to be mapped.
 	// now we do so again; it's unmapped in afile_unmap (refcounted).
 	H_DEREF(af->ha, Archive, a);
 	void* archive_p;
 	size_t archive_size;
 	CHECK_ERR(file_map(&a->f, archive_p, archive_size));
 
 	p = (char*)archive_p + af->ofs;
 	size = af->fc.size;
 
 	af->is_mapped = 1;
 	return ERR_OK;
 }
 
 
 // remove the mapping of file <af>; fail if not mapped.
 //
 // the mapping will be removed (if still open) when its archive is closed.
 // however, map/unmap calls should be paired so that the archive mapping
 // may be removed when no longer needed.
 LibError afile_unmap(AFile* af)
 {
 	CHECK_AFILE(af);
 
 	// make sure archive mapping refcount remains balanced:
 	// don't allow multiple|"false" unmaps.
 	if(!af->is_mapped)
 		return ERR_FAIL;
 	af->is_mapped = 0;
 
 	H_DEREF(af->ha, Archive, a);
 	return file_unmap(&a->f);
 }
 
 
 //-----------------------------------------------------------------------------
 // archive builder
 //-----------------------------------------------------------------------------
 
 static inline bool file_type_is_uncompressible(const char* fn)
 {
 	const char* ext = strrchr(fn, '.');
 	// no extension? bail; assume compressible
 	if(!ext)
 		return true;
 
 	// this is a selection of file types that are certainly not
 	// further compressible. we need not include every type under the sun -
 	// this is only a slight optimization that avoids wasting time
 	// compressing files. the real decision as to cmethod is made based
 	// on attained compression ratio.
 	static const char* uncompressible_exts[] =
 	{
 		"zip", "rar",
 		"jpg", "jpeg", "png",
 		"ogg", "mp3"
 	};
 
 	for(uint i = 0; i < ARRAY_SIZE(uncompressible_exts); i++)
 	{
 		if(!stricmp(ext+1, uncompressible_exts[i]))
 			return true;
 	}
 
 	return false;
 }
 
 
 struct CompressParams
 {
 	bool attempt_compress;
 	uintptr_t ctx;
 	u32 crc;
 };
 
 #include <zlib.h>
 
 static LibError compress_cb(uintptr_t cb_ctx, const void* block, size_t size, size_t* bytes_processed)
 {
 	CompressParams* p = (CompressParams*)cb_ctx;
 
 	// comp_feed already makes note of total #bytes fed, and we need
 	// vfs_io to return the uc size (to check if all data was read).
 	*bytes_processed = size;
 
 	// update checksum
 	p->crc = crc32(p->crc, (const Bytef*)block, (uInt)size);
 
 	if(p->attempt_compress)
 		(void)comp_feed(p->ctx, block, size);
 	return INFO_CB_CONTINUE;
 }
 
 
 // final decision on whether to store the file as compressed,
 // given the observed compressed/uncompressed sizes.
 static bool should_store_compressed(size_t ucsize, size_t csize)
 {
 	const float ratio = (float)ucsize / csize;
 	const ssize_t bytes_saved = (ssize_t)ucsize - (ssize_t)csize;
+	UNUSED2(bytes_saved);
 
 	// tiny - store compressed regardless of savings.
 	// rationale:
 	// - CPU cost is negligible and overlapped with IO anyway;
 	// - reading from compressed files uses less memory because we
 	//   don't need to allocate space for padding in the final buffer.
 	if(ucsize < 512)
 		return true;
 
 	// large high-entropy file - store uncompressed.
 	// rationale:
 	// - any bigger than this and CPU time becomes a problem: it isn't
 	//   necessarily hidden by IO time anymore.
 	if(ucsize >= 32*KiB && ratio < 1.02f)
 		return false;
 
 	// TODO: any other cases?
 	// we currently store everything else compressed.
 	return true;
 }
 
 static LibError read_and_compress_file(const char* atom_fn, uintptr_t ctx,
 	ArchiveEntry& ent, void*& file_contents, FileIOBuf& buf)	// out
 {
 	struct stat s;
 	RETURN_ERR(vfs_stat(atom_fn, &s));
 	const size_t ucsize = s.st_size;
 	// skip 0-length files.
 	// rationale: zip.cpp needs to determine whether a CDFH entry is
 	// a file or directory (the latter are written by some programs but
 	// not needed - they'd only pollute the file table).
 	// it looks like checking for ucsize=csize=0 is the safest way -
 	// relying on file attributes (which are system-dependent!) is
 	// even less safe.
 	// we thus skip 0-length files to avoid confusing them with dirs.
 	if(!ucsize)
 		return INFO_SKIPPED;
 
 	const bool attempt_compress = !file_type_is_uncompressible(atom_fn);
 	if(attempt_compress)
 	{
 		RETURN_ERR(comp_reset(ctx));
 		RETURN_ERR(comp_alloc_output(ctx, ucsize));
 	}
 
 	// read file into newly allocated buffer. if attempt_compress, also
 	// compress the file into another buffer while waiting for IOs.
 	size_t ucsize_read;
 	const uint flags = 0;
 	CompressParams params = { attempt_compress, ctx, 0 };
 	RETURN_ERR(vfs_load(atom_fn, buf, ucsize_read, flags, compress_cb, (uintptr_t)&params));
 	debug_assert(ucsize_read == ucsize);
 
 	// if we compressed the file trial-wise, check results and
 	// decide whether to store as such or not (based on compression ratio)
 	bool store_compressed = false;
 	void* cdata = 0; size_t csize = 0;
 	if(attempt_compress)
 	{
 		LibError ret = comp_finish(ctx, &cdata, &csize);
 		if(ret < 0)
 		{
 			file_buf_free(buf);
 			return ret;
 		}
 
 		store_compressed = should_store_compressed(ucsize, csize);
 	}
 
 	// store file info
 	ent.ucsize  = (off_t)ucsize;
 	ent.mtime   = s.st_mtime;
 	// .. ent.ofs is set by zip_archive_add_file
 	ent.flags   = 0;
 	ent.atom_fn = atom_fn;
 	ent.crc32   = params.crc;
 	if(store_compressed)
 	{
 		ent.method = CM_DEFLATE;
 		ent.csize  = (off_t)csize;
 		file_contents = cdata;
 	}
 	else
 	{
 		ent.method = CM_NONE;
 		ent.csize  = (off_t)ucsize;
 		file_contents = (void*)buf;
 	}
 
 	// note: no need to free cdata - it is owned by the
 	// compression context and can be reused.
 
 	return ERR_OK;
 }
 
 
 
 LibError archive_build_init(const char* P_archive_filename, Filenames V_fns,
 	ArchiveBuildState* ab)
 {
 	RETURN_ERR(zip_archive_create(P_archive_filename, &ab->za));
 	ab->ctx = comp_alloc(CT_COMPRESSION, CM_DEFLATE);
 	ab->V_fns = V_fns;
 
 	// count number of files (needed to estimate progress)
 	for(ab->num_files = 0; ab->V_fns[ab->num_files]; ab->num_files++) {}
 
 	ab->i = 0;
 	return ERR_OK;
 }
 
 
 #include "ps/Loader.h"
 
 int archive_build_continue(ArchiveBuildState* ab)
 {
 
 	const double end_time = get_time() + 200e-3;
 
 	for(;;)
 	{
 		const char* V_fn = ab->V_fns[ab->i];
 		if(!V_fn)
 			break;
 
 		ArchiveEntry ent; void* file_contents; FileIOBuf buf;
 		if(read_and_compress_file(V_fn, ab->ctx, ent, file_contents, buf) == ERR_OK)
 		{
 			(void)zip_archive_add_file(ab->za, &ent, file_contents);
 			(void)file_buf_free(buf);
 		}
 
 		ab->i++;
 		LDR_CHECK_TIMEOUT((int)ab->i, (int)ab->num_files);
 	}
 
 	// note: this is currently known to fail if there are no files in the list
 	// - zlib.h says: Z_DATA_ERROR is returned if freed prematurely.
 	// safe to ignore.
 	comp_free(ab->ctx); ab->ctx = 0;
 	(void)zip_archive_finish(ab->za);
 
 	return ERR_OK;
 }
 
 
 void archive_build_cancel(ArchiveBuildState* ab)
 {
 	comp_free(ab->ctx); ab->ctx = 0;
 	(void)zip_archive_finish(ab->za);
 	memset(ab, 0, sizeof(*ab));
 }
 
 
 LibError archive_build(const char* P_archive_filename, Filenames V_fns)
 {
 	ArchiveBuildState ab;
 	RETURN_ERR(archive_build_init(P_archive_filename, V_fns, &ab));
 	for(;;)
 	{
 		int ret = archive_build_continue(&ab);
 		RETURN_ERR(ret);
 		if(ret == ERR_OK)
 			return ERR_OK;
 	}
 }
\ No newline at end of file