Page MenuHome

XR Actions [part 2]: Actionmaps
ClosedPublic

Authored by Peter Kim (muxed-reality) on Apr 11 2021, 4:06 PM.

Details

Summary

Addresses the remaining portions of T77137 (Python API for Controller
Interaction), which was partially completed by D10942.

Adds an XR "action maps" system for loading XR action data from a
Python script. Action maps are accessible via the Python API, and are used
to pass default actions to the VR session during the
xr_session_start_pre() callback.

Since action maps are stored only as runtime data, they will be
cleaned up with the rest of the VR runtime data on file read or exit.

Diff Detail

Repository
rB Blender
Branch
temp-xr-actionmaps (branched from master)
Build Status
Buildable 16210
Build 16210: arc lint + arc unit

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
source/blender/makesrna/intern/rna_xr.c
1290

The verb should be last, so "action_set_create". I know this isn't what existing code in this file does (I usually prefer the verb first), it doesn't follow our convention. Better to follow it for new code though.

1319

).

1481

I would really prefer keeping this more dynamic, so that we don't have to hardcode how many controllers are available. But also, can you receive the same data via get_action_state()/get_pose_action_state()?

To avoid the harcoded controller count this just be a function. Maybe controller_state_get("location", 0), or controller_location_get(0). Or actually, wouldn't it be better to keep this more general, allowing you to pass the action name or such? But then we basically get get_action_state() again, so I'm a bit unsure too.

1541–1550

Multiple return values are supported with RNA_def_function_output(). In Python they can be received as tuple then. So this could return a (location, rotation) tuple.

1563

Avoid the "=" here, it reads weird. Could just be: "Optional OpenXR user path. If not set, the action will be applied to all paths"

1571

Same here, avoid the "=". E.g.: "Haptic duration in seconds, whereby 0 is the minimum supported duration"

1581

Avoid "=".

1601

Avoid "=".

source/blender/windowmanager/xr/intern/wm_xr_action.c
318

Can use LISTBASE_FOREACH_MUTABLE() here (just continue for non-matching items).

This revision now requires changes to proceed.Jul 22 2021, 5:21 PM

Also, could you please update the task description? Best to make it match the eventual commit message.

Hans Goudey (HooglyBoogly) requested changes to this revision.Jul 22 2021, 6:48 PM

Julian asked me to take a look at UI text in this patch. Here are some comments. Keep in mind that I don't have much context here, so I might have said something that doesn't make sense given more background knowledge.

source/blender/makesrna/intern/rna_xr.c
934

In a description it's probably important to give the information "Corresponding to what?"

Maybe "The action map item with the given name" is more specific?

984

Same comment as above

1058

Even for a more developer focused property, I would personally avoid using the word "Flag" in the UI. It's really much more "internal" than what we usually expose to RNA. The property generally has a more specific purpose. If it doesn't, arguably it should be split into a few more focused separate properties.

1101

If the description is the same as the property name, it should either be removed, or modified to provide a real description of the property.

This applies in a few places in this file.

1120

I would use "is" or "means" instead of "=" here

1128

There was some previous effort to standardize "ranges" in UI text: D9771

1258–1262

I don't think these property descriptions add anything, I would just remove them.

1361

Descriptions should read a bit more like prose, so you can have "The action depends" instead of skipping "The"

1376

