View Full Version : ComRing: I'm just not getting it.

Ryan Roye
11-12-2014, 07:38 PM
I've been working to try and find ways to automate applying item shapes to items... even if I did manage to put something together, I don't understand the patterns or methods of use revolving around comring. Comring is putting me through a mental loop.

Right now, from what I can gather comrings basically operate as "lists"?

This code:

myvar = lwsdk.pris.itemshapedata()
print myvar


('p', 'p', 'p', 'd', 'd', 'd', 'i', 'i', 'i', 'i', 'i', 'f', 'f', 'f', 'f', 'f', 'f', 'f', 'f', 'f', 'd', 'd', 'd', 's:120', 's:120', 's:100', 'p', 's:256', 's:256', 'i') ... i'm not quite sure how this fits into the Item Shape options dialogue as this listing returns a lot more values/variables than the dialogue actually contains. There are 23 changable parameters in the Item Shape dialogue, yet the itemshapedata function yields 31 parameters??

and I'm assuming this is the "format" which the item shape expects any data it receives to be in. Where I get stuck is how to apply desired changes to an itemshape... based on my lscript knowledge theoretically I should be using:

ringAttach(char topic, LWInstance pidata, PyObject function)

... what's a "topic" and "PyObject" function? Where can I find information about this stuff? I'm quite lost here.

12-05-2014, 01:12 AM
Heyo - I'm super naive on the SDK's, I don't really get what you are doing here, and I'm fairly naive with Python, but when I want to learn a specific detail in the SDK's I search the online SDK docs (https://www.lightwave3d.com/lightwave_sdk/ and http://static.lightwave3d.com/sdk/11-6/python/index.html) via Google using this special Google search phrase:

site:static.lightwave3d.com/sdk/11-6/python KEYWORD

Where KEYWORD is what I'm looking to learn about. You may already know this, how the "site:" prefix is an awesome feature of Google's focusing a search on a site or just a folder. Paste it into Google search, and maybe change the URL (keeping how the "site:" thing is formatted) but using a specific website and voila, instant site-specific-searching! (NOTE how I stripped the 'index.html' part from the Python SDK URL...Google seems to require "site:" queries formatted carefully.)

Unfortunately 'topic' is used again and again by the LW Python documentation's navigation - so, :P. I did read in the com ring section (more below) however 'topics' are akin to channel names, like if you have your radio tuned to your local inclement weather channel notification station, then you'll hear from NOAA whenever there's some nasty storm. The 'topic' is merely the name of the station...like "WKPR". It looks like LightWave supports arbitrary topic names. I wonder if a list of topic names is exposed by the app anywhere. Could be informative.

For PyObject, that's just a pointer to a bit of Python code+data, it's an opaque handle that can point to potentially any little / big thing in the app. Its contents vary on the event; it may be empty or it may not, check the docs.

(This is me catching up, welcome to ignore.) Looking at the Communications Ring (LWComRing) http://static.lightwave3d.com/sdk/11-6/python/globalcomring.html, http://static.lightwave3d.com/sdk/11-6/html/globals/comring.html, and the "ring_test.py" sample I gather:
* it's a mechanism for inter-plugin communication
* it supports unlimited discrete topical channels of communications keyed by a string
* it broadcasts events serially to all subscribers of a given channel

"List"-ness of the Com Ring seems to be for reals - ie. LW appears to notify subscribers of a given topic via the com ring in some order, serially (not multiple subscribers in parallel), and it stops notifying subscribers of that event once all the listeners have had that event / message relayed to them. I don't get why it's considered a Ring, but that could be like an implementation detail. So say there's three subscribers to a topic, listeners A, B, and C, and the topic is "snakes". If "B" decides to send a simple event like maybe just the number 7 ... then the com ring might honor its "list"-ness by sequencing delivery, and "ring"-ness by starting from whereever "B" happens to sit in the list and wrapping around from end jumping to beginning of the list, stopping notification before it reaches the sender "B" again. So B-send, C-receive, A-receive, would be the sequence for a list + ring data structure, I'm guessing.

Soooooo - I don't have much to say about the 'p' 'p' 'p' 'p' part of your posting, perhaps someone else does? But I hope the musing about the com ring overall is helpful. :thumbsup:

12-05-2014, 01:30 AM
So, the "Item Shape" dialog in LW appears to be a thing to customize Nulls. Looking now at page 409 of the 2015 PDF docs.

