Frames API

--[[
	Frames	  Trystan Cannon
				12 February 2013

	This is a redesign of an API
	which I had written and didn't
	function properly because of the
	faulty design.

	This API implements a method of recording
	the screen in frames. However, saving
	an entire recording isn't practical because
	of how large the file size would be.

	A decent use for this API is to take
	screenshots in game.
]]--


-- Returns the true size of a table using pairs().
local function getTableSize (myTable)
	local size = 0

	for _, __ in pairs (myTable) do
		size = size + 1
	end

	return size
end

-- Hooks the given screen buffer to the current terminal API.
function hookTerminal (screenBuffer)
	local hookedTerminal = {}
	for index, item in pairs (term.native) do
		hookedTerminal[index] = item
	end


	-- TODO: Implement this function!
	hookedTerminal["scroll"] = function (linesToScroll)
		local lines = {}

		for line = linesToScroll + 1, screenBuffer.screenHeight do
			lines[#lines + 1] = screenBuffer[line]
		end
		-- Fill in any remaining lines with empty space.
		for line = (getTableSize (lines) == 1 and getTableSize (lines) or 1), screenBuffer.screenHeight do
			lines[#lines + 1] = {}

			for xPos = 1, screenBuffer.screenWidth do
				lines[#lines][xPos] = {text = ' ', backgroundColor = colors.black, textColor = colors.white}
			end
		end

		-- Insert the lines table as the current screen buffer lines.
		for line = 1, screenBuffer.screenHeight do
			screenBuffer[line] = lines[line]
		end
		return term.native.scroll (linesToScroll)
	end

	hookedTerminal["clearLine"] = function()
		local _, line = term.native.getCursorPos()

		-- Clear the line by replacing every cell in it with spaces.
		for xPos = 1, screenBuffer.screenWidth do
			screenBuffer[line][xPos] = {text = ' ', backgroundColor = screenBuffer.backgroundColor, textColor = screenBuffer.textColor}
		end

		return term.native.clearLine()
	end

	hookedTerminal["clear"] = function()
		-- Clear the screen buffer by, instead of dumping it, replace every line with spaces.
		for line = 1, screenBuffer.screenHeight do
			for xPos = 1, screenBuffer.screenWidth do
				screenBuffer[line][xPos] = {text = ' ', backgroundColor = screenBuffer.backgroundColor, textColor = screenBuffer.textColor}
			end
		end

		return term.native.clear()
	end

	hookedTerminal["setTextColor"] = function (textColor)
		screenBuffer.textColor = textColor
		return term.native.setTextColor (textColor)
	end

	hookedTerminal["setBackgroundColor"] = function (backgroundColor)
		screenBuffer.backgroundColor = backgroundColor
		return term.native.setBackgroundColor (backgroundColor)
	end

	hookedTerminal["setCursorBlink"] = function (cursorBlink)
		screenBuffer.cursorBlink = cursorBlink
		return term.native.setCursorBlink (cursorBlink)
	end

	hookedTerminal["write"] = function (text)
		local currentX, currentY = term.native.getCursorPos()
		local currentX_offset	= currentX
		local backgroundColor	= screenBuffer.backgroundColor
		local textColor		  = screenBuffer.textColor

		local subOffset = 1
		while currentX < currentX_offset + text:len() do
			screenBuffer[currentY][currentX] = {text = text:sub (subOffset, subOffset), backgroundColor = backgroundColor, textColor = textColor}

			subOffset = subOffset + 1
			currentX  = currentX  + 1
		end

		return term.native.write (text)
	end

	term.redirect (hookedTerminal)
end

-- Initializes the frame environment.
function initFrameEnvironment()
	local screenWidth, screenHeight = term.getSize()
	_G.frameEnvironment			  = {}


	_G.frameEnvironment.screenBuffer = {
		cursorBlink	 = true,
		backgroundColor = colors.black,
		textColor	   = colors.white,
		screenWidth	 = screenWidth,
		screenHeight	= screenHeight
	}
	-- Initialize the screen buffer by adding all of the cell tables.
	for line = 1, _G.frameEnvironment.screenBuffer.screenHeight do
		_G.frameEnvironment.screenBuffer[line] = {}

		for xPos = 1, _G.frameEnvironment.screenBuffer.screenWidth do
			_G.frameEnvironment.screenBuffer[line][xPos] = {text = ' ', backgroundColor = _G.frameEnvironment.screenBuffer.backgroundColor, textColor = _G.frameEnvironment.screenBuffer.textColor}
		end
	end


	-- Returns a copy of the screen buffer and the current os.clock() time. This is a frame.
	-- NOTE: A frame object always has a 'cursorBlink' field too!
	_G.frameEnvironment.getCurrentFrame = function()
		local currentX, currentY = term.native.getCursorPos()

		local currentFrame = {
			cursorBlink = _G.frameEnvironment.screenBuffer.cursorBlink,
			cursorPos   = {x = currentX, y = currentY}
		}

		for line = 1, _G.frameEnvironment.screenBuffer.screenHeight do
			currentFrame[line] = {}

			for xPos = 1, _G.frameEnvironment.screenBuffer.screenWidth do
				currentFrame[line][xPos] = {}

				for index, item in pairs (_G.frameEnvironment.screenBuffer[line][xPos]) do
					currentFrame[line][xPos][index] = item
				end
			end
		end

		return currentFrame, os.clock()
	end

	-- Draws the given frame.
	-- NOTE: This function does not return the cursor position, blink, or screen colors to their original state!
	_G.frameEnvironment.drawFrame = function (frame)
		term.native.setCursorBlink (false)

		for line = 1, _G.frameEnvironment.screenBuffer.screenHeight do
			for xPos = 1, _G.frameEnvironment.screenBuffer.screenWidth do
				local cell = frame[line][xPos]

				if getTableSize (cell) > 0 then
					term.native.setCursorPos (xPos, line)
					term.native.setBackgroundColor (cell.backgroundColor)
					term.native.setTextColor (cell.textColor)
					term.write (cell.text)
				end
			end
		end

		term.native.setCursorBlink (frame.cursorBlink)
		term.native.setCursorPos (frame.cursorPos.x, frame.cursorPos.y)
	end



	-- Ensure that the terminal API is writing to the screen buffer by hooking the screen buffer to the terminal API.
	hookTerminal (_G.frameEnvironment.screenBuffer)
end