Annotate some of the functionality related to worldviews

changelog/snippets/other.6600.md

@@ -0,0 +1 @@
+- (#6600) Annotate functionality related to worldviews

engine/User.lua

@@ -386,9 +386,17 @@ end
 function GetFireState(units)
 end
 
---- Returns the root UI frame for a given head
+--- Returns the root UI frame for a given adapter. You can use `GetFrame(0)` to retrieve the primary adapter. And you can use `GetFrame(1)` to retrieve the secondary adapter. 
+---
+--- In the game options you can add a second adapter under the 'Video' tab.
+--- 
+--- See also `GetNumRootFrames()` to determine the number of root frames. 
+--- 
+--- See also the following modules that manage these frames:
+--- - Primary adapter: lua\ui\game\worldview.lua
+--- - Secondary adapter: lua\ui\game\multihead.lua
 ---@param head number
----@return Frame
+---@return Frame | nil
 function GetFrame(head)
 end
 
@@ -473,7 +481,14 @@ end
 function GetMovieVolume()
 end
 
---- Returns the current number of root frames (typically one per head)
+--- Returns the current number of root frames. There is usually only one root frame for each adapter (monitor). This is often referred to as a 'head' in other comments.
+--- 
+--- In the game options you can add a second adapter under the 'Video' tab.
+---
+--- See also `GetFrame(0)` and `GetFrame(1)` to retrieve the root frame for a given adapter. 
+--- See also the following modules that manage these frames:
+--- - Primary adapter: lua\ui\game\worldview.lua
+--- - Secondary adapter: lua\ui\game\multihead.lua
 ---@return number
 function GetNumRootFrames()
 end

engine/User/CUIWorldView.lua

@@ -12,11 +12,17 @@ local CUIWorldView = {}
 function CUIWorldView:__init(parentControl, cameraName, depth, isMiniMap, trackCamera)
 end
 
----
+--- Resets the camera that is attached to the worldview.
 function CUIWorldView:CameraReset()
 end
 
----Enables/Disables custom world rendering for worldview
+--- If true, enables the rendering of custom world shapes. 
+--- 
+--- See also:
+--- - lua\ui\game\renderable\circle.lua
+--- - lua\ui\game\renderable\square.lua
+--- 
+--- This is introduced via an assembly patch. For more information: https://github.com/FAForever/FA-Binary-Patches/pull/47
 ---@param bool boolean
 function CUIWorldView:SetCustomRender(bool)
 end
@@ -28,48 +34,55 @@ end
 function CUIWorldView:ProjectMultiple(positions)
 end
 
----
+--- If true, enables the rendering of resources. Note that resources can **never** be rendered when the camera is in free mode.
 ---@param enable boolean
 function CUIWorldView:EnableResourceRendering(enable)
 end
 
----
+--- 
 ---@return string
 function CUIWorldView:GetRightMouseButtonOrder()
 end
 
----
+--- Translates the world position of the unit to screen space.
 ---@param unit Unit
 ---@return Vector2 | nil
 function CUIWorldView:GetScreenPos(unit)
 end
 
----
+--- Flag to determine what camera should receive the global camera commands such as moving with the arrow keys.
 ---@param getsCommands boolean
 function CUIWorldView:GetsGlobalCameraCommands(getsCommands)
 end
 
----
+--- Returns true if the cursor is highlighting a command.
 ---@return boolean
 function CUIWorldView:HasHighlightCommand()
 end
 
----
+--- Returns true if the cartographic shared is applied.
+---@see CUIWorldView:SetCartographic
 ---@return boolean
 function CUIWorldView:IsCartographic()
 end
 
+--- Unlocks the input for the camera that is attached to this worldview. Used for cinematics.
 ---
----@param camera Camera
+--- See also `LockInput` to lock the input and `UnlockInput` to unlock the input.
+---@param camera? Camera
 function CUIWorldView:IsInputLocked(camera)
 end
 
+--- Returns true if the rendering of resources is enabled.
 ---
+--- See also `EnableResourceRendering` to enable or disable the resource rendering.
 ---@return boolean
 function CUIWorldView:IsResourceRenderingEnabled()
 end
 
+--- Unlocks the input for the camera that is attached to this worldview. Used for cinematics.
 ---
+--- See also `UnlockInput` to unlock the input and `IsInputLocked` to determine the current state.
 ---@param camera Camera
 function CUIWorldView:LockInput(camera)
 end
@@ -80,12 +93,12 @@ end
 function CUIWorldView:Project(position)
 end
 
----
+--- If true, enables the cartographic shader.
 ---@param cartographic boolean
 function CUIWorldView:SetCartographic(cartographic)
 end
 
----
+--- If true, enables the highlighting of commands.
 ---@param enabled boolean
 function CUIWorldView:SetHighlightEnabled(enabled)
 end
@@ -95,7 +108,9 @@ end
 function CUIWorldView:ShowConvertToPatrolCursor()
 end
 
+--- Unlocks the input for the camera that is attached to this worldview. Used for cinematics.
 ---
+--- See also `LockInput` to lock the input and `IsInputLocked` to determine the current state.
 ---@param camera Camera
 function CUIWorldView:UnlockInput(camera)
 end

lua/ui/controls/worldview.lua

@@ -216,6 +216,11 @@ local orderToCursorCallback = {
 }
 
 ---@class WorldView : moho.UIWorldView, Control
+---@field _cameraName string        # Name of the camera this world view is attached to.
+---@field _disableMarkers boolean   # If true then markers won't show.
+---@field _displayName string       # Used in the interface
+---@field _order number             # Appears unused
+---@field _registered boolean       # Flag that indicates if this world view is registered with the world view manager.
 ---@field Cursor table
 ---@field CursorTrash TrashBag
 ---@field CursorLastEvent any

lua/ui/game/multihead.lua

@@ -1,30 +1,69 @@
---*****************************************************************************
---* File: lua/modules/ui/game/gamemain.lua
---* Author: Chris Blackwell
---* Summary: Entry point for the in game UI
---*
---* Copyright � 2005 Gas Powered Games, Inc.  All rights reserved.
---*****************************************************************************
+--******************************************************************************************************
+--** Copyright (c) 2022  Willem 'Jip' Wijnia
+--**
+--** Permission is hereby granted, free of charge, to any person obtaining a copy
+--** of this software and associated documentation files (the "Software"), to deal
+--** in the Software without restriction, including without limitation the rights
+--** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+--** copies of the Software, and to permit persons to whom the Software is
+--** furnished to do so, subject to the following conditions:
+--**
+--** The above copyright notice and this permission notice shall be included in all
+--** copies or substantial portions of the Software.
+--**
+--** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+--** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+--** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+--** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+--** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+--** OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+--** SOFTWARE.
+--******************************************************************************************************
+
+--- This module is responsible for creating the secondary worldview.
+---
+--- This module is tightly coupled with the following module(s):
+--- - lua/ui/game/worldview.lua
 
 local UIUtil = import("/lua/ui/uiutil.lua")
 local LayoutHelpers = import("/lua/maui/layouthelpers.lua")
 local Group = import("/lua/maui/group.lua").Group
-local GameCommon = import("/lua/ui/game/gamecommon.lua")
 local Bitmap = import("/lua/maui/bitmap.lua").Bitmap
 
+---@type WorldView | false
 view = false
 
+--- Shows the logo in the secondary adapter.
+---@return nil
 function ShowLogoInHead1()
-    if GetNumRootFrames() < 2 then return end
+
+    ---------------------------------------------------------------------------
+    -- defensive programming
+
+    -- don't do anything if there's only one root frame
+    if GetNumRootFrames() < 2 then
+        return
+    end
 
     local rootFrame = GetFrame(1)
     local bg = Bitmap(rootFrame, UIUtil.UIFile('/marketing/splash.dds'))
     LayoutHelpers.FillParentPreserveAspectRatio(bg, rootFrame)
 end
 
+--- Creates a world view on the secondary adapter. The worldview is registered and available in the world view manager.
+---
+--- This function is referenced directly by the engine.
+---@return nil
 function CreateSecondView()
-    if GetNumRootFrames() < 2 then return end
-
+
+    ---------------------------------------------------------------------------
+    -- defensive programming
+
+    -- don't do anything if there's only one root frame
+    if GetNumRootFrames() < 2 then
+        return
+    end
+
     ClearFrame(1)
     secondHeadGroup = Group(GetFrame(1), "secondHeadGroup")
     LayoutHelpers.FillParent(secondHeadGroup, GetFrame(1))
@@ -33,5 +72,8 @@ function CreateSecondView()
     view:Register('CameraHead2', nil, '<LOC map_view_0003>Secondary View', 3)
     view:SetRenderPass(UIUtil.UIRP_UnderWorld | UIUtil.UIRP_PostGlow) -- don't change this or the camera will lag one frame behind
     LayoutHelpers.FillParent(view, secondHeadGroup)
+end
 
-end
+-- backwards compatibility for mods
+
+local GameCommon = import("/lua/ui/game/gamecommon.lua")

lua/ui/game/worldview.lua

@@ -6,20 +6,39 @@
 --* Copyright © 2005 Gas Powered Games, Inc.  All rights reserved.
 --*****************************************************************************
 
+--- This module is responsible for creating the primary worldview(s) and managing all worldviews in general.
+---
+--- This module is tightly coupled with the following module(s):
+--- - lua/ui/game/multihead.lua
+
 local UIUtil = import("/lua/ui/uiutil.lua")
 local LayoutHelpers = import("/lua/maui/layouthelpers.lua")
 local Bitmap = import("/lua/maui/bitmap.lua").Bitmap
 local Group = import("/lua/maui/group.lua").Group
 local Factions = import("/lua/factions.lua").Factions
 
----@type { [string]: WorldView }
+--- A list of all available worldviews.
+---@type table<string, WorldView>
 MapControls = {}
 
+--- A group that covers the entire screen.
+---@type Group | false
 view = false
+
+--- Primary view, if in split screen this is the left view. The left view is always visible. 
+--- 
+--- Most features that rely on a worldview only work for the left worldview. One example is the reclaim overlay.
+---@type WorldView | false
 viewLeft = false
+
+--- Secondary view used in split screen. This is the right view. 
+---@type WorldView | false
 viewRight = false
+
 secondaryView = false
+
 tertiaryView = false
+
 local parentForFrame = false
 
 positionMarkers = {}
@@ -131,6 +150,10 @@ function MarkStartPositions(startPositions)
     end
 end
 
+--- Creates the world view on the primary monitor.
+---@param parent Control
+---@param mapGroup Control
+---@param mapGroupRight Control | nil   # if provided, creates a split view with a separate world view in both map groups
 function CreateMainWorldView(parent, mapGroup, mapGroupRight)
     -- feature: preserve the world camera when changing views
     ---@type UserCamera
@@ -298,9 +321,10 @@ function UnlockInput()
     end
 end
 
--- this function is called by the engine so it can not be removed (its logic could be changed though)
+--- This function is called by the engine so it can not be removed (its logic could be changed though)
+---@return boolean
 function IsInputLocked()
-    return (viewLeft and viewLeft:IsInputLocked()) or (viewRight and viewRight:IsInputLocked())
+    return (viewLeft and viewLeft:IsInputLocked()) or (viewRight and viewRight:IsInputLocked()) or false
 end
 
 function ForwardMouseWheelInput(event)
@@ -311,6 +335,7 @@ function ForwardMouseWheelInput(event)
     end
 end
 
+---@param val boolean
 function SetHighlightEnabled(val)
     if viewLeft then
         viewLeft:SetHighlightEnabled(val)
@@ -345,7 +370,7 @@ function UnregisterWorldView(view)
     end
 end
 
----@return { [string]: WorldView }
+---@return table<string, WorldView>
 function GetWorldViews()
     return MapControls
 end