Descriptions for boolean properties should be phrased as describing what happens when it is turned on.
In this case, something like "Apply haptics to the matching user paths" (I don't really know what that means)

1384–1404

My previous comments about "=" and the range in Ui text applies here.

1394

No need to repeat the property name in the description. Also, descriptions generally shouldn't state the default value of the property.

In this case, there's a real opportunity to be helpful here! Why not describe what the frequency means? Somethings per second?

1436–1447

Descriptions are repeating property names here as well.

1523

Property names should use title case, so "Action state" -> "Action State"

1548

"+" should be "and" here, since descriptions should generally be written like regular prose without contractions like this.

Move actionmaps from session settings to runtime data

Also addresses other review feedback.

Peter Kim (muxed-reality) marked 36 inline comments as done.Aug 4 2021, 12:04 PM
Peter Kim (muxed-reality) added inline comments.
intern/ghost/GHOST_C-api.h
1154

Renamed to GHOST_XrGetCustomdataArray().

intern/ghost/intern/GHOST_XrAction.h
68

Removed cleanups.

108

Using SubactionIndexMap.

source/blender/makesdna/DNA_xr_types.h
50–52

Moved action maps to wmXrRuntimeData.

80–82

The flags were merged into a single bit field for convenience, but they are now split into separate flags (eXrOpFlag, eXrActionFlag, eXrAxisFlag, eXrHapticFlag).

102

Although the action maps are not stored in files, I believe the DNA declaration here is necessary for the RNA functions, which interface with the XrActionMap collection/ListBase (see rna_def_xr_actionmap()/rna_def_xr_actionmap_items() in rna_xr.c).

If there's another solution though, please let me know.

145

Same as above (declaration needed for RNA).

source/blender/makesrna/intern/rna_internal.h
436–437 ↗(On Diff #39413)

Removed forward declared functions.

source/blender/makesrna/intern/rna_xr.c
408

Will revert this change here (unintentionally changed during rebase).

488–505

Refactored this to take in an XrActionMap struct pointer instead of individual parameters. This way, all the necessary actions/action spaces/bindings can be created with a simple Python function call. The XrActionMap should already be set up correctly after loading from the Python script.

818–821

Improved descriptions.

934

Renamed description.

1058

Renamed properties to avoid using the term "flag".

1101

Removed unnecessary descriptions.

1128

Standardized ranges based on D9771.

1290

Renamed functions to keep verb last.

1376

Oops, missed this.
It will be changed to "Apply haptics to the same user paths for the haptic action and this action".

1394

Missed this one too...

The "default frequency" was actually referring to the default haptic frequency of the OpenXR runtime, not the property's default value, but this was unclear.

Will be changed to "Frequency of the haptic vibration in hertz. 0.0 specifies the OpenXR runtime's default frequency".

1481

Replaced hardcoded controller accessors with controller_location/rotation_get() functions.

Controller pose actions get special treatment in that they need to convert the "raw pose"/action state returned by the runtime into one that takes into account eye offsets, base pose, navigation, etc.

At this point, I think we can assume that all poses will be controller poses, so for the time being I removed get_pose_action_state() since it wasn't very useful by itself.

source/blender/windowmanager/xr/intern/wm_xr_action.c
313

I could be mistaken, but I don't think I can use BLI_findstring() since the ListBase stores LinkData, not wmXrAction. So the "offset" parameter used for BLI_findstring() doesn't work.

Could make wmXrAction into a link-able struct, but it's actually stored in a C++ container in GHOST so I didn't want to cause confusion.

Actions are guaranteed to be unique though.

318

Using LISTBASE_FOREACH_MUTABLE().

source/blender/windowmanager/xr/intern/wm_xr_actionmap.c
112

Removed unused function.

Think we should add a rna_xr_api.c now that there are so many functions for XR RNA. This can be done separately though, even after the other patches are in if you expect too many conflicts from it.

source/blender/makesdna/DNA_xr_types.h
102

Issue is that this still will unnecessarily add the structs to SDNA. So the struct information will still be written to files, just no data for it.

If you want to avoid that like I said, you'd have to remove the RNA_def_struct_sdna() calls and do all the DNA struct access manually through callbacks. This would create a lot of boilerplate code in this case, so I'm not sure if that is a better alternative really. Checking with other devs.

source/blender/makesrna/intern/rna_xr.c
467–469

This function is super long. IMO logic in RNA callbacks should be minimal. If more advanced stuff is needed that should go to a dedicated module. So I'd suggest putting this to WM-XR. Even then I'd suggest splitting it in a few functions.

818–819

It confuses me a bit that a float input is represented as "button". A "button" to me usually has an on/off state only. Generally I'd prefer to keep the same name for RNA identifiers as we do internally, so "FLOAT" in this case. Any reason for not doing that? (Same for the other identifiers.)

832

Should be "location and rotation". A / usually implies "or".

834–837

Why not call this "VIRBRATION"? Makes it more direct and clear.

source/blender/windowmanager/xr/intern/wm_xr_action.c
313

You're right, in that case this is fine. One more reason to switch all this code to C++, which we should probably do rather sooner than later.

Peter Kim (muxed-reality) marked 21 inline comments as done.
  • Split action creation into separate functions
  • Rename RNA identifiers for action types enum
  • Update based on D12077 (add XrActionMapBinding)
Peter Kim (muxed-reality) marked 4 inline comments as done.Aug 5 2021, 8:56 AM
Peter Kim (muxed-reality) added inline comments.
source/blender/makesdna/DNA_xr_types.h
102

I read some of the discussion on #blender-coders. Was adding the struct to SDNA the preferred option?

source/blender/makesrna/intern/rna_xr.c
467–469

Ok, makes sense. I split the function into separates ones again to reduce complexity (action_set_create()/action_create()/action_binding_create()).

818–819

Now using same action type identifiers for RNA as internally. There wasn't a particular reason for doing otherwise.

Peter Kim (muxed-reality) marked 2 inline comments as done.

Update based on D12073 (controller data refactor)

Looks good. Mostly smaller picky comments inline. One thing I noticed is that vector2f appears in UI text in a few places. Maybe it would be better to use 2D vector? That's more consistent with other areas in Blender anyway.

source/blender/makesdna/DNA_xr_types.h
176

From a brief look at how this is used it looks a bit more like an active index than a selected item, is that right? If so, I'd call it active_item_index or something like that.

source/blender/makesrna/intern/rna_xr.c
1144

Could just make a new sentence here: "Haptic duration in seconds. 0.0 is the minimum supported duration)." "whereby" just sounds a bit odd to me.

source/blender/windowmanager/xr/intern/wm_xr_actionmap.c
382

Titles here should read like comment text, so Actionmap -> Action Maps

395

This comment is a bit obvious too.

422

Not sure the point of this comment given the name of the function. If you want to keep it, I'd suggest putting it above the function like:

/**
 * Ensure unique name among all action maps.
 */
void WM_xr_actionmap_ensure_unique(wmXrRuntimeData *runtime, XrActionMap *actionmap)
This revision is now accepted and ready to land.Aug 5 2021, 3:44 PM

Use "2D vector" not "vector2f" in UI, adjust comments

Peter Kim (muxed-reality) marked 6 inline comments as done.Aug 5 2021, 4:28 PM
Peter Kim (muxed-reality) added inline comments.
source/blender/makesdna/DNA_xr_types.h
176

You're right that it is used as an "active index" internally, however I didn't want to cause confusion since "active" has another meaning with respect to action maps ("active" means that the action map is the one currently used for the VR session).

This is similar to the landmarks in the Python add-on, where there is both a selected landmark (to which UI edits are applied) and an active landmark (the one used for the VR session): https://docs.blender.org/manual/en/2.83/addons/3d_view/vr_scene_inspection.html?highlight=virtual%20reality

This revision was automatically updated to reflect the committed changes.
Peter Kim (muxed-reality) marked an inline comment as done.