# Projection
The core for our minimap to mainscreen projection.

Supports rotation, and zoom, and resizable client.
In the case of `TRSCamera` it also supports different pitch levels.

Projection extends the {ref}`Minimap` and {ref}`MainScreen` interfaces with
functionality to convert coordinates to & from one to the other, usually refered
to as `MM2MS` or `MS2MM`.

There's 2 systems of projection:
- MM2MS, original work done by [slacky](https://slacky.one/).
- RSCamera, a reverse engineered projection from the client itself.

It's thanks to these that we can project the following grid, in this example
{ref}`MM2MS` is being used:
```{figure} ../../images/mm2ms.png
```

Projection by itself is just a 3D space, sort of like a grid with infinite cross
sections in all axis (read {ref}`MM2MS Projector` for more information).

It's up to you to give it coordinates you want to be converted, for example:
```pascal
{$I WaspLib/osrs.simba}

begin
  while True do
  begin
    Options.GetZoomLevel(False);
    Minimap.DebugTiles();
  end;
end.
```

```{figure} ../../images/mm2ms_flat.gif
```

But you can for example, use it with a {ref}`TRSMap` heightmap data for more
advanced projections:
```pascal
{$I WaspLib/osrs.simba}

begin
  Map.Setup([ERSChunk.VARROCK]);

  while True do
  begin
    Options.GetZoomLevel(False);
    Map.DebugHeight();
  end;
end.
```

```{figure} ../../images/mm2ms_height.gif
```


- - -

## TProjection
Main record responsible for projection.


- - -

## Projection.Run
```pascal
function TProjection.Run(arr: TVector3Array; roll: Single): TPointArray;
```
Core method that will run the `TMM2MSProjector` to convert points from the
minimap to the mainscreen.

You will likely not need to use this directly and will only interact with the
`TRSMinimap` and `TRSMainScreen` extensions below.


- - -

## Projection.ProjectModel
```pascal
function TProjection.ProjectModelEx(model: TModel; minimapCoord: TVector3; heights: array [0..3] of Single; rotation, radians: Single): TPointArray;
function TProjection.ProjectModel(model: TModel; minimapCoord: TVector3; rotation, radians: Single): TPointArray;
```
Projects a model from a `Minimap Coordinate` to the `MainScreen`.

Example:
```pascal
{$I WaspLib/osrs.simba}
var
  model: TModel;
  tpa: TPointArray;
begin
  model := new TModel('path/to/my/model.obj');
  tpa := Projection.ProjectModel(Minimap.Center.ToVec3(), Minimap.CompassRadians, 0);
  ShowOnTarget(tpa);
end.
```

```{figure} ../../images/modelproject.png
```


- - -

## Projection variable
Global {ref}`TProjection` variable.

It's unlikely you need to use this directly.

You usually only need the `TRSMinimap` and `TRSMainScreen` extensions below.


- - -

## Minimap Projection Extensions
This section contains multiple extensiosn to {ref}`TRSMinimap` related to
{ref}`Projection`.


- - -

### Minimap Vectors To MainScreen
```pascal
function TRSMinimap.Vectors2MS(vectors: TVector3Array; radians: Single): TPointArray;
function TRSMinimap.Vector2MS(vector: TVector3; radians: Single): TPoint;
```
Converts a minimap `vector` or `vectors` to the mainscreen with the help of `MM2MS`.


- - -

### Minimap Points To MainScreen
```pascal
function TRSMinimap.Points2MS(points: TPointArray; radians: Single = $FFFF): TPointArray;
function TRSMinimap.Point2MS(pt: TPoint; radians: Single = $FFFF): TPoint;
function TRSMinimap.ATPA2MS(atpa: T2DPointArray; radians: Single = $FFFF): T2DPointArray; overload;
```
Converts minimap `points` to the mainscreen with the help of `MM2MS`.


- - -

### Minimap Points To MainScreen Quads
```pascal
function TRSMinimap.Vector2MSQuad(vector: TVector3; radians: Single; size: TVector2 = [1,1]; offset: TVector3 = [0,0,0]): TQuad;
function TRSMinimap.Point2MSQuad(pt: TPoint; size: TVector2 = [1,1]; radians: Single = $FFFF): TQuad;
```
Converts a minimap point `pt` or `vector` to a mainscreen `TQuad` with the help of `MM2MS`.

Example:
```pascal
while True do
begin
  quad := Minimap.Point2MSQuad(Minimap.Center);
  ShowOnTarget(quad);
end;
```


- - -

### Minimap Points To MainScreen Cuboids
```pascal
function TRSMinimap.Vector2MSCuboid(vector, size: TVector3; radians: Single; offset: TVector3 = [0,0,0]): TCuboid;
function TRSMinimap.Point2MSCuboid(pt: TPoint; size: TVector3; radians: Single = $FFFF): TCuboid;
```
Converts a minimap point `pt` or `vector` to a mainscreen `TCuboid` with the help of `MM2MS`.

Example:
```pascal
while True do
begin
  cuboid := Minimap.Point2MSCuboid(Minimap.Center, [2,2,6]);
  ShowOnTarget(cuboid);
end;
```


- - -

### Minimap.ZoomQuad
```pascal
property TRSMinimap.ZoomQuad: TQuad;
```
Returns a `TQuad` on the minimap of what's visible on the mainscreen at the current zoom level.

Example:
```pascal
{$I WaspLib/osrs.simba}

begin
  while True do
  begin
    Options.GetZoomLevel(False);
    ShowOnTarget(Minimap.ZoomQuad);
  end;
end.
```

```{figure} ../../images/zoomquad.gif
```


- - -

### Minimap.PointOnZoomQuad
```pascal
function TRSMinimap.PointOnZoomQuad(pt: TPoint): Boolean;
```
Returns True/False if a point `pt` is within our "zoom quad".
Read `Minimap.ZoomQuad` for more information.

Example:
```pascal
WriteLn Minimap.PointOnZoomQuad(pt);
```


- - -

### Minimap.RandomPointOnZoomQuad
```pascal
function TRSMinimap.RandomPointOnZoomQuad(pt: TPoint; randomness: Integer): TPoint;
```
Creates a random point within the zoom quad that is within `randomness` distance from `pt`.


- - -

### Minimap.FacePoint
```pascal
function TRSMinimap.FacePoint(pt: TPoint; randomness: Integer = 0): Boolean;
```
This method will rotate the camera so that `pt` is within the zoom rectangle without adjusting the zoom level.

Example:
```pascal
WriteLn Minimap.FacePoint([620, 100]); //keep in mind this example uses a static point, you will probably never do this.
```


- - -

### Minimap.InZoomRange
```pascal
function TRSMinimap.InZoomRangeEx(pt: TPoint; out corner: TPoint): Boolean;
function TRSMinimap.InZoomRange(pt: TPoint): Boolean;
function TRSMinimap.AnyInZoomRange(tpa: TPointArray): Boolean; overload;
```
Method used to know if a point `pt`is within reach of the Zoom rectangle without adjusting the zoom level.
Check `TRSMinimap.ZoomQuad` for information on the zoom quad.

Example:
```pascal
WriteLn Minimap.InZoomRange([620, 100]);
```


- - -

### Minimap.GetZoomToPoint
```pascal
function TRSMinimap.GetZoomToPoint(pt: TPoint; randomness: Integer = 0): Integer;
```
This function gives us a zoom level where `pt` would be visible in the
{ref}`MainScreen`.

Example:
```pascal
{$I WaspLib/osrs.simba}
var
  pt: TPoint;
begin
  pt := Minimap.GetDots(ERSDot.ITEM)[0]; //find an item dot and returns it's coodinates.
  RSMouseZoom.SetZoomLevel(Minimap.GetZoomToPoint(pt));
end.
```


- - -

### Minimap.SetZoomToPoint
```pascal
function TRSMinimap.SetZoomToPoint(pt: TPoint; randomness: Integer = 0): Boolean;
```
This function adjusts the zoom level so the point **pt** is true in
{ref}`Minimap.InZoomRange`.


- - -

### Minimap.MakePointVisible
```pascal
function TRSMinimap.MakePointVisible(p: TPoint; randomness: Integer = 0): Boolean;
```
Uses both {ref}`Minimap.SetZoomToPoint` and {ref}`Minimap.FacePoint` to make a
point visible on the {ref}`MainScreen`.


- - -

### Minimap.DebugTiles
```pascal
procedure TRSMinimap.DebugTiles(img: TImage; dots: ERSDots);
procedure TRSMinimap.DebugTiles(dots: ERSDots = [ERSDot.PLAYER..ERSDot.ITEM]); overload;
```
Simply meant for debugging purposes.
Will draw a grid of tiles on the mainscreen with the help of `MM2MS`.

You can optionally specify which minimap `ERSDot` you want to highlight.
By default all are highlighted.

Example:
```pascal
Minimap.DebugTiles();
```


- - -

## MainScreen Projection Extensions
This section contains multiple extensiosn to {ref}`TRSMainScreen` related to
{ref}`Projection`.


- - -

### MainScreen.Point2MM
```pascal
function TRSMainScreen.Point2MM(pt: TPoint; height: Integer; radians: Single): TVector3;
```
Converts a mainscreen point `pt` to a minimap `TPoint` with the help of `MM2MS`.
This is not an exact reversion of what `MM2MS` does but it's very accurate.


- - -

### MainScreen.FacePoint
```pascal
function TRSMainScreen.FacePoint(pt: TPoint; randomness: Integer = 0): Boolean; override;
```
Rotates the camera to face point `pt`.


- - -

### MainScreen.NormalizeDistance
```pascal
function TRSMainScreen.NormalizeDistance(dist: Integer): Integer;
```
Converts a distance acquired from the **fixed client* and **default zoom** to the
current mainscreen with help of {ref}`MM2MS`.

For example, say you want to create a box with the same size regardless of the
zoom level:
```pascal
{$I WaspLib/osrs.simba}

var
  b: TBox;
  dist: Integer;
begin
  while True do
  begin
    Options.GetZoomLevel(False);
    dist := MainScreen.NormalizeDistance(50);
    b := TBox.Create(MainScreen.Center, dist, dist);
    ShowOnTarget(b);
  end;
end.
```

It will look something like this:
```{figure} ../../images/normalizedist.gif
```


- - -

### MainScreen.PlayerBox
```pascal
property TRSMainScreen.PlayerBox: TBox;
```
Returns a `TBox` on the mainscreen that tightly bounds the player.

Results are cached per zoom level to avoid unnecessary recomputation.

Example:
```pascal
{$I WaspLib/osrs.simba}

begin
  while True do
  begin
    Options.GetZoomLevel(False);
    ShowOnTarget(MainScreen.PlayerBox);
  end;
end.
```
```{figure} ../../images/mm2ms_playerbox.gif
```


- - -

### MainScreen.SetHighestPitch
```pascal
function TRSMainScreen.SetHighestPitch(): Boolean;
```
Attempts to set the camera pitch to the highest possible.

Example:
```pascal
if not MainScreen.HighestPitch then
  MainScreen.SetHighestPitch();
```


- - -

### MainScreen.SetLowestPitch
```pascal
function TRSMainScreen.SetLowestPitch(): Boolean;
```
Attempts to set the camera pitch to the lowest possible.

Example:
```pascal
if MainScreen.HighestPitch then
  MainScreen.SetLowestPitch();
```