From 9bf46ca92edcea4b93803865e59964b679e572a3 Mon Sep 17 00:00:00 2001
From: Laura <milanbartky@gmail.com>
Date: Mon, 20 Nov 2023 05:39:41 -0500
Subject: [PATCH] Added descriptions for a few camera DoF natives (#866)

* Update SetCamFarDof.md

Reduce redundancy by referencing examples instead.

* Update SetUseHiDof.md

Better to not link to URLs that could get lost in the future.

---------

Co-authored-by: ammonia-cfx <38232208+4mmonium@users.noreply.github.com>
---
 CAM/SetCamDofStrength.md       | 30 ++++++++++++++++++++++++++++--
 CAM/SetCamFarDof.md            |  9 ++++++---
 CAM/SetCamNearDof.md           | 10 +++++++---
 CAM/SetCamUseShallowDofMode.md | 10 +++++++---
 CAM/SetUseHiDof.md             |  4 ++++
 5 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/CAM/SetCamDofStrength.md b/CAM/SetCamDofStrength.md
index 6736b2ac7..26aa20bd8 100644
--- a/CAM/SetCamDofStrength.md
+++ b/CAM/SetCamDofStrength.md
@@ -8,8 +8,34 @@ ns: CAM
 void SET_CAM_DOF_STRENGTH(Cam cam, float dofStrength);
 ```
 
+Specifies how much the DoF effect should be applied (Set using [`SET_CAM_NEAR_DOF`](#_0x3FA4BF0A7AB7DE2C), [`SET_CAM_FAR_DOF`](#_0xEDD91296CD01AEE0), etc.)
 
 ## Parameters
-* **cam**: 
-* **dofStrength**: 
+* **cam**: The camera handle
+* **dofStrength**: Depth of Field strength (between 0.0 and 1.0)
 
+## Examples
+```lua
+CreateThread(function()
+    local camera = CreateCam("DEFAULT_SCRIPTED_FLY_CAMERA", true)
+    -- Set the cam coordinates to the player coords
+    local playerCoords = GetEntityCoords(PlayerPedId())
+    SetCamCoord(camera, playerCoords)
+    -- Render the camera we just created
+    RenderScriptCams(true)
+    -- Use a shallow depth of field
+    SetCamUseShallowDofMode(camera, true)
+    -- Set at what distance your camera should start to focus (Example: 0.7 meters)
+    SetCamNearDof(camera, 0.7)
+    -- Set at what distance your camera should stop focusing (Example: 1.3 meters)
+    SetCamFarDof(camera, 1.3)
+    -- Apply 100% of the DoF effect (The native you're reading documentation on)
+    SetCamDofStrength(camera, 1.0)
+
+    while DoesCamExist(camera) do
+        -- Use DoF effect (needs to be called every tick)
+        SetUseHiDof()
+        Citizen.Wait(0)  
+    end
+end)
+```
diff --git a/CAM/SetCamFarDof.md b/CAM/SetCamFarDof.md
index 9024df9b6..92ac86b29 100644
--- a/CAM/SetCamFarDof.md
+++ b/CAM/SetCamFarDof.md
@@ -8,8 +8,11 @@ ns: CAM
 void SET_CAM_FAR_DOF(Cam cam, float farDOF);
 ```
 
+Specifies when the camera should stop being in focus. Can be used together with [`SET_USE_HI_DOF`](#_0xA13B0222F3D94A94), [`SET_CAM_NEAR_DOF`](#_0x3FA4BF0A7AB7DE2C), [`SET_CAM_USE_SHALLOW_DOF_MODE`](#_0x16A96863A17552BB), [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897) and other DoF related natives.
 
-## Parameters
-* **cam**: 
-* **farDOF**: 
+### Usage Example
+A usage example for this native can be found in the following native documentation: [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897).
 
+## Parameters
+* **cam**: The camera handle
+* **farDOF**: Distance in in standard units
diff --git a/CAM/SetCamNearDof.md b/CAM/SetCamNearDof.md
index 626ba267d..d294712f8 100644
--- a/CAM/SetCamNearDof.md
+++ b/CAM/SetCamNearDof.md
@@ -8,8 +8,12 @@ ns: CAM
 void SET_CAM_NEAR_DOF(Cam cam, float nearDOF);
 ```
 
+Specifies when the camera should start being in focus. Can be used together with [`SET_USE_HI_DOF`](#_0xA13B0222F3D94A94), [`SET_CAM_FAR_DOF`](#_0xEDD91296CD01AEE0), [`SET_CAM_USE_SHALLOW_DOF_MODE`](#_0x16A96863A17552BB), [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897) and other DoF related natives.
 
-## Parameters
-* **cam**: 
-* **nearDOF**: 
 
+### Usage Example
+A usage example for this native can be found in the following native documentation: [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897).
+
+## Parameters
+* **cam**: The camera handle
+* **nearDOF**: Distance in in standard units
diff --git a/CAM/SetCamUseShallowDofMode.md b/CAM/SetCamUseShallowDofMode.md
index 5602e8549..3402cdf6a 100644
--- a/CAM/SetCamUseShallowDofMode.md
+++ b/CAM/SetCamUseShallowDofMode.md
@@ -8,8 +8,12 @@ ns: CAM
 void SET_CAM_USE_SHALLOW_DOF_MODE(Cam cam, BOOL toggle);
 ```
 
+Enables or disables the usage of a shallow DOF. Needs to be set to true to use [`SET_CAM_NEAR_DOF`](#_0x3FA4BF0A7AB7DE2C), [`SET_CAM_FAR_DOF`](#_0xEDD91296CD01AEE0), etc. Doesn't need to be called every tick.
 
-## Parameters
-* **cam**: 
-* **toggle**: 
 
+### Usage Example
+A usage example for this native can be found in the following native documentation: [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897).
+
+## Parameters
+* **cam**: The camera handle
+* **toggle**: Boolean if the camera should use a shallow depth of field or not
diff --git a/CAM/SetUseHiDof.md b/CAM/SetUseHiDof.md
index 434ee8381..16817e332 100644
--- a/CAM/SetUseHiDof.md
+++ b/CAM/SetUseHiDof.md
@@ -8,4 +8,8 @@ ns: CAM
 void SET_USE_HI_DOF();
 ```
 
+Needs to be called every tick to make the active camera use a high depth of field.  
+The DoF can be customized using [`SET_CAM_NEAR_DOF`](#_0x3FA4BF0A7AB7DE2C), [`SET_CAM_FAR_DOF`](#_0xEDD91296CD01AEE0), [`SET_CAM_USE_SHALLOW_DOF_MODE`](#_0x16A96863A17552BB), [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897) and other DoF related natives.
 
+### Usage Example
+A usage example for this native can be found in the following native documentation: [`SET_CAM_DOF_STRENGTH`](#_0x5EE29B4D7D5DF897).