diff --git a/articles/getting_to_know/howto/audio/HowTo_ChangePitchAndVolume.md b/articles/getting_to_know/howto/audio/HowTo_ChangePitchAndVolume.md index f70be56f..788b0758 100644 --- a/articles/getting_to_know/howto/audio/HowTo_ChangePitchAndVolume.md +++ b/articles/getting_to_know/howto/audio/HowTo_ChangePitchAndVolume.md @@ -125,7 +125,7 @@ But you can use your own if you wish. Demonstrates how to load a wav file through a file stream. -* [Creating and Playing Sounds](../../whatis/WhatIs_Audio.md) +* [Creating and Playing Sounds](../../whatis/audio/index.md) Provides overviews about audio technology, and presents predefined scenarios to demonstrate how to use audio. diff --git a/articles/getting_to_know/howto/audio/HowTo_Microphone.md b/articles/getting_to_know/howto/audio/HowTo_Microphone.md index 04d91722..63139b15 100644 --- a/articles/getting_to_know/howto/audio/HowTo_Microphone.md +++ b/articles/getting_to_know/howto/audio/HowTo_Microphone.md @@ -29,7 +29,7 @@ Also, you can use the **BufferReady** event handler of the [Microphone](xref:Mic ## See Also -* [Creating and Playing Sounds](../../whatis/WhatIs_Audio.md) +* [Creating and Playing Sounds](../../whatis/audio/index.md) Provides overviews about audio technology, and presents predefined scenarios to demonstrate how to use audio. diff --git a/articles/getting_to_know/howto/audio/HowTo_PlayASong.md b/articles/getting_to_know/howto/audio/HowTo_PlayASong.md index e9596129..5875759d 100644 --- a/articles/getting_to_know/howto/audio/HowTo_PlayASong.md +++ b/articles/getting_to_know/howto/audio/HowTo_PlayASong.md @@ -61,7 +61,7 @@ The following demonstrates how to play a song from the media file in the content ## See Also -* [Media Overview](../../whatis/WhatIs_Audio.md) +* [Media Overview](../../whatis/audio/index.md) Provides a high-level overview about the capabilities—such as playing music and video and accessing pictures—of the Media API in MonoGame. diff --git a/articles/getting_to_know/howto/audio/toc.yml b/articles/getting_to_know/howto/audio/toc.yml deleted file mode 100644 index 68bd1706..00000000 --- a/articles/getting_to_know/howto/audio/toc.yml +++ /dev/null @@ -1,18 +0,0 @@ -- name: <- Back - href: ../index.md -- name: Introduction - href: index.md -- name: How to Play a sound - href: HowTo_PlayASound.md -- name: How to Loop a sound - href: HowTo_LoopASound.md -- name: How to Play a song - href: HowTo_PlayASong.md -- name: How to Change Pitch And Volume - href: HowTo_ChangePitchAndVolume.md -- name: How to Stream Data From a Wav - href: HowTo_StreamDataFromWav.md -- name: Microphone basics - href: HowTo_Microphone.md -- name: How to Record the Microphone - href: HowTo_Record_Microphone.md \ No newline at end of file diff --git a/articles/getting_to_know/howto/content_pipeline/toc.yml b/articles/getting_to_know/howto/content_pipeline/toc.yml deleted file mode 100644 index bd892b82..00000000 --- a/articles/getting_to_know/howto/content_pipeline/toc.yml +++ /dev/null @@ -1,2 +0,0 @@ -- name: <- Back - href: ../index.md \ No newline at end of file diff --git a/articles/getting_to_know/howto/graphics/toc.yml b/articles/getting_to_know/howto/graphics/toc.yml deleted file mode 100644 index bd892b82..00000000 --- a/articles/getting_to_know/howto/graphics/toc.yml +++ /dev/null @@ -1,2 +0,0 @@ -- name: <- Back - href: ../index.md \ No newline at end of file diff --git a/articles/getting_to_know/howto/input/toc.yml b/articles/getting_to_know/howto/input/toc.yml deleted file mode 100644 index bd892b82..00000000 --- a/articles/getting_to_know/howto/input/toc.yml +++ /dev/null @@ -1,2 +0,0 @@ -- name: <- Back - href: ../index.md \ No newline at end of file diff --git a/articles/getting_to_know/howto/toc.yml b/articles/getting_to_know/howto/toc.yml deleted file mode 100644 index 0d05dd14..00000000 --- a/articles/getting_to_know/howto/toc.yml +++ /dev/null @@ -1,12 +0,0 @@ -- name: <- Back - href: ../index.md -- name: Introduction - href: index.md -- name: Audio - href: audio/ -- name: Content Pipeline - href: content_pipeline/ -- name: Graphics - href: graphics/ -- name: Input - href: input/ \ No newline at end of file diff --git a/articles/getting_to_know/toc.yml b/articles/getting_to_know/toc.yml deleted file mode 100644 index d0f3c652..00000000 --- a/articles/getting_to_know/toc.yml +++ /dev/null @@ -1,30 +0,0 @@ -- name: Introduction - href: index.md -- name: What is - href: whatis/ - items: - - name: Audio - href: whatis/WhatIs_Audio.md - - name: Content Pipeline - href: whatis/content_pipeline/ - - name: Graphics - href: whatis/graphics/ - - name: The Game Loop - href: whatis/WhatIs_TheGameLoop.md - - name: Input - href: whatis/WhatIs_Input.md - - name: Vector / Matrix / Quaternions - href: whatis/WhatIs_VectorMatrixQuat.md - - name: MonoGame Class Library - href: whatis/WhatIs_MonoGame_Class_Library.md -- name: How To - href: howto/ - items: - - name: Audio - href: howto/audio/ - - name: Content Pipeline - href: howto/content_pipeline/ - - name: Graphics - href: howto/graphics/ - - name: Input - href: howto/input/ diff --git a/articles/getting_to_know/whatis/WhatIs_Audio.md b/articles/getting_to_know/whatis/audio/index.md similarity index 89% rename from articles/getting_to_know/whatis/WhatIs_Audio.md rename to articles/getting_to_know/whatis/audio/index.md index 81feb5a0..3ca201f5 100644 --- a/articles/getting_to_know/whatis/WhatIs_Audio.md +++ b/articles/getting_to_know/whatis/audio/index.md @@ -1,68 +1,68 @@ ---- -title: Sounds Overview -description: An overview of how the MonoGame Framework provides audio playback through several core audio classes. -requireMSLicense: true ---- - -If your game is to use a few sound files, then the [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect), [SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance), and [DynamicSoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) classes will provide everything you need to play and stream audio during gameplay. - -## Simple Audio Playback - -The simplest way to play sounds for background music or sound effects is to use [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) and [SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance). Source audio files are added like any other game asset to the project. For example code, see [Playing a Sound](../howto/audio/HowTo_PlayASound.md), [Looping a Sound](../howto/audio/HowTo_LoopASound.md), and [Adjusting Pitch and Volume](../howto/audio/HowTo_ChangePitchAndVolume.md). For background music, see [Playing a Song](../howto/audio/HowTo_PlayASong.md). - -## Accessing the Audio Buffer - -Developers can use [DynamicSoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) for direct access to an audio buffer. By accessing the audio buffer, developers can manipulate sound, break up large sound files into smaller data chunks, and stream sound. For example code, see [Streaming Data from a WAV File](../howto/audio/HowTo_StreamDataFromWav.md). - -## 3D Audio - -The [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) class provides the ability to place audio in a 3D space. By creating [AudioEmitter](xref:Microsoft.Xna.Framework.Audio.AudioEmitter) and [AudioListener](xref:Microsoft.Xna.Framework.Audio.AudioListener) objects, the API can position a sound in 3D, and can change the 3D position of a sound during playback. Once you create and initialize [AudioEmitter](xref:Microsoft.Xna.Framework.Audio.AudioEmitter) and [AudioListener](xref:Microsoft.Xna.Framework.Audio.AudioListener), call [SoundEffectInstance.Apply3D](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance). - -## Audio Constraints - -When working with multiple platforms using MonoGame, there are a few constraints around audio that you will need to keep in mind and cater for, namely: - -* Mobile platforms have a maximum of 32 sounds playing simultaneously. -* Desktop platforms have a maximum of 256 sounds playing simultaneously. -* Consoles and other platforms have their own constraints, please look at the console sdk documentation for more information, - -> [!IMPORTANT] -> An [InstancePlayLimitException](xref:Microsoft.Xna.Framework.Audio.InstancePlayLimitException) exception is thrown if this limit is exceeded. - -## Audio Buffer Format - -The `byte[]` buffer format used as a parameter for the [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) constructor, [Microphone.GetData](xref:Microsoft.Xna.Framework.Audio.Microphone) method, and [DynamicSoundEffectInstance.SubmitBuffer](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) method is PCM wave data. Additionally, the PCM format is interleaved and in little-endian. - -The audio format has the following constraints: - -* The audio channels can be mono (1) or stereo (2). -* The PCM wave file must have 16-bits per sample. -* The sample rate must be between 8,000 Hz and 48,000 Hz. -* The interleaving for stereo data is left channel to right channel. - -## Songs as Background Music - -Access to the media library, combined with the ability to use playlists, allows games to create interesting background scores that can change with gameplay. Songs can be played directly from the media library, or can be imported by using the Content Pipeline. For more information, see [Playing a Song](../howto/audio/HowTo_PlayASong.md). - -## Concepts - -> [!IMPORTANT] -> How to articles to follow. - -## Reference - -* [SoundEffect Class](xref:Microsoft.Xna.Framework.Audio.SoundEffect) - - Provides a loaded sound resource. - -* [SoundEffectInstance Class](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance) - - Provides a single playing, paused, or stopped instance of a [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) sound. - -* [DynamicSoundEffectInstance Class](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) - - Provides properties, methods, and events for play back of the audio buffer. - -* [Song Class](xref:Microsoft.Xna.Framework.Media.Song) - - Provides access to a song in the song library. +--- +title: Sounds Overview +description: An overview of how the MonoGame Framework provides audio playback through several core audio classes. +requireMSLicense: true +--- + +If your game is to use a few sound files, then the [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect), [SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance), and [DynamicSoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) classes will provide everything you need to play and stream audio during gameplay. + +## Simple Audio Playback + +The simplest way to play sounds for background music or sound effects is to use [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) and [SoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance). Source audio files are added like any other game asset to the project. For example code, see [Playing a Sound](../../howto/audio/HowTo_PlayASound.md), [Looping a Sound](../../howto/audio/HowTo_LoopASound.md), and [Adjusting Pitch and Volume](../../howto/audio/HowTo_ChangePitchAndVolume.md). For background music, see [Playing a Song](../../howto/audio/HowTo_PlayASong.md). + +## Accessing the Audio Buffer + +Developers can use [DynamicSoundEffectInstance](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) for direct access to an audio buffer. By accessing the audio buffer, developers can manipulate sound, break up large sound files into smaller data chunks, and stream sound. For example code, see [Streaming Data from a WAV File](../../howto/audio/HowTo_StreamDataFromWav.md). + +## 3D Audio + +The [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) class provides the ability to place audio in a 3D space. By creating [AudioEmitter](xref:Microsoft.Xna.Framework.Audio.AudioEmitter) and [AudioListener](xref:Microsoft.Xna.Framework.Audio.AudioListener) objects, the API can position a sound in 3D, and can change the 3D position of a sound during playback. Once you create and initialize [AudioEmitter](xref:Microsoft.Xna.Framework.Audio.AudioEmitter) and [AudioListener](xref:Microsoft.Xna.Framework.Audio.AudioListener), call [SoundEffectInstance.Apply3D](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance). + +## Audio Constraints + +When working with multiple platforms using MonoGame, there are a few constraints around audio that you will need to keep in mind and cater for, namely: + +* Mobile platforms have a maximum of 32 sounds playing simultaneously. +* Desktop platforms have a maximum of 256 sounds playing simultaneously. +* Consoles and other platforms have their own constraints, please look at the console sdk documentation for more information, + +> [!IMPORTANT] +> An [InstancePlayLimitException](xref:Microsoft.Xna.Framework.Audio.InstancePlayLimitException) exception is thrown if this limit is exceeded. + +## Audio Buffer Format + +The `byte[]` buffer format used as a parameter for the [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) constructor, [Microphone.GetData](xref:Microsoft.Xna.Framework.Audio.Microphone) method, and [DynamicSoundEffectInstance.SubmitBuffer](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) method is PCM wave data. Additionally, the PCM format is interleaved and in little-endian. + +The audio format has the following constraints: + +* The audio channels can be mono (1) or stereo (2). +* The PCM wave file must have 16-bits per sample. +* The sample rate must be between 8,000 Hz and 48,000 Hz. +* The interleaving for stereo data is left channel to right channel. + +## Songs as Background Music + +Access to the media library, combined with the ability to use playlists, allows games to create interesting background scores that can change with gameplay. Songs can be played directly from the media library, or can be imported by using the Content Pipeline. For more information, see [Playing a Song](../../howto/audio/HowTo_PlayASong.md). + +## Concepts + +> [!IMPORTANT] +> How to articles to follow. + +## Reference + +* [SoundEffect Class](xref:Microsoft.Xna.Framework.Audio.SoundEffect) + + Provides a loaded sound resource. + +* [SoundEffectInstance Class](xref:Microsoft.Xna.Framework.Audio.SoundEffectInstance) + + Provides a single playing, paused, or stopped instance of a [SoundEffect](xref:Microsoft.Xna.Framework.Audio.SoundEffect) sound. + +* [DynamicSoundEffectInstance Class](xref:Microsoft.Xna.Framework.Audio.DynamicSoundEffectInstance) + + Provides properties, methods, and events for play back of the audio buffer. + +* [Song Class](xref:Microsoft.Xna.Framework.Media.Song) + + Provides access to a song in the song library. diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md b/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md index 45aa9f78..64b92f47 100644 --- a/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md @@ -42,7 +42,7 @@ The format of data in the .XNB file is tightly coupled to the MonoGame Framework ### Runtime Components -Runtime components of the Content Pipeline support loading and using the transformed game asset by your MonoGame game. These components use the [MonoGame library](../WhatIs_MonoGame_Class_Library.md), which can be extended to create custom components. +Runtime components of the Content Pipeline support loading and using the transformed game asset by your MonoGame game. These components use the [MonoGame library](../monogame_class_library/index.md), which can be extended to create custom components. ## Content Loader diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md b/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md index 6aed43d8..eba8b8ff 100644 --- a/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md @@ -58,7 +58,7 @@ When you include an art asset file in your MonoGame solution's content project ( The run-time components of the MonoGame Content Pipeline support the loading and use of the transformed art asset by your MonoGame. -These run-time components make use of the [MonoGame Framework Class Library](../WhatIs_MonoGame_Class_Library.md), which can be extended to create custom Content Pipeline run-time components. +These run-time components make use of the [MonoGame Framework Class Library](../monogame_class_library/index.md), which can be extended to create custom Content Pipeline run-time components. ## See Also diff --git a/articles/getting_to_know/whatis/content_pipeline/toc.yml b/articles/getting_to_know/whatis/content_pipeline/toc.yml deleted file mode 100644 index 5f65dc64..00000000 --- a/articles/getting_to_know/whatis/content_pipeline/toc.yml +++ /dev/null @@ -1,12 +0,0 @@ -- name: <- Back - href: ../index.md -- name: What is Content? - href: CP_Overview.md -- name: Loading Content - href: ../../howto/content_pipeline/HowTo_GameContent_Add.md -- name: Content Pipeline Architecture - href: CP_Architecture.md -- name: MonoGame Content Pipeline Class Library - href: CP_Class_Library.md -- name: Content Pipeline Document Object Model - href: CP_DOM.md \ No newline at end of file diff --git a/articles/getting_to_know/whatis/WhatIs_TheGameLoop.md b/articles/getting_to_know/whatis/game_loop/index.md similarity index 98% rename from articles/getting_to_know/whatis/WhatIs_TheGameLoop.md rename to articles/getting_to_know/whatis/game_loop/index.md index 0b6c162b..a006bacf 100644 --- a/articles/getting_to_know/whatis/WhatIs_TheGameLoop.md +++ b/articles/getting_to_know/whatis/game_loop/index.md @@ -1,96 +1,96 @@ ---- -title: What is the Game Loop -description: There is a specific order of operations related to how a MonoGame project runs. -requireMSLicense: true ---- - -The MonoGame Framework [Game](xref:Microsoft.Xna.Framework.Game) class implements a game loop, which provides not only the window which displays your game, but also provides overloadable methods that your game implements to facilitate communication between your game and the operating system. This topic provides an overview of the basic functionality provided by the game loop. - -* [Making a New Game](#making-a-new-game) -* [Game Loop Timing](#game-loop-timing) -* [Game Components](#game-components) -* [Game Services](#game-services) -* [Game Components Consuming Game Services](#game-components-consuming-game-services) - -![The MonoGame "Game" Loop](./images/MGExecution.png) - -## Making a New Game - -The first step in creating a new game is to make a class that derives from [Game](xref:Microsoft.Xna.Framework.Game). The new class needs to override the following methods: - -* Initialize - which is the method is responsible for game setup before the first frame of the game. -* Update - which is the method is responsible for handling game logic. -* Draw - which is the method responsible for drawing content to the screen. - -## Game Loop Timing - -A [Game](xref:Microsoft.Xna.Framework.Game) is either fixed step or variable step, defaulting to fixed step. The type of step determines how often [Update](xref:Microsoft.Xna.Framework.Game) will be called and affects how you need to represent time-based procedures such as movement and animation. - -### Fixed-Step Game Loops - -A fixed-step [Game](xref:Microsoft.Xna.Framework.Game) tries to call its **Update** method on the fixed interval specified in **TargetElapsedTime**. Setting **Game.IsFixedTimeStep** to **true** causes a [Game](xref:Microsoft.Xna.Framework.Game) to use a fixed-step game loop. A new MonoGame project uses a fixed-step game loop with a default **TargetElapsedTime** of 1/60th of a second. - -In a fixed-step game loop, [Game](xref:Microsoft.Xna.Framework.Game) calls **Update** once the **TargetElapsedTime** has elapsed. After **Update** is called, if it is not time to call **Update** again, the [Game](xref:Microsoft.Xna.Framework.Game) calls **Draw**. After **Draw** is called, if it is not time to call **Update** again, [Game](xref:Microsoft.Xna.Framework.Game) idles until it is time to call **UpdateS**. - -If **Update** takes too long to process, [Game](xref:Microsoft.Xna.Framework.Game) sets **IsRunningSlowly** to **true** and calls **Update** again, without calling **Draw** in between. When an update runs longer than the **TargetElapsedTime**, [Game](xref:Microsoft.Xna.Framework.Game) responds by calling **Update** extra times and dropping the frames associated with those updates to catch up. This ensures that **Update** will have been called the expected number of times when the game loop catches up from a slowdown. You can check the value of **IsRunningSlowly** in your **Update** if you want to detect dropped frames and shorten your **Update** processing to compensate. You can reset the elapsed times by calling **ResetElapsedTime**. - -When your game pauses in the debugger, [Game](xref:Microsoft.Xna.Framework.Game) will not make extra calls to **Update** when the game resumes. - -### Variable-Step Game Loops - -A variable-step game calls its **Update** and **Draw** methods in a continuous loop without regard to the [TargetElapsedTime](xref:Microsoft.Xna.Framework.Game). Setting [Game.IsFixedTimeStep](xref:Microsoft.Xna.Framework.Game) to **false** causes a [Game](xref:Microsoft.Xna.Framework.Game) to use a variable-step game loop. - -### Animation and Timing - -For operations that require precise timing, such as animation, the type of game loop your game uses (fixed-step or variable-step) is important. - -Using a fixed step allows game logic to use the **TargetElapsedTime** as its basic unit of time and assume that **Update** will be called at that interval. Using a variable step requires the game logic and animation code to be based on **ElapsedGameTime** to ensure smooth gameplay. Because the **Update** method is called immediately after the previous frame is drawn, the time between calls to **Update** can vary. Without taking the time between calls into account, the game would seem to speed up and slow down. The time elapsed between calls to the **Update** method is available in the **Update** method's _gameTime_ parameter. You can reset the elapsed times by calling **ResetElapsedTime**. - -When using a variable-step game loop, you should express rates—such as the distance a sprite moves—in game units per millisecond (ms). The amount a sprite moves in any given update can then be calculated as the rate of the sprite times the elapsed time. Using this approach to calculate the distance the sprite moved ensures that the sprite will move consistently if the speed of the game or computer varies. - -## Game Components - -Game components provide a modular way of adding functionality to a game. You create a game component by deriving the new component either from the - -* [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) class, or -* [DrawableGameComponent](xref:Microsoft.Xna.Framework.DrawableGameComponent) class if the component loads and draws graphics content. - -You then add game logic and rendering code to the game component by overriding the following methods: - -* **GameComponent.Update** -* **GameComponent.Initialize** - -Additionally, if you derive from the `DrawableGameComponent` class, you will additionally be able to override: - -* **DrawableGameComponent.Draw** - -A game component is registered with a game by passing the component to `Game.Components.Add`. A registered component will have its `initialize`, `update`, and `draw` methods called from the `Game.Initialize`, `Game.Update`, and `Game.Draw` methods, respectively. - -## Game Services - -Game services are a mechanism for maintaining loose coupling between objects that need to interact with each other. Services work through a mediator—in this case, [Game.Services](xref:Microsoft.Xna.Framework.Game.Services). Service providers register with [Game.Services](xref:Microsoft.Xna.Framework.Game.Services), and service consumers request services from [Game.Services](xref:Microsoft.Xna.Framework.Game.Services). This arrangement allows an object that requires a service to request the service without knowing the name of the service provider. - -Game services are defined by a unique interface. A class specifies the services it provides by implementing interfaces and registering the services with [Game.Services](xref:Microsoft.Xna.Framework.Game.Services). A service is registered by calling **Game.Services.AddService** specifying the type of service being implemented and a reference to the object providing the service. For example, to register an object that provides a service represented by the interface IMyService, you would use the following code. - -```csharp - Services.AddService( typeof( IMyService ), myobject ); -``` - -Once a service is registered, the object providing the service can be retrieved by **Game.Services.GetService** and specifying the desired service. For example, to retrieve [IGraphicsDeviceService](xref:Microsoft.Xna.Framework.Graphics.IGraphicsDeviceService), you would use the following code. - -```csharp - IGraphicsDeviceService graphicsservice = (IGraphicsDeviceService)Services.GetService( typeof(IGraphicsDeviceService) ); -``` - -## Game Components Consuming Game Services - -The [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) class provides the [Game](xref:Microsoft.Xna.Framework.GameComponent.Game) property so a [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) can determine what [Game](xref:Microsoft.Xna.Framework.Game) it is attached to. With the [Game](xref:Microsoft.Xna.Framework.GameComponent.Game) property, a [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) can call [Game.Services.GetService](xref:Microsoft.Xna.Framework.GameServiceContainer) to find a provider of a particular service. For example, a [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) would find the [IGraphicsDeviceService](xref:Microsoft.Xna.Framework.Graphics.IGraphicsDeviceService) provider by using the following code. - -```csharp - IGraphicsDeviceService graphicsservice = (IGraphicsDeviceService)Game.Services.GetService( typeof( IGraphicsDeviceService ) ); -``` - -## Related articles - -> [!IMPORTANT] -> How to articles to follow. +--- +title: What is the Game Loop +description: There is a specific order of operations related to how a MonoGame project runs. +requireMSLicense: true +--- + +The MonoGame Framework [Game](xref:Microsoft.Xna.Framework.Game) class implements a game loop, which provides not only the window which displays your game, but also provides overloadable methods that your game implements to facilitate communication between your game and the operating system. This topic provides an overview of the basic functionality provided by the game loop. + +* [Making a New Game](#making-a-new-game) +* [Game Loop Timing](#game-loop-timing) +* [Game Components](#game-components) +* [Game Services](#game-services) +* [Game Components Consuming Game Services](#game-components-consuming-game-services) + +![The MonoGame "Game" Loop](../images/MGExecution.png) + +## Making a New Game + +The first step in creating a new game is to make a class that derives from [Game](xref:Microsoft.Xna.Framework.Game). The new class needs to override the following methods: + +* Initialize - which is the method is responsible for game setup before the first frame of the game. +* Update - which is the method is responsible for handling game logic. +* Draw - which is the method responsible for drawing content to the screen. + +## Game Loop Timing + +A [Game](xref:Microsoft.Xna.Framework.Game) is either fixed step or variable step, defaulting to fixed step. The type of step determines how often [Update](xref:Microsoft.Xna.Framework.Game) will be called and affects how you need to represent time-based procedures such as movement and animation. + +### Fixed-Step Game Loops + +A fixed-step [Game](xref:Microsoft.Xna.Framework.Game) tries to call its **Update** method on the fixed interval specified in **TargetElapsedTime**. Setting **Game.IsFixedTimeStep** to **true** causes a [Game](xref:Microsoft.Xna.Framework.Game) to use a fixed-step game loop. A new MonoGame project uses a fixed-step game loop with a default **TargetElapsedTime** of 1/60th of a second. + +In a fixed-step game loop, [Game](xref:Microsoft.Xna.Framework.Game) calls **Update** once the **TargetElapsedTime** has elapsed. After **Update** is called, if it is not time to call **Update** again, the [Game](xref:Microsoft.Xna.Framework.Game) calls **Draw**. After **Draw** is called, if it is not time to call **Update** again, [Game](xref:Microsoft.Xna.Framework.Game) idles until it is time to call **UpdateS**. + +If **Update** takes too long to process, [Game](xref:Microsoft.Xna.Framework.Game) sets **IsRunningSlowly** to **true** and calls **Update** again, without calling **Draw** in between. When an update runs longer than the **TargetElapsedTime**, [Game](xref:Microsoft.Xna.Framework.Game) responds by calling **Update** extra times and dropping the frames associated with those updates to catch up. This ensures that **Update** will have been called the expected number of times when the game loop catches up from a slowdown. You can check the value of **IsRunningSlowly** in your **Update** if you want to detect dropped frames and shorten your **Update** processing to compensate. You can reset the elapsed times by calling **ResetElapsedTime**. + +When your game pauses in the debugger, [Game](xref:Microsoft.Xna.Framework.Game) will not make extra calls to **Update** when the game resumes. + +### Variable-Step Game Loops + +A variable-step game calls its **Update** and **Draw** methods in a continuous loop without regard to the [TargetElapsedTime](xref:Microsoft.Xna.Framework.Game). Setting [Game.IsFixedTimeStep](xref:Microsoft.Xna.Framework.Game) to **false** causes a [Game](xref:Microsoft.Xna.Framework.Game) to use a variable-step game loop. + +### Animation and Timing + +For operations that require precise timing, such as animation, the type of game loop your game uses (fixed-step or variable-step) is important. + +Using a fixed step allows game logic to use the **TargetElapsedTime** as its basic unit of time and assume that **Update** will be called at that interval. Using a variable step requires the game logic and animation code to be based on **ElapsedGameTime** to ensure smooth gameplay. Because the **Update** method is called immediately after the previous frame is drawn, the time between calls to **Update** can vary. Without taking the time between calls into account, the game would seem to speed up and slow down. The time elapsed between calls to the **Update** method is available in the **Update** method's _gameTime_ parameter. You can reset the elapsed times by calling **ResetElapsedTime**. + +When using a variable-step game loop, you should express rates—such as the distance a sprite moves—in game units per millisecond (ms). The amount a sprite moves in any given update can then be calculated as the rate of the sprite times the elapsed time. Using this approach to calculate the distance the sprite moved ensures that the sprite will move consistently if the speed of the game or computer varies. + +## Game Components + +Game components provide a modular way of adding functionality to a game. You create a game component by deriving the new component either from the + +* [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) class, or +* [DrawableGameComponent](xref:Microsoft.Xna.Framework.DrawableGameComponent) class if the component loads and draws graphics content. + +You then add game logic and rendering code to the game component by overriding the following methods: + +* **GameComponent.Update** +* **GameComponent.Initialize** + +Additionally, if you derive from the `DrawableGameComponent` class, you will additionally be able to override: + +* **DrawableGameComponent.Draw** + +A game component is registered with a game by passing the component to `Game.Components.Add`. A registered component will have its `initialize`, `update`, and `draw` methods called from the `Game.Initialize`, `Game.Update`, and `Game.Draw` methods, respectively. + +## Game Services + +Game services are a mechanism for maintaining loose coupling between objects that need to interact with each other. Services work through a mediator—in this case, [Game.Services](xref:Microsoft.Xna.Framework.Game.Services). Service providers register with [Game.Services](xref:Microsoft.Xna.Framework.Game.Services), and service consumers request services from [Game.Services](xref:Microsoft.Xna.Framework.Game.Services). This arrangement allows an object that requires a service to request the service without knowing the name of the service provider. + +Game services are defined by a unique interface. A class specifies the services it provides by implementing interfaces and registering the services with [Game.Services](xref:Microsoft.Xna.Framework.Game.Services). A service is registered by calling **Game.Services.AddService** specifying the type of service being implemented and a reference to the object providing the service. For example, to register an object that provides a service represented by the interface IMyService, you would use the following code. + +```csharp + Services.AddService( typeof( IMyService ), myobject ); +``` + +Once a service is registered, the object providing the service can be retrieved by **Game.Services.GetService** and specifying the desired service. For example, to retrieve [IGraphicsDeviceService](xref:Microsoft.Xna.Framework.Graphics.IGraphicsDeviceService), you would use the following code. + +```csharp + IGraphicsDeviceService graphicsservice = (IGraphicsDeviceService)Services.GetService( typeof(IGraphicsDeviceService) ); +``` + +## Game Components Consuming Game Services + +The [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) class provides the [Game](xref:Microsoft.Xna.Framework.GameComponent.Game) property so a [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) can determine what [Game](xref:Microsoft.Xna.Framework.Game) it is attached to. With the [Game](xref:Microsoft.Xna.Framework.GameComponent.Game) property, a [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) can call [Game.Services.GetService](xref:Microsoft.Xna.Framework.GameServiceContainer) to find a provider of a particular service. For example, a [GameComponent](xref:Microsoft.Xna.Framework.GameComponent) would find the [IGraphicsDeviceService](xref:Microsoft.Xna.Framework.Graphics.IGraphicsDeviceService) provider by using the following code. + +```csharp + IGraphicsDeviceService graphicsservice = (IGraphicsDeviceService)Game.Services.GetService( typeof( IGraphicsDeviceService ) ); +``` + +## Related articles + +> [!IMPORTANT] +> How to articles to follow. diff --git a/articles/getting_to_know/whatis/graphics/toc.yml b/articles/getting_to_know/whatis/graphics/toc.yml deleted file mode 100644 index bd892b82..00000000 --- a/articles/getting_to_know/whatis/graphics/toc.yml +++ /dev/null @@ -1,2 +0,0 @@ -- name: <- Back - href: ../index.md \ No newline at end of file diff --git a/articles/getting_to_know/whatis/index.md b/articles/getting_to_know/whatis/index.md index a8bf67c4..fe31a237 100644 --- a/articles/getting_to_know/whatis/index.md +++ b/articles/getting_to_know/whatis/index.md @@ -35,19 +35,19 @@ Due the complexity of the Content and Graphics pipelines, the information is bro This section details some general aspects of the operation of a MonoGame Framework game. -* [What Is Audio?](WhatIs_Audio.md) +* [What Is Audio?](./audio/index.md) An overview of how the MonoGame Framework provides audio playback through several core audio classes. -* [What Is Input?](WhatIs_Input.md) +* [What Is Input?](./input/index.md) An overview of how the MonoGame Framework provides input management for games. -* [What Is the GameLoop?](WhatIs_TheGameLoop.md) +* [What Is the GameLoop?](./game_loop/index.md) A viewport is a 2D rectangle that defines the size of the rendering surface onto which a 3D scene is projected. -* [What are Vectors, Matrices, and Quaternions?](WhatIs_VectorMatrixQuat.md) +* [What are Vectors, Matrices, and Quaternions?](./vector_matrix_quat/index.md) Presents an overview of the math-related functionality provided by the MonoGame Framework. @@ -55,6 +55,6 @@ This section details some general aspects of the operation of a MonoGame Framewo ### References -* [What Is MonoGame Class Library](WhatIs_MonoGame_Class_Library.md) +* [What Is MonoGame Class Library](./monogame_class_library/index.md) An overview of the MonoGame Class Library reference, containing all the API calls available to the MonoGame Framework. diff --git a/articles/getting_to_know/whatis/WhatIs_Input.md b/articles/getting_to_know/whatis/input/index.md similarity index 98% rename from articles/getting_to_know/whatis/WhatIs_Input.md rename to articles/getting_to_know/whatis/input/index.md index b5e76499..9f8a97c6 100644 --- a/articles/getting_to_know/whatis/WhatIs_Input.md +++ b/articles/getting_to_know/whatis/input/index.md @@ -1,20 +1,20 @@ ---- -title: Overview of User Input and Input Devices -description: Input is a general term referring to the process of receiving actions from the user. -requireMSLicense: true ---- - -Input is a general term referring to the process of receiving actions from the user. In MonoGame, the [Microsoft.Xna.Framework.Input](xref:Microsoft.Xna.Framework.Input) namespace provides support for most input devices. - -Methods related to input devices unavailable on the platform your game is running on are always available to your code. For example, you can access all [GamePad](xref:Microsoft.Xna.Framework.Input.GamePad) methods on Mobile, but they will not return valid information (unless a GamePad is connected). Although using these methods will not cause exceptions or build errors in your code, they will silently fail when run. - -Physical keyboards may or may not be present on mobile devices; you should not rely on the presence of a physical keyboard. For text input, you should use a software input panel (SIP), which will work on all devices, including those with physical keyboards. - -If the mobile device does have access to a physical keyboard, the same methods used for keyboards on desktop can be used, given a few caveats. - -For multi-touch devices, you can use the raw touch data provided by the [TouchPanel](xref:Microsoft.Xna.Framework.Input.Touch.TouchPanel) class, but you can also use MonoGame's support for predefined gestures if your input fits one of the supported gesture types. For information about working with raw multi-touch input, see [Working with Touch Input](). For information about gesture support, see [Detecting Gestures on a Multi-touch Screen](). - -The microphone on mobile can be used to capture audio that can be used in your game. For more information, see [Recording Sounds with Microphones](). - -> [!IMPORTANT] +--- +title: Overview of User Input and Input Devices +description: Input is a general term referring to the process of receiving actions from the user. +requireMSLicense: true +--- + +Input is a general term referring to the process of receiving actions from the user. In MonoGame, the [Microsoft.Xna.Framework.Input](xref:Microsoft.Xna.Framework.Input) namespace provides support for most input devices. + +Methods related to input devices unavailable on the platform your game is running on are always available to your code. For example, you can access all [GamePad](xref:Microsoft.Xna.Framework.Input.GamePad) methods on Mobile, but they will not return valid information (unless a GamePad is connected). Although using these methods will not cause exceptions or build errors in your code, they will silently fail when run. + +Physical keyboards may or may not be present on mobile devices; you should not rely on the presence of a physical keyboard. For text input, you should use a software input panel (SIP), which will work on all devices, including those with physical keyboards. + +If the mobile device does have access to a physical keyboard, the same methods used for keyboards on desktop can be used, given a few caveats. + +For multi-touch devices, you can use the raw touch data provided by the [TouchPanel](xref:Microsoft.Xna.Framework.Input.Touch.TouchPanel) class, but you can also use MonoGame's support for predefined gestures if your input fits one of the supported gesture types. For information about working with raw multi-touch input, see [Working with Touch Input](). For information about gesture support, see [Detecting Gestures on a Multi-touch Screen](). + +The microphone on mobile can be used to capture audio that can be used in your game. For more information, see [Recording Sounds with Microphones](). + +> [!IMPORTANT] > How to articles to follow. \ No newline at end of file diff --git a/articles/getting_to_know/whatis/WhatIs_MonoGame_Class_Library.md b/articles/getting_to_know/whatis/monogame_class_library/index.md similarity index 97% rename from articles/getting_to_know/whatis/WhatIs_MonoGame_Class_Library.md rename to articles/getting_to_know/whatis/monogame_class_library/index.md index 2d7723ea..0661b0c1 100644 --- a/articles/getting_to_know/whatis/WhatIs_MonoGame_Class_Library.md +++ b/articles/getting_to_know/whatis/monogame_class_library/index.md @@ -1,53 +1,53 @@ ---- -title: MonoGame Framework Class Library -description: MonoGame Framework Class Library Reference -requireMSLicense: true ---- - -The MonoGame Framework class library is a library of classes, interfaces, and value types that are included in MonoGame Game Studio. This library provides access to MonoGame Framework functionality and is designed to be the foundation on which MonoGame Game Studio applications, components, and controls are built. - -## Namespaces - -- [Microsoft.Xna.Framework](xref:Microsoft.Xna.Framework) - - Provides commonly needed game classes such as timers and game loops. - -- [Microsoft.Xna.Framework.Audio](xref:Microsoft.Xna.Framework.Audio) - - Contains low-level application programming interface (API) methods that can load and manipulate content files to play audio. - -- [Microsoft.Xna.Framework.Content](xref:Microsoft.Xna.Framework.Content) - - Contains the run-time components of the Content Pipeline. - -- [Microsoft.Xna.Framework.Design](xref:Microsoft.Xna.Framework.Design) - - Provides a unified way of converting types of values to other types. - -- [Microsoft.Xna.Framework.Graphics](xref:Microsoft.Xna.Framework.Graphics) - - Contains low-level application programming interface (API) methods that take advantage of hardware acceleration capabilities to display 3D objects. - -- [Microsoft.Xna.Framework.Graphics.PackedVector](xref:Microsoft.Xna.Framework.Graphics.PackedVector) - - Represents data types with components that are not multiples of 8 bits. - -- [Microsoft.Xna.Framework.Input](xref:Microsoft.Xna.Framework.Input) - - Contains classes to receive input from keyboard, mouse, and GamePad devices. - -- [Microsoft.Xna.Framework.Input.Touch](xref:Microsoft.Xna.Framework.Input.Touch) - - Contains classes that enable access to touch-based input on devices that support it. - -- [Microsoft.Xna.Framework.Media](xref:Microsoft.Xna.Framework.Media) - - Contains classes to enumerate, play, and view songs, albums, playlists, and pictures. - -- Microsoft.Xna.Framework.Utilities - - Contains classes that provide additional support for working with MonoGame. - -- Microsoft.Xna.Framework.Utilities.Deflate - - Contains classes that provide additional support for compression with MonoGame. +--- +title: MonoGame Framework Class Library +description: MonoGame Framework Class Library Reference +requireMSLicense: true +--- + +The MonoGame Framework class library is a library of classes, interfaces, and value types that are included in MonoGame Game Studio. This library provides access to MonoGame Framework functionality and is designed to be the foundation on which MonoGame Game Studio applications, components, and controls are built. + +## Namespaces + +- [Microsoft.Xna.Framework](xref:Microsoft.Xna.Framework) + + Provides commonly needed game classes such as timers and game loops. + +- [Microsoft.Xna.Framework.Audio](xref:Microsoft.Xna.Framework.Audio) + + Contains low-level application programming interface (API) methods that can load and manipulate content files to play audio. + +- [Microsoft.Xna.Framework.Content](xref:Microsoft.Xna.Framework.Content) + + Contains the run-time components of the Content Pipeline. + +- [Microsoft.Xna.Framework.Design](xref:Microsoft.Xna.Framework.Design) + + Provides a unified way of converting types of values to other types. + +- [Microsoft.Xna.Framework.Graphics](xref:Microsoft.Xna.Framework.Graphics) + + Contains low-level application programming interface (API) methods that take advantage of hardware acceleration capabilities to display 3D objects. + +- [Microsoft.Xna.Framework.Graphics.PackedVector](xref:Microsoft.Xna.Framework.Graphics.PackedVector) + + Represents data types with components that are not multiples of 8 bits. + +- [Microsoft.Xna.Framework.Input](xref:Microsoft.Xna.Framework.Input) + + Contains classes to receive input from keyboard, mouse, and GamePad devices. + +- [Microsoft.Xna.Framework.Input.Touch](xref:Microsoft.Xna.Framework.Input.Touch) + + Contains classes that enable access to touch-based input on devices that support it. + +- [Microsoft.Xna.Framework.Media](xref:Microsoft.Xna.Framework.Media) + + Contains classes to enumerate, play, and view songs, albums, playlists, and pictures. + +- Microsoft.Xna.Framework.Utilities + + Contains classes that provide additional support for working with MonoGame. + +- Microsoft.Xna.Framework.Utilities.Deflate + + Contains classes that provide additional support for compression with MonoGame. diff --git a/articles/getting_to_know/whatis/toc.yml b/articles/getting_to_know/whatis/toc.yml deleted file mode 100644 index 80e1ad20..00000000 --- a/articles/getting_to_know/whatis/toc.yml +++ /dev/null @@ -1,18 +0,0 @@ -- name: <- Back - href: ../index.md -- name: Introduction - href: index.md -- name: Content Pipeline - href: content_pipeline/ -- name: Graphics - href: graphics/ -- name: Audio - href: WhatIs_Audio.md -- name: Input - href: WhatIs_Input.md -- name: The Game Loop - href: WhatIs_TheGameLoop.md -- name: Vector / Matrix / Quaternions - href: WhatIs_VectorMatrixQuat.md -- name: MonoGame Class Library - href: WhatIs_VectorMatrixQuat.md diff --git a/articles/getting_to_know/whatis/WhatIs_VectorMatrixQuat.md b/articles/getting_to_know/whatis/vector_matrix_quat/index.md similarity index 98% rename from articles/getting_to_know/whatis/WhatIs_VectorMatrixQuat.md rename to articles/getting_to_know/whatis/vector_matrix_quat/index.md index b4d8aa89..86269dd2 100644 --- a/articles/getting_to_know/whatis/WhatIs_VectorMatrixQuat.md +++ b/articles/getting_to_know/whatis/vector_matrix_quat/index.md @@ -1,63 +1,63 @@ ---- -title: What are Vectors, Matrices, and Quaternions? -description: What are What are Vectors, Matrices, and Quaternions definitions for MonoGame! -requireMSLicense: true ---- - -The MonoGame Framework Math Libraries are in the [Microsoft.Xna.Framework](xref:Microsoft.Xna.Framework) namespace alongside a number of additional types that deal with The MonoGame Framework Application model. - -* [Coordinate system](#coordinate-system) -* [Mathematical Constants and Scalar Manipulation](#mathematical-constants-and-scalar-manipulation) -* [Basic Geometric Types](#basic-geometric-types) -* [Precision and Performance](#precision-and-performance) - -## Coordinate system - -The MonoGame Framework uses a right-handed coordinate system, with the positive z-axis pointing toward the observer when the positive x-axis is pointing to the right, and the positive y-axis is pointing up. - -## Mathematical Constants and Scalar Manipulation - -The MonoGame Framework provides the [MathHelper Members](xref:Microsoft.Xna.Framework.MathHelper) class for manipulating scalar values and retrieving some common mathematical constants. This includes methods such as the `ToDegrees` and `ToRadians` utility methods for converting between degrees and radians. - -## Basic Geometric Types - -The MonoGame Framework Math library has multiple basic geometric types for manipulating objects in 2D or 3D space. Each geometric type has a number of mathematical operations that are supported for the type. - -### Vectors - -The MonoGame Framework provides the [Vector2](xref:Microsoft.Xna.Framework.Vector2), [Vector3](xref:Microsoft.Xna.Framework.Vector3), and [Vector4](xref:Microsoft.Xna.Framework.Vector4) classes for representing and manipulating vectors. A vector typically is used to represent a direction and magnitude. In The MonoGame Framework, however, it also could be used to store a coordinate or other data type with the same storage requirements. - -Each vector class has methods for performing standard vector operations such as: - -* [Dot product](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Dot_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_) -* [Cross product](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Cross_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_) -* [Normalization](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Normalize) -* [Transformation](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Transform_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Matrix_) -* [Linear](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Lerp_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_), [Cubic](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_SmoothStep_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_), [Catmull-Rom](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_CatmullRom_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_), or [Hermite spline](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Hermite_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_) interpolation. - -### Matrices - -The MonoGame Framework provides the [Matrix](xref:Microsoft.Xna.Framework.Matrix) class for transformation of geometry. The [Matrix](xref:Microsoft.Xna.Framework.Matrix) class uses row major order to address matrices, which means that the row is specified before the column when describing an element of a two-dimensional matrix. The [Matrix](xref:Microsoft.Xna.Framework.Matrix) class provides methods for performing standard matrix operations such as calculating the `determinate` or `inverse` of a matrix. There also are helper methods for creating scale, rotation, and translation matrices. - -### Quaternions - -The MonoGame Framework provides the [Quaternion](xref:Microsoft.Xna.Framework.Quaternion) structure to calculate the efficient rotation of a vector by a specified angle. - -### Curves - -The [Curve](xref:Microsoft.Xna.Framework.Curve) class represents a Hermite curve for interpolating varying positions at different times without having to explicitly define each position. The curve is defined by a collection of [CurveKey](xref:Microsoft.Xna.Framework.CurveKey) points representing each varying position at different times. This class can be used not only for spatial motion, but also to represent any response that changes over time. - -### Bounding Volumes - -The MonoGame Framework provides the [BoundingBox](xref:Microsoft.Xna.Framework.BoundingBox), [BoundingFrustum](xref:Microsoft.Xna.Framework.BoundingFrustum), [BoundingSphere](xref:Microsoft.Xna.Framework.BoundingSphere), [Plane](xref:Microsoft.Xna.Framework.Plane), and [Ray](xref:Microsoft.Xna.Framework.Ray) classes for representing simplified versions of geometry for the purpose of efficient collision and hit testing. These classes have methods for checking for intersection and containment with each other. - -## Precision and Performance - -The MonoGame Framework Math libraries are single-precision. This means that the primitives and operations contained in this library use 32-bit floating-point numbers to achieve a balance between precision and efficiency when performing large numbers of calculations. - -A 32-bit floating-point number ranges from `–3.402823e38` to `+3.402823e38`. The 32 bits store the sign, mantissa, and exponent of the number that yields seven digits of floating-point precision. - - [!NOTE] -> Some numbers—for example π, 1/3, or the square root of two—can be approximated only with seven digits of precision, so be aware of rounding errors when using a binary representation of a floating-point number. - -For more information about single-precision numbers, see the documentation for the [Single](http://msdn.microsoft.com/en-us/library/system.single.aspx) data type. +--- +title: What are Vectors, Matrices, and Quaternions? +description: What are What are Vectors, Matrices, and Quaternions definitions for MonoGame! +requireMSLicense: true +--- + +The MonoGame Framework Math Libraries are in the [Microsoft.Xna.Framework](xref:Microsoft.Xna.Framework) namespace alongside a number of additional types that deal with The MonoGame Framework Application model. + +* [Coordinate system](#coordinate-system) +* [Mathematical Constants and Scalar Manipulation](#mathematical-constants-and-scalar-manipulation) +* [Basic Geometric Types](#basic-geometric-types) +* [Precision and Performance](#precision-and-performance) + +## Coordinate system + +The MonoGame Framework uses a right-handed coordinate system, with the positive z-axis pointing toward the observer when the positive x-axis is pointing to the right, and the positive y-axis is pointing up. + +## Mathematical Constants and Scalar Manipulation + +The MonoGame Framework provides the [MathHelper Members](xref:Microsoft.Xna.Framework.MathHelper) class for manipulating scalar values and retrieving some common mathematical constants. This includes methods such as the `ToDegrees` and `ToRadians` utility methods for converting between degrees and radians. + +## Basic Geometric Types + +The MonoGame Framework Math library has multiple basic geometric types for manipulating objects in 2D or 3D space. Each geometric type has a number of mathematical operations that are supported for the type. + +### Vectors + +The MonoGame Framework provides the [Vector2](xref:Microsoft.Xna.Framework.Vector2), [Vector3](xref:Microsoft.Xna.Framework.Vector3), and [Vector4](xref:Microsoft.Xna.Framework.Vector4) classes for representing and manipulating vectors. A vector typically is used to represent a direction and magnitude. In The MonoGame Framework, however, it also could be used to store a coordinate or other data type with the same storage requirements. + +Each vector class has methods for performing standard vector operations such as: + +* [Dot product](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Dot_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_) +* [Cross product](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Cross_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_) +* [Normalization](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Normalize) +* [Transformation](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Transform_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Matrix_) +* [Linear](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Lerp_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_), [Cubic](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_SmoothStep_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_), [Catmull-Rom](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_CatmullRom_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_), or [Hermite spline](/api/Microsoft.Xna.Framework.Vector3.html#Microsoft_Xna_Framework_Vector3_Hermite_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_Microsoft_Xna_Framework_Vector3_System_Single_) interpolation. + +### Matrices + +The MonoGame Framework provides the [Matrix](xref:Microsoft.Xna.Framework.Matrix) class for transformation of geometry. The [Matrix](xref:Microsoft.Xna.Framework.Matrix) class uses row major order to address matrices, which means that the row is specified before the column when describing an element of a two-dimensional matrix. The [Matrix](xref:Microsoft.Xna.Framework.Matrix) class provides methods for performing standard matrix operations such as calculating the `determinate` or `inverse` of a matrix. There also are helper methods for creating scale, rotation, and translation matrices. + +### Quaternions + +The MonoGame Framework provides the [Quaternion](xref:Microsoft.Xna.Framework.Quaternion) structure to calculate the efficient rotation of a vector by a specified angle. + +### Curves + +The [Curve](xref:Microsoft.Xna.Framework.Curve) class represents a Hermite curve for interpolating varying positions at different times without having to explicitly define each position. The curve is defined by a collection of [CurveKey](xref:Microsoft.Xna.Framework.CurveKey) points representing each varying position at different times. This class can be used not only for spatial motion, but also to represent any response that changes over time. + +### Bounding Volumes + +The MonoGame Framework provides the [BoundingBox](xref:Microsoft.Xna.Framework.BoundingBox), [BoundingFrustum](xref:Microsoft.Xna.Framework.BoundingFrustum), [BoundingSphere](xref:Microsoft.Xna.Framework.BoundingSphere), [Plane](xref:Microsoft.Xna.Framework.Plane), and [Ray](xref:Microsoft.Xna.Framework.Ray) classes for representing simplified versions of geometry for the purpose of efficient collision and hit testing. These classes have methods for checking for intersection and containment with each other. + +## Precision and Performance + +The MonoGame Framework Math libraries are single-precision. This means that the primitives and operations contained in this library use 32-bit floating-point numbers to achieve a balance between precision and efficiency when performing large numbers of calculations. + +A 32-bit floating-point number ranges from `–3.402823e38` to `+3.402823e38`. The 32 bits store the sign, mantissa, and exponent of the number that yields seven digits of floating-point precision. + + [!NOTE] +> Some numbers—for example π, 1/3, or the square root of two—can be approximated only with seven digits of precision, so be aware of rounding errors when using a binary representation of a floating-point number. + +For more information about single-precision numbers, see the documentation for the [Single](http://msdn.microsoft.com/en-us/library/system.single.aspx) data type. diff --git a/articles/toc.yml b/articles/toc.yml index ddc972f7..b50bc4a8 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -65,19 +65,19 @@ href: getting_to_know/whatis/ items: - name: Audio - href: getting_to_know/whatis/WhatIs_Audio.md + href: getting_to_know/whatis/audio/ - name: Content Pipeline href: getting_to_know/whatis/content_pipeline/ - name: Graphics href: getting_to_know/whatis/graphics/ - name: Input - href: getting_to_know/whatis/WhatIs_Input.md + href: getting_to_know/whatis/input/ - name: The Game Loop - href: getting_to_know/whatis/WhatIs_TheGameLoop.md + href: getting_to_know/whatis/game_loop/ - name: Vector / Matrix / Quaternions - href: getting_to_know/whatis/WhatIs_VectorMatrixQuat.md + href: getting_to_know/whatis/vector_matrix_quat/ - name: MonoGame Class Library - href: getting_to_know/whatis/WhatIs_MonoGame_Class_Library.md + href: getting_to_know/whatis/monogame_class_library/ - name: How to href: getting_to_know/howto/ items: