From d1d1e930f2fcc1f0c24630eedec823e96cfae9f6 Mon Sep 17 00:00:00 2001 From: Karl-Josef Adler Date: Sun, 13 Nov 2022 19:26:50 +0100 Subject: [PATCH 1/6] Create 0000-refactor-input.md Copy rfc/0000-template.md to rfc/0000-my-feature.md --- docs/src/rfc/0000-refactor-input.md | 112 ++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/src/rfc/0000-refactor-input.md diff --git a/docs/src/rfc/0000-refactor-input.md b/docs/src/rfc/0000-refactor-input.md new file mode 100644 index 000000000..ef4644eef --- /dev/null +++ b/docs/src/rfc/0000-refactor-input.md @@ -0,0 +1,112 @@ +- Feature Name: (fill me in with a unique ident, `my_awesome_feature`) +- Start Date: (fill me in with today's date, YYYY-MM-DD) +- RFC PR: [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/pull/0000) +- maplibre-rs Issue: [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/issues/0000) + +# Summary + +[summary]: #summary + +One paragraph explanation of the feature. + +# Motivation + +[motivation]: #motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +# Guide-level explanation + +[guide-level-explanation]: #guide-level-explanation + +Explain the proposal as if it was already included in the project and you were teaching it to another maplibre-rs user. +That generally means: + +- Introducing new named concepts. +- Explaining the feature largely in terms of examples. +- Explaining how maplibre-rs users should *think* about the feature, and how it should impact the way they use + maplibre-rs. It should explain the impact as concretely as possible. +- If applicable, provide sample error messages, deprecation warnings, or migration guidance. +- If applicable, describe the differences between teaching this to existing maplibre-rs users and new maplibre-rs users. + +For implementation-oriented RFCs (e.g. for internals), this section should focus on how maplibre-rs contributors should +think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an +example-driven introduction to the policy, and explain its impact in concrete terms. + +# Reference-level explanation + +[reference-level-explanation]: #reference-level-explanation + +This is the technical portion of the RFC. Explain the design in sufficient detail that: + +- Its interaction with other features is clear. +- It is reasonably clear how the feature would be implemented. +- Corner cases are dissected by example. + +The section should return to the examples given in the previous section, and explain more fully how the detailed +proposal makes those examples work. + +# Drawbacks + +[drawbacks]: #drawbacks + +Why should we *not* do this? + +# Rationale and alternatives + +[rationale-and-alternatives]: #rationale-and-alternatives + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? + +# Prior art + +[prior-art]: #prior-art + +Discuss prior art, both the good and the bad, in relation to this proposal. +A few examples of what this can include are: + +- Does this feature exist in other map renderers and what experience have their community had? +- For community proposals: Is this done by some other community and what were their experiences with it? +- For other teams: What lessons can we learn from what other communities have done here? +- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, + this can serve as a more detailed theoretical background. + +This section is intended to encourage you as an author to think about the lessons from other renderers, provide readers +of your RFC with a fuller picture. +If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an +adaptation from other map renderers. + +Note that while precedent set by other map renderers is some motivation, it does not on its own motivate an RFC. + +# Unresolved questions + +[unresolved-questions]: #unresolved-questions + +- What parts of the design do you expect to resolve through the RFC process before this gets merged? +- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of + the solution that comes out of this RFC? + +# Future possibilities + +[future-possibilities]: #future-possibilities + +Think about what the natural extension and evolution of your proposal would +be and how it would affect the renderer and project as a whole in a holistic +way. Try to use this section as a tool to more fully consider all possible +interactions with the project and renderer in your proposal. +Also consider how this all fits into the roadmap for the project +and of the relevant sub-team. + +This is also a good place to "dump ideas", if they are out of scope for the +RFC you are writing but otherwise related. + +If you have tried and cannot think of any future possibilities, +you may simply state that you cannot think of anything. + +Note that having something written down in the future-possibilities section +is not a reason to accept the current or a future RFC; such notes should be +in the section on motivation or rationale in this or subsequent RFCs. +The section merely provides additional information. From eaa65da9199b40de185bbedbdc85e0978109842f Mon Sep 17 00:00:00 2001 From: Karl-Josef Adler Date: Sun, 13 Nov 2022 20:04:35 +0100 Subject: [PATCH 2/6] Update 0000-refactor-input.md Started summary --- docs/src/rfc/0000-refactor-input.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/src/rfc/0000-refactor-input.md b/docs/src/rfc/0000-refactor-input.md index ef4644eef..59724f02f 100644 --- a/docs/src/rfc/0000-refactor-input.md +++ b/docs/src/rfc/0000-refactor-input.md @@ -1,7 +1,7 @@ -- Feature Name: (fill me in with a unique ident, `my_awesome_feature`) -- Start Date: (fill me in with today's date, YYYY-MM-DD) -- RFC PR: [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/pull/0000) -- maplibre-rs Issue: [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/issues/0000) +- Feature Name: (`refract_input`) +- Start Date: (2022-11-13) +- RFC PR: [maplibre/maplibre-rs#00??](https://github.com/maplibre/maplibre-rs/pull/00??) +- maplibre-rs Issue: #91 and otherrs [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/issues/91) # Summary @@ -9,12 +9,21 @@ One paragraph explanation of the feature. +Refract the input modules: +Define and document the function of the default input-controller, equaly to the input UI of maplibre-gl-js (Issue #186) +Implement an event loop. Consider, in maplibre-gl-js the loop is part of the map-camera. (Issue #91) +Check, if/what variations of winit, we need. +Refract the splitting of the input controller functionality in modules/source-codes, may be like maplibre-gl-js (Issue #91) +Sepatate the input-controller in an extra Rust module/crate (Issue #185) + # Motivation [motivation]: #motivation Why are we doing this? What use cases does it support? What is the expected outcome? +The input module, which handles key presses and other inputs is quite cluttered. That means that, the logic in order to update the libraries state is quite complicated. + # Guide-level explanation [guide-level-explanation]: #guide-level-explanation From f11e5143427e7e89c260a2c62ce35448e3ad05c3 Mon Sep 17 00:00:00 2001 From: Karl-Josef Adler Date: Mon, 14 Nov 2022 20:35:16 +0100 Subject: [PATCH 3/6] Update 0000-refactor-input.md Motivation --- docs/src/rfc/0000-refactor-input.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/src/rfc/0000-refactor-input.md b/docs/src/rfc/0000-refactor-input.md index 59724f02f..90f4d6c0f 100644 --- a/docs/src/rfc/0000-refactor-input.md +++ b/docs/src/rfc/0000-refactor-input.md @@ -10,11 +10,13 @@ One paragraph explanation of the feature. Refract the input modules: -Define and document the function of the default input-controller, equaly to the input UI of maplibre-gl-js (Issue #186) -Implement an event loop. Consider, in maplibre-gl-js the loop is part of the map-camera. (Issue #91) -Check, if/what variations of winit, we need. -Refract the splitting of the input controller functionality in modules/source-codes, may be like maplibre-gl-js (Issue #91) -Sepatate the input-controller in an extra Rust module/crate (Issue #185) +* A) Define and document the function of the default input-controller, equaly to the input UI of maplibre-gl-js (Issue #186) +* B) Implement an event loop. Consider, in maplibre-gl-js the loop is part of the map-camera. (Issue #91) +* C) Check, if/what variations of winit, we need. +* D) Refract the splitting of the input controller functionality in modules/source-codes, may be like maplibre-gl-js (Issue #91) +* E) Sepatate the input-controller in an extra Rust module/crate (Issue #185) + +Should all this realy be in one RFC? # Motivation @@ -22,9 +24,20 @@ Sepatate the input-controller in an extra Rust module/crate (Issue #185) Why are we doing this? What use cases does it support? What is the expected outcome? -The input module, which handles key presses and other inputs is quite cluttered. That means that, the logic in order to update the libraries state is quite complicated. +A) The user of maplibre-rs sould "feel at home", have the identical UI expirience + +B) Now, each input module does the map move/slide itselve. +If we do it in the map-module, maintaining the inputs and writing a custom imput controler would be les complex. + +C) Will the default winit work for all targets? - Todo: maxammann + +D) The input module, which handles key presses and other inputs is quite cluttered. That means that, the logic in order to update the libraries state is quite complicated. Just one input module for key, mouse and touch, calling the map-API (see B) would be simpler. + +E) Actually, a fork of the whole repository to build a individual changed application. +If we offer two extra rust crates for rendering and for control/UI, just the UI could be forked and changed. + -# Guide-level explanation +# Guide-level explanation ???Detailed design??? [guide-level-explanation]: #guide-level-explanation From 868579d448e49e045a68486b84682320265a2095 Mon Sep 17 00:00:00 2001 From: -karlos- Date: Sat, 19 Nov 2022 14:19:19 +0100 Subject: [PATCH 4/6] Guide-level explanation --- docs/src/rfc/0000-refactor-input.md | 44 ++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/docs/src/rfc/0000-refactor-input.md b/docs/src/rfc/0000-refactor-input.md index 90f4d6c0f..cf3e1ae00 100644 --- a/docs/src/rfc/0000-refactor-input.md +++ b/docs/src/rfc/0000-refactor-input.md @@ -10,13 +10,13 @@ One paragraph explanation of the feature. Refract the input modules: -* A) Define and document the function of the default input-controller, equaly to the input UI of maplibre-gl-js (Issue #186) -* B) Implement an event loop. Consider, in maplibre-gl-js the loop is part of the map-camera. (Issue #91) -* C) Check, if/what variations of winit, we need. -* D) Refract the splitting of the input controller functionality in modules/source-codes, may be like maplibre-gl-js (Issue #91) +* A) Implement an event loop. Consider, in maplibre-gl-js the loop is part of the map-camera. (Issue #91) +* B) Check, if/what variations of winit, we need. +* C) Refract the splitting of the input controller functionality in modules/source-codes, may be like maplibre-gl-js (Issue #91) +* D) Define and document the function of the default input-controller, equaly to the input UI of maplibre-gl-js (Issue #186) * E) Sepatate the input-controller in an extra Rust module/crate (Issue #185) -Should all this realy be in one RFC? +Should all this realy be in one RFC? Separate A) in an extra RFC? And B)? Oh! RFCs are ment for users of maplibre-rs only, not for internal development! That means, only C) and E) remains? # Motivation @@ -24,16 +24,16 @@ Should all this realy be in one RFC? Why are we doing this? What use cases does it support? What is the expected outcome? -A) The user of maplibre-rs sould "feel at home", have the identical UI expirience - -B) Now, each input module does the map move/slide itselve. +A) At the current version, each input module does the map move/slide itselve. If we do it in the map-module, maintaining the inputs and writing a custom imput controler would be les complex. -C) Will the default winit work for all targets? - Todo: maxammann +B) Will the default winit work for all targets? - Todo: maxammann + +C) The input module, which handles key presses and other inputs is quite cluttered. That means that, the logic in order to update the libraries state is quite complicated. We have to decide, how to split. Just one input module for key, mouse and touch, calling the map-API (see B) would be simpler. -D) The input module, which handles key presses and other inputs is quite cluttered. That means that, the logic in order to update the libraries state is quite complicated. Just one input module for key, mouse and touch, calling the map-API (see B) would be simpler. +D) The user of maplibre-rs sould "feel at home", have the identical UI expirience, while using the input controls. -E) Actually, a fork of the whole repository to build a individual changed application. +E) Actually, a fork of the whole repository is needed to build a individual changed application. If we offer two extra rust crates for rendering and for control/UI, just the UI could be forked and changed. @@ -52,8 +52,26 @@ That generally means: - If applicable, describe the differences between teaching this to existing maplibre-rs users and new maplibre-rs users. For implementation-oriented RFCs (e.g. for internals), this section should focus on how maplibre-rs contributors should -think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an -example-driven introduction to the policy, and explain its impact in concrete terms. +think about the change, and give examples of its concrete impact (= A,B,C) + +A) +The map should offers an API, a function or a message queue to set the new map view, both imidiately and like an intrpolating move of the camera. We could do it like in maplibre-gl-js, there is only a single API, setting all values at once: position, angle, zoom. +The developer of a new control don't need to set or interpolate the camera but just calls that API. + +B) Todo: maxammann + +C) +At the monent, there is no concept, what input handler sould do what inputs and actions. If we do it like maplibre-gl-js, +there would be one handler for one input type. A keyboard handler would process all keybpard actions, change and set all values: position, angle, zoom. + +D) If a user knows maplibre-gl-js, one should expirience and find in the documentation exactly the same input UI. +All keyboard, mouse and touch input actions should be descripted and coded equal to maplibre-gl-js. We then could extend the UI and i.e. add keys for rotaton etc. + +E) The user of maplibre-rs should find +1) a crate to make the map visible, but don't need to se its code, just a well descripted API +2) a crate to control the map as an example to adapt the Rust code as wiched. +3) and examples to build applications for different targets. + # Reference-level explanation From c78d5fcbb850a31fecea951faafd80fd343f2309 Mon Sep 17 00:00:00 2001 From: -karlos- Date: Sun, 20 Nov 2022 14:42:48 +0100 Subject: [PATCH 5/6] rename to input_handling --- .../src/rfc/{0000-refactor-input.md => 0000-input-handling..md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/src/rfc/{0000-refactor-input.md => 0000-input-handling..md} (99%) diff --git a/docs/src/rfc/0000-refactor-input.md b/docs/src/rfc/0000-input-handling..md similarity index 99% rename from docs/src/rfc/0000-refactor-input.md rename to docs/src/rfc/0000-input-handling..md index cf3e1ae00..278e0a9c3 100644 --- a/docs/src/rfc/0000-refactor-input.md +++ b/docs/src/rfc/0000-input-handling..md @@ -1,4 +1,4 @@ -- Feature Name: (`refract_input`) +- Feature Name: (`input_handling.`) - Start Date: (2022-11-13) - RFC PR: [maplibre/maplibre-rs#00??](https://github.com/maplibre/maplibre-rs/pull/00??) - maplibre-rs Issue: #91 and otherrs [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/issues/91) From e82bc61f84b0c210a7fad5cbe1d5a73725c2cb64 Mon Sep 17 00:00:00 2001 From: Maximilian Ammann Date: Sat, 19 Nov 2022 22:06:53 +0100 Subject: [PATCH 6/6] Add a Summary text, add titles for aspects of this PR, fix typos, move content to motivation --- docs/src/rfc/0000-input-handling..md | 106 +++++++++++++++++---------- 1 file changed, 69 insertions(+), 37 deletions(-) diff --git a/docs/src/rfc/0000-input-handling..md b/docs/src/rfc/0000-input-handling..md index 278e0a9c3..4da2dfda9 100644 --- a/docs/src/rfc/0000-input-handling..md +++ b/docs/src/rfc/0000-input-handling..md @@ -1,22 +1,33 @@ -- Feature Name: (`input_handling.`) +- Feature Name: (`input_handling`) - Start Date: (2022-11-13) - RFC PR: [maplibre/maplibre-rs#00??](https://github.com/maplibre/maplibre-rs/pull/00??) -- maplibre-rs Issue: #91 and otherrs [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/issues/91) +- maplibre-rs Issue: +[maplibre/maplibre-rs#186](https://github.com/maplibre/maplibre-rs/issues/91) +[maplibre/maplibre-rs#185](https://github.com/maplibre/maplibre-rs/issues/185) [ +[maplibre/maplibre-rs#186](https://github.com/maplibre/maplibre-rs/issues/186) # Summary [summary]: #summary -One paragraph explanation of the feature. +This RFC describes how we want to handle input in maplibre-rs. From a user perspective, input means that certain key +presses, screen touches or mouse movements translate into actions, which change how the map data is rendered. -Refract the input modules: -* A) Implement an event loop. Consider, in maplibre-gl-js the loop is part of the map-camera. (Issue #91) -* B) Check, if/what variations of winit, we need. -* C) Refract the splitting of the input controller functionality in modules/source-codes, may be like maplibre-gl-js (Issue #91) -* D) Define and document the function of the default input-controller, equaly to the input UI of maplibre-gl-js (Issue #186) -* E) Sepatate the input-controller in an extra Rust module/crate (Issue #185) +We call these inputs *input events*. These events can trigger so-called *actions*. Actions directly modify the state of +the renderer. -Should all this realy be in one RFC? Separate A) in an extra RFC? And B)? Oh! RFCs are ment for users of maplibre-rs only, not for internal development! That means, only C) and E) remains? +This RFC discusses various aspects of input handling: +1. **Event Loop** Acknowledge the presence of an Event Loop (processes *input events*) +2. **Platform Abstractions** Define how we can define abstractions over the platform's input system +3. **User-Friendly Inputs** Define what inputs end-users expect they can perform + + +Input aspects: +* **Event Loop** Implement an event loop. Consider, in `maplibre-gl-js` the loop is part of the map-camera. (Issue #91) +* **Platform Abstractions** Check, if/what variations of `winit`, we need. +* **Modularize Event Handlers** Refract the splitting of the input controller functionality in modules/source-codes, may be like `maplibre-gl-js` (Issue #91) +* **User-Friendly Inputs** Define and document the function of the default input-controller, equally to the input UI of `maplibre-gl-js` (Issue #186) +* **???** Separate the input-controller in an extra Rust module/crate (Issue #185) -maxammann: Is that maybe related to **Modularize Event Handlers**? # Motivation @@ -24,24 +35,51 @@ Should all this realy be in one RFC? Separate A) in an extra RFC? And B)? Oh! RF Why are we doing this? What use cases does it support? What is the expected outcome? -A) At the current version, each input module does the map move/slide itselve. -If we do it in the map-module, maintaining the inputs and writing a custom imput controler would be les complex. +### Event Loop + +At the current version, each input module does the map move/slide itself. +If we do it in the map-module, maintaining the inputs and writing a custom input controller would be less complex. +The map should offer an API, a function or a message queue to set the new map view, both immediately and like an interpolating move of the camera. We could do it like in `maplibre-gl-js`, there is only a single API, setting all values at once: position, angle, zoom. +The developer of a new control don't need to set or interpolate the camera but just calls that API. + +maxammann: An event loop is required because of the Rust ownership model we can not change the state of the renderer at an arbitrary point. Event a `Rc>` would not change that because we can never be certain if the render loop is currently borrowing the map state. + +maxammann: Therefore, we must acknowledge that the only way how we can change the map state is through events in an event loop. -B) Will the default winit work for all targets? - Todo: maxammann +### Platform Abstractions -C) The input module, which handles key presses and other inputs is quite cluttered. That means that, the logic in order to update the libraries state is quite complicated. We have to decide, how to split. Just one input module for key, mouse and touch, calling the map-API (see B) would be simpler. +Will the default `winit` work for all targets? - Todo: maxammann: No, it does not work for our usecase on iOS and Android right now. -D) The user of maplibre-rs sould "feel at home", have the identical UI expirience, while using the input controls. +### Modularize Event Handlers -E) Actually, a fork of the whole repository is needed to build a individual changed application. +The input module, which handles key presses and other inputs is quite cluttered. +That means that, the logic in order to update the libraries state is quite complicated. +We have to decide, how to split. Just one input module for key, mouse and touch, calling the map-API (see B) would be simpler. +At the moment, there is no concept, what input handler would do what inputs and actions. +If we do it like `maplibre-gl-js`, there would be one handler for one input type. +A keyboard handler would process all keyboard actions, change and set all values: position, angle, zoom. + +### User-Friendly Inputs + +The user of maplibre-rs should "feel at home", have the identical UI experience, while using the input controls. +If a user knows `maplibre-gl-js`, one should experience and find in the documentation exactly the same input UI. +All keyboard, mouse, and touch input actions should be described and coded equal to `maplibre-gl-js`. We then could extend the UI and i.e. add keys for rotation etc. + +### ??? + +Actually, a fork of the whole repository is needed to build a individual changed application. If we offer two extra rust crates for rendering and for control/UI, just the UI could be forked and changed. +The user of maplibre-rs should provide +1. a crate to make the map visible, but don't need to see its code, just a well described API, +2. a crate to control the map as an example to adapt the Rust code as wished, and +3. examples to build applications for different targets. -# Guide-level explanation ???Detailed design??? +# Guide-level explanation [guide-level-explanation]: #guide-level-explanation -Explain the proposal as if it was already included in the project and you were teaching it to another maplibre-rs user. +Explain the proposal as if it was already included in the project, and you were teaching it to another maplibre-rs user. That generally means: - Introducing new named concepts. @@ -51,26 +89,8 @@ That generally means: - If applicable, provide sample error messages, deprecation warnings, or migration guidance. - If applicable, describe the differences between teaching this to existing maplibre-rs users and new maplibre-rs users. -For implementation-oriented RFCs (e.g. for internals), this section should focus on how maplibre-rs contributors should -think about the change, and give examples of its concrete impact (= A,B,C) -A) -The map should offers an API, a function or a message queue to set the new map view, both imidiately and like an intrpolating move of the camera. We could do it like in maplibre-gl-js, there is only a single API, setting all values at once: position, angle, zoom. -The developer of a new control don't need to set or interpolate the camera but just calls that API. - -B) Todo: maxammann - -C) -At the monent, there is no concept, what input handler sould do what inputs and actions. If we do it like maplibre-gl-js, -there would be one handler for one input type. A keyboard handler would process all keybpard actions, change and set all values: position, angle, zoom. - -D) If a user knows maplibre-gl-js, one should expirience and find in the documentation exactly the same input UI. -All keyboard, mouse and touch input actions should be descripted and coded equal to maplibre-gl-js. We then could extend the UI and i.e. add keys for rotaton etc. - -E) The user of maplibre-rs should find -1) a crate to make the map visible, but don't need to se its code, just a well descripted API -2) a crate to control the map as an example to adapt the Rust code as wiched. -3) and examples to build applications for different targets. +TODO # Reference-level explanation @@ -86,12 +106,16 @@ This is the technical portion of the RFC. Explain the design in sufficient detai The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. +TODO + # Drawbacks [drawbacks]: #drawbacks Why should we *not* do this? +TODO + # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives @@ -100,6 +124,8 @@ Why should we *not* do this? - What other designs have been considered and what is the rationale for not choosing them? - What is the impact of not doing this? +TODO + # Prior art [prior-art]: #prior-art @@ -120,6 +146,8 @@ adaptation from other map renderers. Note that while precedent set by other map renderers is some motivation, it does not on its own motivate an RFC. +TODO + # Unresolved questions [unresolved-questions]: #unresolved-questions @@ -129,6 +157,8 @@ Note that while precedent set by other map renderers is some motivation, it does - What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? +TODO + # Future possibilities [future-possibilities]: #future-possibilities @@ -150,3 +180,5 @@ Note that having something written down in the future-possibilities section is not a reason to accept the current or a future RFC; such notes should be in the section on motivation or rationale in this or subsequent RFCs. The section merely provides additional information. + +TODO