<!-- 🚨 Please Do Not skip any instructions and information mentioned below as they are all required and essential to evaluate and test the PR. By fulfilling all the required information you will be able to reduce the volume of questions and most likely help merge the PR faster 🚨 -->
<!-- 📝 It is preferred if you keep the "☑️ Allow edits by maintainers" checked in the Pull Request Template as it increases collaboration with the Toolkit maintainers by permitting commits to your PR branch (only) created from your fork. This can let us quickly make fixes for minor typos or forgotten StyleCop issues during review without needing to wait on you doing extra work. Let us help you help us! 🎉 -->
## Related to #3422
<!-- Add the relevant issue number after the "#" mentioned above (for ex: Fixes#1234) which will automatically close the issue once the PR is merged. -->
<!-- Add a brief overview here of the feature/bug & fix. -->
## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->
- Refactoring
- Improvements
<!-- - Bugfix -->
<!-- - Feature -->
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->
## Overview
Following the suggestion from @mrlacey for non-breaking changes, this PR moves the new `Span2D<T>` and `Memory2D<T>` types introduced in version 7.0 to the root `Microsoft.Toolkit.HighPerformance` namespace (instead of `.Memory`). This is simpler to use for consumers, it makes sense given that the root namespace already contains some other "primitive" types, and it's also more consistent to how the `Span<T>` and `Memory<T>` types are included in the `System.Memory` package, but are still located in the root `System` namespace.
This PR also includes some minor codegen improvements to some other extensions, while I was at it 😄
## PR Checklist
Please check if your PR fulfills the following requirements:
- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] ~~Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->~~
- [ ] ~~Sample in sample app has been added / updated (for bug fixes / features)~~
- [ ] ~~Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)~~
- [X] New major technical changes in the toolkit have or will be added to the [Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) e.g. build changes, source generators, testing infrastructure, sample creation changes, etc...
- [X] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [X] Contains **NO** breaking changes
### Related to #3594, working towards reducing footprint and increasing modularity
<!-- Add a brief overview here of the feature/bug & fix. -->
## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->
<!-- - Bugfix -->
<!-- - Feature -->
<!-- - Code style update (formatting) -->
- Refactoring (no functional changes, no api changes)
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->
The `Guard` and `ThrowHelper` APIs are part of the `Microsoft.Toolkit` package.
This has a few downsides with respect to binary size for consuming package and overall API surface for consumers.
The `Guard` and `ThrowHelper` APIs relied on a number of different NuGet packages that needed to be pulled in:
- `System.Diagnostics.Contracts`
- `System.ValueTuple`
- `System.Memory`
- `System.Runtime.CompilerServices.Unsafe`
These packages are _only_ needed by those APIs, and yet with `Microsoft.Toolkit` being referenced by every other package in the whole Toolkit, every other package ended up having a dependency on those as well even when there was no use for them at all. This is not ideal both for final binary size, for the increased number of potentially unwanted APIs being imported by consumers, and due to the fact that many consumers want to minimize the number of NuGet dependencies in general.
Furthermore, the `.Diagnostics` APIs can be very useful for all kinds of developers, especially those working in backend scenarios and with a particular focus on performance. It was not ideal to force those developers to also import APIs such as observable collections and other more UI-oriented APIs that were available in the base package (in fact I've spoken with a few devs that didn't like having to include anything other than just the `Guard` and `ThrowHelper` APIs when adding the package).
For consumers on .NET 5 that don't use .NET Native, splitting the `Guard` and `ThrowHelper` APIs away means 80KB less in binary size (when not using IL trimming) when those APIs are not needed, which is effectively a 75% reduction on the base package.
## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->
The `Guard` and `ThrowHelper` APIs have now been moved to a new `Microsoft.Toolkit.Diagnostics` package.
Splitting this package completely removes all those dependencies from all other packages too 🚀
This work will also make it easier in the future to introduce a `.Diagnostics` source-only package, if we wanted to.
**Note:** marking as breaking change due to the APIs being moved to a different package, but this PR doesn't do any changes to the overall API surface across the various packages - the APIs are still all exactly the same, just modularized differently.
## PR Checklist
Please check if your PR fulfills the following requirements:
- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] ~~Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->~~
- [ ] ~~Sample in sample app has been added / updated (for bug fixes / features)~~
- [ ] ~~Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)~~
- [X] New major technical changes in the toolkit have or will be added to the [Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) e.g. build changes, source generators, testing infrastructure, sample creation changes, etc...
- [X] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [ ] Contains **NO** breaking changes
## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->
<!-- - Bugfix -->
- Feature
- Optimization
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->
There are no `nint`/`nuint` overloads for the any `Guard` APIs. These types have been introduced with C# 9, so it makes sense to add proper support for them given that #3356 added full support for C# 9 and .NET 5 to these packages.
Also there were some codegen bits in `Guard.IsCloseTo` that were not ideal.
Additionally, the codegen for the `Guard` APIs didn't leverage compiler support properly.
## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->
✅ Added new `nint`/`nuint` overloads to `Guard` APIs
🚀 Improved codegen in a number of `Guard.IsCloseTo` overloads
🚀 Improved codegen for faulting blocks
## PR Checklist
Please check if your PR fulfills the following requirements:
- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->
- [ ] Sample in sample app has been added / updated (for bug fixes / features)
- [ ] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)
- [X] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [X] Contains **NO** breaking changes
## Fixes
<!-- Add the relevant issue number after the "#" mentioned above (for ex: Fixes#1234) which will automatically close the issue once the PR is merged. -->
Add lazy loading threshold for ```ImageEx``` control and change the lazy loading implement that will be also fixed#3258 .
<!-- Add a brief overview here of the feature/bug & fix. -->
## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->
- Bugfix
- Feature
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->
If enable lazy loading, only the ImageEx entered the viewport, the source will start to load.
## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->
Give a threshold for triggering the lazy loading behavior, the default value is 300 px.
## PR Checklist
Please check if your PR fulfills the following requirements:
- [x] Tested code with current [supported SDKs](../readme.md#supported)
- [x] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/pull/387<!-- docs PR link -->
- [x] Sample in sample app has been added / updated (for bug fixes / features)
- [ ] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)
- [ ] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [ ] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [x] Contains **NO** breaking changes
<!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below.
Please note that breaking changes are likely to be rejected. -->
## Other information
## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->
- Optimization
<!-- - Bugfix -->
<!-- - Feature -->
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->
Some `for` loops have unoptimal codegen involving the indexing at each iteration.
For instance, as a very simple test, this method simply sets all items in an input `Span<int>` to `0`:
```csharp
public static void M1(Span<int> span)
{
ref int r0 = ref MemoryMarshal.GetReference(span);
int length = span.Length;
for (int i = 0; i < length; i++)
{
Unsafe.Add(ref r0, i) = 0;
}
}
```
```asm
C.M1(System.Span`1<Int32>)
L0000: mov rax, [rcx]
L0003: mov edx, [rcx+8]
L0006: xor ecx, ecx
L0008: test edx, edx
L000a: jle short L001c
L000c: movsxd r8, ecx
L000f: xor r9d, r9d
L0012: mov [rax+r8*4], r9d
L0016: inc ecx
L0018: cmp ecx, edx
L001a: jl short L000c
L001c: ret
```
Here the loop starts at `L000c`, and at every iteration it takes the loop counter, extends it to native int, then uses it to index from the initial reference (that `[rax+r8*4]` offset calculation), and then writes to it. This is unnecessary logic, in cases such as this.
## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->
Refactored some loops to operate within a target address range, with all indexing out of the loop body.
```csharp
public static void M2(Span<int> span)
{
ref int r0 = ref MemoryMarshal.GetReference(span);
ref int r1 = ref Unsafe.Add(ref r0, span.Length);
while (Unsafe.IsAddressLessThan(ref r0, ref r1))
{
r0 = 0;
r0 = ref Unsafe.Add(ref r0, 1);
}
}
```
```asm
C.M2(System.Span`1<Int32>)
L0000: mov rax, [rcx]
L0003: mov edx, [rcx+8]
L0006: movsxd rdx, edx
L0009: lea rdx, [rax+rdx*4]
L000d: cmp rax, rdx
L0010: jae short L001f
L0012: xor ecx, ecx
L0014: mov [rax], ecx
L0016: add rax, 4
L001a: cmp rax, rdx
L001d: jb short L0012
L001f: ret
```
Here instead we pre-calculate the target address just once, outside the loop, and then just iterate until the initial, moving reference reaches that point. This allows the actual loop to be more compact and with no indexing logic needed. We just read directly from the moving reference, and then increment it by a fixed amount at the end of each iteration. Not groundbreaking, but better 🚀
## PR Checklist
Please check if your PR fulfills the following requirements:
- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] ~~Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->~~
- [ ] ~~Sample in sample app has been added / updated (for bug fixes / features)~~
- [ ] ~~Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)~~
- [X] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [X] Contains **NO** breaking changes
