----------------------------------------------------------------------------------------------------------------
-- Camera helper functions
-- (c) 2003 Relic Entertainment Inc.

--? @group Camera

----------------------------------------------------------------------------------------------------------------
 


function Camera_FocusOnTargetMarker( marker, secs )
	Camera_MoveToPosition(marker, false)
end

function Camera_FocusOnTargetMarkerIfClose(marker)
	Camera_MoveToPositionIfClose(marker)
end


SLOW_CAMERA_PANNING = 0.5



--? @shortdesc Move the camera to desired location. The optional pan flag should be true if you want the camera to glide to the new location. You can specify a pan rate to use (use SLOW_CAMERA_PANNING for a default slower rate)
--? @extdesc This function canNOT be called through a CTRL object in NISlets.
--? @args MarkerID/Pos position[, Boolean pan, Float panRate]
--? @result Void
function Camera_MoveToPosition(pos, pan, panRate)
	
	-- if we were passed in a marker, convert it to a pos
	if scartype(pos) == ST_MARKER then
		pos = Marker_GetPosition(pos)
	end
	if (pan == nil) then pan = false end

	-- shift the camera
	Camera_FocusOnPosition(pos, pan)

	if panRate ~= nil then
		Camera_SetSlideTargetRate(panRate)
	end
	
end



--? @shortdesc Slightly refocus the camera to rest on a position if it's close by.
--? @extdesc This function can be called through a CTRL object in NISlets.
--? @args MarkerID/Pos position
--? @result Void
function Camera_MoveToPositionIfClose(pos)
	
	-- if we were passed in a marker, convert it to a pos
	if scartype(pos) == ST_MARKER then
		pos = Marker_GetPosition(pos)
	end
	
	-- work out how close we are to the position already
	local dist = World_DistancePointToPoint(Camera_GetTargetPos(), pos)
	
	-- shift the camera is it's within our range
	if dist > 5 and dist < 20 then
		
		Camera_FocusOnPosition(pos, true)
		Camera_SetSlideTargetRate(SLOW_CAMERA_PANNING)
		
	end
	
end



--? @shortdesc Move the camera to an EGroup's location. The optional pan flag should be true if you want the camera to glide to the new location. You can specify a pan rate to use (use SLOW_CAMERA_PANNING for a default slower rate)
--? @extdesc This function can be called through a CTRL object in NISlets.
--? @args EGroupID egroup[, Boolean pan, Float panRate]
--? @result Void
function Camera_MoveToEGroup(egroup, pan, panRate)

	if (pan == nil) then pan = false end
	
	if EGroup_Count(egroup) >= 1 then
		
		local pos = 1
		
		if EGroup_GetSpread(egroup) > Camera_GetZoomDist() then
			pos = Entity_GetPosition(EGroup_GetSpawnedEntityAt(egroup, 1))
		else
			pos = EGroup_GetPosition(egroup)
		end
		
		Camera_FocusOnPosition(pos, pan)
		
		if panRate ~= nil then
			Camera_SetSlideTargetRate(panRate)
		end
		
	end

end



--? @shortdesc Move the camera to an SGroup's location. The optional pan flag should be true if you want the camera to glide to the new location. You can specify a pan rate to use (use SLOW_CAMERA_PANNING for a default slower rate)
--? @extdesc This function can be called through a CTRL object in NISlets.
--? @args SGroupID sgroup[, Boolean pan, Float panRate]
--? @result Void
function Camera_MoveToSGroup(sgroup, pan, panRate)

	if (pan == nil) then pan = false end
	
	if SGroup_Count(sgroup) >= 1 then
		
		local pos = 1
		
		if SGroup_GetSpread(sgroup) > Camera_GetZoomDist() then
			pos = Squad_GetPosition(SGroup_GetSpawnedSquadAt(sgroup, 1))
		else
			pos = SGroup_GetPosition(sgroup)
		end
		
		Camera_FocusOnPosition(pos, pan)
		
		if panRate ~= nil then
			Camera_SetSlideTargetRate(panRate)
		end
		
	end

end



--? @shortdesc Set the camera to follow the first squad in an SGroup.
--? @extdesc The camera will follow them until the player takes control again.
--? @args SGroupID sgroup
--? @result Void
function Camera_FollowSGroup(sgroup)
	
	if (SGroup_Count(sgroup) >= 1) then
		Camera_FollowSquad(SGroup_GetSpawnedSquadAt(sgroup, 1))
	end
	
end

