Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: status error codes #256

Merged
merged 1 commit into from
Sep 18, 2024
Merged

docs: status error codes #256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 25 additions & 14 deletions Documentation~/manual/advanced/input-validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,24 @@
# Input validation

If [`ValidateInput`][validate] is set to true, the provided data will be validated before running the triangulation procedure. Input positions, as well as input constraints, have several restrictions:

- Points count must be greater/equal 3.
- Points positions cannot be duplicated.
- Points cannot contain NaNs or infinities.
- Constraint edges cannot intersect with each other.
- Constraint edges cannot be duplicated or swapped duplicated.
- Zero-length constraint edges are forbidden.
- Constraint edges cannot intersect with points other than the points for which they are defined.
- [`IgnoreConstraintForPlantingSeeds`][ignore-constraint] must have a length equal to half the length of [ConstraintEdges][constraints].
- If [`IgnoreConstraintForPlantingSeeds`][ignore-constraint] is provided, [`ConstraintEdges`][constraints] must also be provided.

If any of these conditions fail, triangulation will not be calculated. You can catch this as an error by using [`Status`][status] (native, can be used in jobs).
If [`ValidateInput`][validate] set to true, the provided [`InputData<T2>`][input-data] and [`TriangulationSettings`][settings] will be validated before executing the triangulation procedure.
The input
[`InputData<T2>.Positions`][positions],
[`InputData<T2>.ConstraintEdges`][constraints],
[`InputData<T2>.HoleSeeds`][holes],
and [`InputData<T2>.IgnoreConstraintForPlantingSeeds`][ignore-constraint] have certain restrictions:

- [Positions][positions] count must be greater or equal 3.
- [Positions][positions] and [HoleSeeds][holes] cannot contain NaNs or infinities.
- [Positions][positions] cannot be duplicated.
- [ConstraintEdges][constraints] should have length multiple of 2.
- [ConstraintEdges][constraints] should have constraints defined in [Positions][positions] range.
- [ConstraintEdges][constraints] cannot be duplicated, swapped duplicated, or create self-loop.
- [ConstraintEdges][constraints] cannot intersect with each other.
- [ConstraintEdges][constraints] cannot be collinear with positions which is not included in the constraint.
- [IgnoreConstraintForPlantingSeeds][ignore-constraint] must have a length equal to half the length of [ConstraintEdges][constraints].

If any of these conditions fail, triangulation will not be calculated. You can catch this as an error by using [`Status`][status-ref] (native reference, can be used in jobs).
For more details about error codes, refer to the [Status][status] API documentation.

```csharp
using var triangulator = new Triangulator(Allocator.Persistent)
Expand All @@ -32,6 +38,11 @@ var status = triangulator.Output.Status.Value;
> Input validation can be expensive. If you are certain of your input, consider disabling this option for additional performance.

[validate]: xref:andywiecko.BurstTriangulator.TriangulationSettings.ValidateInput
[status]: xref:andywiecko.BurstTriangulator.Status
[input-data]: xref:andywiecko.BurstTriangulator.InputData`1
[settings]: xref:andywiecko.BurstTriangulator.TriangulationSettings
[positions]: xref:andywiecko.BurstTriangulator.InputData`1.Positions
[constraints]: xref:andywiecko.BurstTriangulator.InputData`1.ConstraintEdges
[holes]: xref:andywiecko.BurstTriangulator.InputData`1.HoleSeeds
[ignore-constraint]: xref:andywiecko.BurstTriangulator.InputData`1.IgnoreConstraintForPlantingSeeds
[status-ref]: xref:andywiecko.BurstTriangulator.OutputData`1.Status
[status]: xref:andywiecko.BurstTriangulator.Status
9 changes: 7 additions & 2 deletions Documentation~/manual/examples/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ var triangles = triangulator.Output.Triangles;
> If you want to call this within a jobs pipeline, schedule a job using [`triangulator.Schedule(dependencies)`][schedule].
> Click [**here**](xref:example-unity-jobs) to learn how to use triangulation within a jobs pipeline.

If triangulation fails for some reason, you can catch the information using [`Status`][status]
If triangulation fails for some reason, you can catch the information using [`Status`][status-ref]

```csharp
status = triangulator.Output.Status.Value;
Expand All @@ -32,6 +32,10 @@ if (status != Status.OK) // ERROR!
}
```

> [!WARNING]
> The [Status][status-ref] can be used to handle various error codes.
> For more information about other enum values, refer to the [API documentation][status].

The result of the triangulation procedure will depend on the selected settings.
There are a few settings for triangulation, which are briefly described in the [API documentation][settings].
Follow the articles in the manual to learn more about settings.
Expand All @@ -43,4 +47,5 @@ In other examples, the following *cool* guitar was used as an input test case:
[settings]: xref:andywiecko.BurstTriangulator.TriangulationSettings
[run]: xref:andywiecko.BurstTriangulator.Triangulator.Run
[schedule]: xref:andywiecko.BurstTriangulator.Triangulator.Schedule(Unity.Jobs.JobHandle)
[status]: xref:andywiecko.BurstTriangulator.OutputData`1.Status
[status-ref]: xref:andywiecko.BurstTriangulator.OutputData`1.Status
[status]: xref:andywiecko.BurstTriangulator.Status
Loading