I googled the SDK docs for itemshape & "Item Shape" and I see some more stuff here http://static.lightwave3d.com/sdk/11-6/html/filefmts/RigFileFormat.html - in fact I see one "data card" having 32 data items, pretty close to 31 that you talk about seeing. The 32-element data card, (which I guess is coming through the com ring via the PyObject?), however doesn't seem to have as many character-datatype fields as your 'p' 'p' 'p' ... finding. It's got a bunch more numerical fields. So I'm not convinced I found the matching SDK definition of what you're encountering. :/

Also, depending upon the way the SDK's entity names have been chosen, this item shape I found might be a different thing than what you're looking for, from the Item Shape dialog. Yeah I am still super naive on actually using the SDK. Woot here is to hoping you aren't, especially with your Lscript experience.

12-05-2014, 01:50 AM
Another random finding / tid-bit: http://static.lightwave3d.com/sdk/11-6/python/pris_common.html#lwsdk.pris.itemshapedata generally documents that object you yanked out of the app and printed.

What is it that you're seeking to do, I need to ask? Is it to pull data from a given object's item shape?

Hooo - a mother lode, sort-of. http://static.lightwave3d.com/sdk/11-6/html/lscript/v27.html I wonder why Google search did not find the LScript docs? I should ask NewTek / LW3DG to update their sdk webpage to explicitly link to the LScript documentation since it is inaccessible otherwise, unless you Guess the URL...which I did. :D

Anyhoo the 'comringencode' LScript function is documented here. I'm getting sleepy and not really comprehending what I'm reading here - specifically I don't know if the 'p'p'p'p'p' thing was merely a Key (like you see on a map or diagram) illustrating how to pack data for sending "item shape" datastructures from one plugin to another - I am guessing it is a Key but I don't see how to actually send the Data. Good luck, again, star fighter.

Ryan Roye
12-07-2014, 01:22 PM
I did actually see those docs before making this post; they just fail to explain clearly how to use the function. They do everything but tell the user what they need to know to get something useful out of that... it's like explaining every little part about a machine but not saying what it does or how its used. Very frustrating from a learning standpoint.

In any case, I gave up on comring as I later discovered that they added a function called "Generic_AddItemShape" with arguments that lets you add item shapes to things via scripting. For anyone else interested, here's all the arguments available for the command (thank Matt G. for this info!):

Generic_AddItemShape (arguments or flags, space separated and case sensitive)

Replace="True|False" Shape="SHAPENAME" Axis="0|1|2" Scale="SCALE" Label="LABEL" LineTo="ItemID" Justification="0|1|2" Filled="True|False" XRay="True|False" UseSelectedColor="True|False" UseUnselectedColor="True|False" UseTextColor="True|False" Opacity="0-1" SelectedColor="0-1 0-1 0-1" UnselectedColor="0-1 0-1 0-1" TextColor="0-1 0-1 0-1")

EXAMPLE COMMAND (in lscript commander) :

Generic_AddItemShape Replace='True' Shape='Pyramid' Axis='2' Scale='0.5' Label='DisplayTextHere' Justification='0' Filled='True' XRay='False' UseSelectedColor='True' UseUnselectedColor='True' UseTextColor='True' Opacity='0.5' SelectedColor='1 1 1' UnselectedColor='0 0 0' TextColor='1 1 0'


- In LW 11.6.3 and earlier, all of the checkbox and field flags, including opacity, do not work with this command. I have reported this error but I wouldn't expect it to be a priority fix. You can, however, use the "ItemColor" command to at least be able to color the nulls.

- The LineTo flag doesn't appear to be working in LW 2015 and earlier. It incorrectly points to the scene's origin instead of to the item specified.

12-07-2014, 11:15 PM
Thanks. I agree that the documentation isn't always very direct in helping you.

12-08-2014, 02:51 AM
I did actually see those docs before making this post; they just fail to explain clearly how to use the function. They do everything but tell the user what they need to know to get something useful out of that... it's like explaining every little part about a machine but not saying what it does or how its used. Very frustrating from a learning standpoint.
That particular STYLE of presentation is endemic throughout the scripting dox: lots of detail, no useful overview. It's almost like a tic or something.

It's like they were following an outline template that had the first line missing. I noticed it repeatedly back when I was struggling with the dox.

12-08-2014, 04:44 PM
The "Why". It's very often overlooked in technical writing; it is pretty hard to keep a "Why" document consistent if you're the author of the code and the documentation, IMO! It's like rewriting the code.

Good to hear you found out about Generic_AddItemShape.