Doc reviews

articles/monogame/howto/HowTo_AsyncProgramming.md

@@ -0,0 +1,49 @@
+---
+title: How to work with Asynchronous Methods in MonoGame
+description: This topic describes how you can work with asynchronous methods in MonoGame.
+---
+
+# Working with Asynchronous Methods in MonoGame
+
+This topic describes how you can work with asynchronous methods in MonoGame.
+
+MonoGame provides many methods that operate _asynchronously_ for operations that may take longer than the desired render-cycle length.
+
+Asynchronous methods consist of four elements:
+
+* A **Begin** call that begins the asynchronous process. **Begin** methods return an [IASyncResult](http://msdn.microsoft.com/en-us/library/system.iasyncresult.aspx) object that can be used to poll for completion if a callback function is not used to detect the completion of the operation.
+* An **End** call that ends the asynchronous process and returns objects or data requested by the **Begin** call. Calling the corresponding **End** method for each **Begin** method is important to prevent deadlocks and other undesirable behavior.
+* An optional _callback_ method that is called by the system when the asynchronous operation completes. This is passed to the **Begin** call.
+* An optional, arbitrary _tracking object_ that can be supplied to **Begin** to uniquely identify a particular asynchronous request. This object is part of the _IASyncResult_ returned by **Begin**, and is also present in the callback method's _**IASyncResult**_ parameter. Because of this, it also can be used to pass arbitrary data to the callback method when the asynchronous process completes.
+
+The two most common methods of working with asynchronous methods are to check for completion by polling or by callback. This topic describes both methods.
+
+For exhaustive information about asynchronous methods, see [Asynchronous Programming Design Patterns](http://msdn.microsoft.com/library/ms228969.aspx) on MSDN.
+
+## To poll for asynchronous method completion
+
+1. Call the asynchronous **Begin** method, and save the returned _**IASyncResult**_ object to a variable that will be checked for completion.
+
+2. In your update code, check [IsCompleted](http://msdn.microsoft.com/en-us/library/system.iasyncresult.iscompleted.aspx).
+
+3. When [IsCompleted](http://msdn.microsoft.com/en-us/library/system.iasyncresult.iscompleted.aspx) is **true**, call the **End** method that corresponds to the **Begin** method called in step 1.
+
+### To use a callback to check for asynchronous method completion
+
+1. Call the asynchronous **Begin** method, passing it an [AsyncCallback](http://msdn.microsoft.com/en-us/library/system.asynccallback.aspx) method that will be called when the asynchronous process is completed.
+
+    > [AsyncCallback](http://msdn.microsoft.com/en-us/library/system.asynccallback.aspx) methods must return void, and take a single parameter: [IASyncResult](http://msdn.microsoft.com/en-us/library/system.iasyncresult.aspx).
+
+2. In the callback, call the **End** method that corresponds to the **Begin** method called in step 1.
+
+    > The **End** method typically returns any data or objects requested by the **Begin** call.
+
+## See Also
+
+[Asynchronous Programming Design Patterns](http://msdn.microsoft.com/library/ms228969.aspx)  
+
+---
+
+© 2012 Microsoft Corporation. All rights reserved.  
+
+© 2023 The MonoGame Foundation.

articles/monogame/howto/HowTo_AutomaticRotation.md

@@ -0,0 +1,20 @@
+---
+title: How to manage automatic rotation and scaling
+description: A walkthrough what is involved in figuring out if two objects collide for MonoGame!
+---
+
+# Automatic Rotation and Scaling
+
+This topic describes automatic rotation and scaling in the MonoGame Framework. Rotation and scaling are done in hardware at no performance cost to the game.
+
+If your game supports more than one display orientation, as specified by [SupportedOrientations](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.SupportedOrientations) and described with [DisplayOrientation](xref:Microsoft.Xna.Framework.DisplayOrientation), the MonoGame Framework automatically rotates and scales the game when the **OrientationChanged** event is raised.
+
+The current back buffer resolution is scaled, and can be queried by using [PreferredBackBufferWidth](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferWidth) and [PreferredBackBufferHeight](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferHeight). These values will not be the same as the nonscaled screen resolution, which can be queried by using [DisplayMode](xref:Microsoft.Xna.Framework.Graphics.GraphicsDevice.DisplayMode) or [ClientBounds](xref:Microsoft.Xna.Framework.GameWindow.ClientBounds).
+
+If you leave [SupportedOrientations](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.SupportedOrientations) set to **DisplayOrientation.Default**, orientation is automatically determined from your [PreferredBackBufferWidth](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferWidth) and [PreferredBackBufferHeight](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferHeight). If the [PreferredBackBufferWidth](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferWidth) is greater than the [PreferredBackBufferHeight](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferHeight), the game will run in the landscape orientation and automatically switch between **LandscapeLeft** and **LandscapeRight** depending on the position which the user holds the phone. To run a game in the portrait orientation, set the [PreferredBackBufferWidth](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferWidth) to a value smaller than the [PreferredBackBufferHeight](xref:Microsoft.Xna.Framework.GraphicsDeviceManager.PreferredBackBufferHeight).
+
+---
+
+© 2012 Microsoft Corporation. All rights reserved.
+
+© The MonoGame Team.

articles/monogame/howto/HowTo_CollisionDetectionOverview.md

@@ -0,0 +1,81 @@
+---
+title: How to test collisions with Bounding Volumes
+description: A walkthrough what is involved in figuring out if two objects collide for MonoGame!
+---
+
+# Bounding Volumes and Collisions
+
+Collision detection determines whether objects in a game world overlap each other.
+
+The MonoGame Framework provides several classes and methods to speed implementation of collision detection systems in games.
+
+* [Bounding Volume Classes](#bounding-volume-classes)
+* [Non-Bounding Volume Classes](#non-bounding-volume-classes)
+* [Contains and Intersects Methods](#contains-and-intersects-methods)
+* [Adding New Collision Data Structures](#adding-new-collision-data-structures)
+
+## Bounding Volume Classes
+
+The MonoGame Framework has three classes that represent three-dimensional volumes. Use a bounding volume class to approximate the volume occupied by a complex object using a volume that is less complex and faster for performing collision checking. All of the bounding volume classes support intersection and containment tests with each other and the plane and ray classes.
+
+### Bounding Sphere
+
+The [BoundingSphere Structure](xref:Microsoft.Xna.Framework.BoundingSphere) represents the space occupied by a sphere.
+
+There are several benefits of using a bounding sphere for collision detection.
+
+* Sphere to sphere checks are very fast. To check for collision between two spheres, the distance between the centers of the spheres is compared to the sum of the radii of both spheres. If the distance is less than the combined radii of both spheres, the spheres intersect.
+* The [BoundingSphere Structure](xref:Microsoft.Xna.Framework.BoundingSphere) class is compact. It stores only a vector representing its center and its radius.
+* Unlike a bounding box, a bounding sphere doesn’t need to be recreated if the model rotates. If the model being bounded rotates, the bounding sphere will still be large enough to contain it.
+* Moving a bounding sphere is inexpensive. Just add a value to the center.
+
+There is one major drawback to using the bounding sphere class for collision detection.
+
+* Unless the object being approximated is sphere shaped, the bounding sphere will have some empty space, which could result in false positive results. Long narrow objects will have the most empty space in their bounding spheres.
+
+### Bounding Box
+
+The [BoundingBox Structure](xref:Microsoft.Xna.Framework.BoundingBox) represents the space occupied by a box. The bounding box class is axis aligned. Each face of the bounding box is perpendicular to the x-axis, the y-axis, or the z-axis.
+
+There are several benefits of using the bounding box for collision detection.
+
+* The bounding box class fits rectangular shapes aligned with the axis very well. Compared to the bounding sphere class, the bounding box class provides a much tighter fit for non-rotated rectangular objects.
+* Because the bounding box class is axis aligned, you can make certain assumptions that result in collision checks between bounding boxes being quicker than a bounding box that can be rotated.
+
+There are a few drawbacks of using the bounding box for collision detection.
+
+* Rotating a bounding box causes it to no longer be axis aligned. Because of this, if you rotate a model being bounded, you will need to recreate the bounding box. Doing so can be slow, since all the points in an object are iterated through to get the bounding box. If the model has not changed orientation, you can translate the bounding box instead of recreating it.
+* If the model being bounded is not aligned to the axis, the bounding box will have some empty space. The amount of empty space will be greatest when the object is rotated 45 degrees from an axis.
+* Empty space in the bounding box can result in false positives when checking for collision.
+
+### Bounding Frustum
+
+Use a [BoundingFrustum Class](xref:Microsoft.Xna.Framework.BoundingFrustum) to create a bounding volume that corresponds to the space visible to the camera. You create a bounding frustum from the combined view and projection matrix that the camera is using currently. If the camera moves or rotates, you need to recreate the bounding frustum. The bounding frustum isn’t used to determine when two objects collide, but rather when an object intersects with the volume of space viewable by the camera. Objects that do not intersect and are not contained by the bounding frustum are not visible to the camera and don’t need to be drawn. For complex models, this can reduce the number of pixels that need to be rendered.
+
+## Non-Bounding Volume Classes
+
+### Plane
+
+The [Plane Structure](xref:Microsoft.Xna.Framework.Plane) describes a 2D plane. The plane is defined by a normal vector (perpendicular to the plane) and a point on the plane. The plane class supports intersection tests with the bounding volume classes. The plane class’s intersection test returns the tested object's position relative to the plane. The return value indicates whether the object intersects the plane. If the object does not intersect the plane, the return value indicates whether the object is on the plane’s front side or back side.
+
+### Ray
+
+The [Ray Structure](xref:Microsoft.Xna.Framework.Ray) describes a ray starting at a point in space. The ray structure supports intersection tests with the bounding volume classes. The return value of the ray intersection tests is the distance the intersection occurred at, or null if no intersection occurred.
+
+### Model
+
+In addition to the information needed to draw a model, the [Model Class](xref:Microsoft.Xna.Framework.Graphics.Model) contains bounding volumes for its parts. When a model is imported, the content pipeline calculates the bounding sphere for each of the model's parts. To check for collision between two models, you can compare the bounding spheres for one model to all of the bounding spheres of the other model.
+
+## Contains and Intersects Methods
+
+Bounding volume classes have methods to support two types of collision tests: intersection tests and containment tests. The intersects methods check whether the two objects being tested overlap in any way. As soon as the test finds that the objects do intersect, it returns without trying to determine the degree of the intersection. The contains methods determine whether the objects simply intersect or whether one of the objects is completely contained by the other. Since the intersects methods need only determine whether an intersection occurred, they tend to be faster than the contains methods.
+
+## Adding New Collision Data Structures
+
+When implementing other bounding volume classes and intersection tests, you will probably need to add a custom content pipeline processor. For example, your game might need to use convex hulls for collision detection. You could use a custom processor to determine the convex hull and then place it in the model's tag field. Then, when the model is loaded at run time, the convex hull information would be available in the model. For more information, see [Extending a Standard Content Processor](Content_Pipeline/HowTo_Extend_Processor.md).
+
+---
+
+© 2012 Microsoft Corporation. All rights reserved.  
+
+© 2023 The MonoGame Foundation.

articles/monogame/howto/HowTo_ExitNow.md

@@ -0,0 +1,66 @@
+---
+title: How to exit a Game Immediately
+description: Demonstrates how to exit a game in response to user input.
+---
+
+# Exiting a Game Immediately
+
+Demonstrates how to exit a game in response to user input.
+
+## Exiting a Game Without Finishing the Current Update
+
+> **Note* some platforms react differently to **Game.Exit**, so be sure to test on a device!
+
+### To exit the game loop without running any remaining code in the update handler
+
+1. Derive a class from [Game](xref:Microsoft.Xna.Framework.Game).
+
+2. Create a method that checks [KeyboardState.IsKeyDown](xref:Microsoft.Xna.Framework.Input.KeyboardState) for the state of the **ESC** key.
+
+3. If the ESC key has been pressed, call [Game.Exit](xref:Microsoft.Xna.Framework.Game.Exit) and return **true**.
+
+    ```csharp
+    bool checkExitKey(KeyboardState keyboardState, GamePadState gamePadState)
+    {
+        // Check to see whether ESC was pressed on the keyboard 
+        // or BACK was pressed on the controller.
+        if (keyboardState.IsKeyDown(Keys.Escape) ||
+            gamePadState.Buttons.Back == ButtonState.Pressed)
+        {
+            Exit();
+            return true;
+        }
+        return false;
+    }
+    ```
+
+4. Call the method in **Game.Update**, and return from **Update** if the method returned **true**.
+
+    ```csharp
+    GamePadState gamePadState = GamePad.GetState(PlayerIndex.One);
+    KeyboardState keyboardState = Keyboard.GetState();
+
+    // Check to see if the user has exited
+    if (checkExitKey(keyboardState, gamePadState))
+    {
+        base.Update(gameTime);
+        return;
+    }
+    ```
+
+5. Create a method to handle the **Game.Exiting** event.
+
+    The **Exiting** event is issued at the end of the tick in which [Game.Exit](xref:Microsoft.Xna.Framework.Game.Exit) is called.
+
+    ```csharp
+    void Game1_Exiting(object sender, EventArgs e)
+    {
+        // Add any code that must execute before the game ends.
+    }
+    ```
+
+---
+
+© 2012 Microsoft Corporation. All rights reserved.  
+
+© 2023 The MonoGame Foundation.