|
|
What does a plugin n00b need?
About Truespace Archives
These pages are a copy of the official truespace forums prior to their removal somewhere around 2011.
They are retained here for archive purposes only.
What does a plugin n00b need? // SDK, Plug-in & 3rd Party Area
Post by kena // Aug 29, 2008, 3:10pm
|
kena
Total Posts: 2321
|
OK - I've downloaded the SDK. I've looked at the files....
now what?
Is there a program I need to use to construct a plugin?
Is there any kind of beginner's tutorial that I need to look at?
I would really like to learn how to do this, but I would really like a bit of direction to start with.
TIA |
Post by frootee // Aug 29, 2008, 3:37pm
|
frootee
Total Posts: 2667
|
Hi Kena. Check this post in the tech forum. Basically You need Visual Studio 2005/2008. If you do not have Studio yet I'd suggest going for 2008.
http://forums1.caligari.com/truespace/showpost.php?p=72399&postcount=11
There are a couple good documents with the SDK. Check the Examples folder for the files.
Specifically, the RsExamplesPlugin.doc document discusses the simpler examples. Helloworld is the simplest, which is run from the command prompt.
With Visual Studio, I would suggest adding a breakpoint somewhere in the code at, say, the CrsCmdFactory::CreateInstance function call.
Then, as the document states, start truespace, then in Visual Studio, select Debug->Attach to Process. Select ts7.exe from the list.
Then when you type the command in the Truespace command prompt window, you will be immediately taken to that breakpoint in the code. From there, you can single step through the code using the F10 button, and F11 to step into a function, and Shift-F11 to step out of it.
And of course, ask questions! A handful of beta testers have been investing a considerable amount of time on understanding the SDK and getting plugins working. So we'll help wherever we can.
Froo |
Post by remnar // Aug 29, 2008, 4:39pm
|
remnar
Total Posts: 105
|
This new SDK is not newb friendly. In fact it is a lot more complicated and complex compared to the old one which is more straight forward to understand. Then again I'm not the smartest person, so if you're bright and can catch onto new technology concepts quickly, then I suppose you won't have a problem. The plugin project is still a dll with ATL statically linked. However when I'm looking at code and includes, and it's like looking at a new language based on c++. I'm not a experienced coder, I just do this stuff as a hobby.
I can tell from reading the documentation and watching the video, that this system can be very powerful in connecting people together using a 3d world interface instead of a 2d one. Kind of reminds me of the Home Ps3 project. A similar system could be made with Ts7. |
Post by weshowe // Aug 29, 2008, 4:41pm
|
weshowe
Total Posts: 23
|
Well, I got the RsSamplePlugin compiled and installed. The compile (VC8) went flawlessly.
The installation took more study than I thought necessary. Is there an automatic installation option (thinking through distribution)?
I am wanting to make a simple 3D File Importer. I can manage the entire file read/parse process and I found the example heightmap that shows converting the data to a mesh.
What I want is to define a link between the (modified) RsSamplePlugin and my code. There has to be some way I can create a menu or button, and when the user clicks that my code executes, interacts with the user and adds a mesh.
Hints?
<* Wes *> |
Post by Electric Jim // Aug 29, 2008, 5:54pm
|
Electric Jim
Total Posts: 98
|
I see that Microsoft offers somewhat-limited "Express" versions of its various programming packages/languages ("2008" versions of Visual Basic, C++, and C#) for free, with no limitations on commercial use of the resulting software. Could anyone say whether any or all of these "Express" versions would be sufficient to produce plugins for tS7.6? Thanks.
For reference, here are a few relevent links:
Main "Express" web page:
http://www.microsoft.com/express/
Feature comparison for different versions:
http://msdn.microsoft.com/en-us/vstudio/products/cc149003.aspx
(Clicking the "[Expand All]" link on the page gives a huge table of featues and indicates which features are supported by which products.) |
Post by TheLion36 // Aug 29, 2008, 10:53pm
|
TheLion36
Total Posts: 36
|
I think the TS 7.6 SDK is based on ATL (A template based COM wrapper). The Express Editions of Visual Studio don't support ATL, so that would be a no... :( |
Post by Jack Edwards // Aug 30, 2008, 12:14am
|
Jack Edwards
Total Posts: 4062
|
Yeah, because it's ATL based you need VS2005/2008 Standard or Professional edition. The cool thing is that having Express Edition qualifies you for "upgrade" pricing. ;)
Also because it's ATL your interface classes that you create will need to have unique GUIDs. That means if you adapt one of the examples as your new plugin, you will need to go through and change all the GUIDs to be unique that way they don't conflict with GUIDs registered to the examples or other plugins that you made. There's a tool built into VS for generating new unique GUIDs.
The learning curve for ATL is VERY steep, but once you get over it, the SDK is not that difficult to use. A couple of things that will help is learning how to use and convert BSTRs and CComVariant types.
You can use custom ATL dialogs, but you need to use built in Windows controls when building your dialog because MFC doesn't work with ATL the way the plugin DLL project is set up. (At least I was not able to find a way to make it work with MFC. :o)
It's also important to keep in mind the threaded nature of the application when designing your plugin. So this is definitely not the simple "C" style API of old, but you have the same power as the TrueSpace developers to add new functionality to the application. |
Post by frootee // Aug 30, 2008, 2:22am
|
frootee
Total Posts: 2667
|
What I want is to define a link between the (modified) RsSamplePlugin and my code. There has to be some way I can create a menu or button, and when the user clicks that my code executes, interacts with the user and adds a mesh.
Hints?
<* Wes *>
Hi Wes.
You need to create a dialog.
In the Solution Explorer of Visual Studio, right click one of the folders:
Include, Source, or Resource Files (Choose Resource Files if it exists but the others should be ok)
Hover over Add, then Select: Resource.
Choose Dialog, then New.
A dialog will be created for you, as well as the source and header files.
Now you need to change the name, add buttons, etc.
A Toolbox should open in your Studio workspace. That's where you change the name, and add buttons.
To 'connect' the dialog to an example, you have to add some part of the example's function set to the button handler.
So for the TopologyExample COMMAND to get called, you would put this in the button's OnBnClickedOK handler (I am assuming OK is the button name); my dialog is called atldlg:
LRESULT Catldlg::OnBnClickedOK(WORD /*wNotifyCode*/, WORD /*wID*/, HWND /*hWndCtl*/,
BOOL& /*bHandled*/)
{
// TODO: Add your control notification handler code here
//create TopologyExample command
CComPtr<IRsCommand> spCmd;
HRESULT hr = CRpExamplesPlugin::CreateCommand(DEF_GUIDNAME_PTR( IRcTopologyExample),
&spCmd);
if (FAILED(hr))
return hr;
//execute it
return CRpExamplesPlugin::ExecuteCommand(spCmd);
}
This is essentially the same thing being done when you type on the command line: examplesplugin.topologyexample()
For your importer, you would do something similar.
Froo |
Post by weshowe // Aug 30, 2008, 5:42am
|
weshowe
Total Posts: 23
|
Thanks for the hint.
I have made dialogs, but didn't know that was the starting point.
<* Wes *> |
Post by frootee // Aug 30, 2008, 5:52am
|
frootee
Total Posts: 2667
|
You're welcome Wes.
Yeah, it took awhile to figure that one out.
I believe I learned that just by setting breakpoints in the code, running in debug mode and attaching to the ts7.exe process.
Then when I typed in the command, like examplesplugin.topologyexample, I went straight to the breakpoint; then I could single step
through the code til I found what I needed.
The SDK document does a really good job of explaining things.
Here's another tip:
items which start with IRn in the documentation and code are Nodes.
When you create these, one way to access them is via a jscript command, when you do this:
Node.Create('
as soon as you type that first single quote, you will see the autocomplete feature activate. Scroll down the list to confirm your node has been added. For the Heightfield and Topology example (I think), you can see it listed in the Examples Plugin/ series. These are already available once you load the example plugin. This is one way to confirm that your node creation worked. Also, make a note that string that shows up in the autocomplete before your node name. In this case, Examples Plugin. Look in the code that was used to create this node. You will see that same string listed in the code. That's another way to get a bit familiar with how this thing works.
Items which start with IRf are Function Sets.
Items which start with IRc are Commands.
Items which start with IRi are Interfaces.
Items which start with IRp are Packages.
This information will be important as you study the documentation and code.
I suggest you study the code and the documentation at the same time. In the docs, make the 'classes' html file (The Class Index) your starting point. Class members page is also a quick way to look up functions. |
Post by TheLion36 // Aug 30, 2008, 6:00am
|
TheLion36
Total Posts: 36
|
Been trying to get my head around the examples all day and so far I've had no luck... :( I've never done any ATL programming before and so far its a bit weird.
If I create a new ATL Project in VS2008 I have a few forced files that the examples dont seem to have which makes it highly confusing. (Added a screenshot of my Solution Explorer after starting a new ATL Project).
Another thing I miss is a barebone example of a plugin. All the plugin examples are fairly big/complex. I know the RsExamplesPlugin has the HelloWorld example but its not stand alone and part of a larger complex framework that makes the helloworld example very complex as well (Its hard to know from that example where to start and what is needed and what isn't).
I need a good place to start, a barebone example of a plugin with only the bare essentials needed to be accepted as a plugin by Rosetta.
Any usefull/appropriate links on ATL development would also be very much appreciated, Followed a 7 step tutorial on MSDN to make an ActiveX object that draws a polygon but it doesn't explain that much besides the wizards. (http://msdn.microsoft.com/en-us/library/3ax346b7(VS.71).aspx). |
Post by frootee // Aug 30, 2008, 7:04am
|
frootee
Total Posts: 2667
|
Hi Lion.
There is the RsSamplePlugin folder as well. That is all by itself. I have not looked at it yet but I believe it is a skeleton plugin.
I would recommend using the ExamplesPlugin as a start. Create a copy of that entire folder, and work from your copy.
if you look at the solutions explorer for the examples plugin, you will see that it is well organized. Each example is self contained. So you first have a folder called Examples. In that folder, you have a folder for the helloworld example, another for the topology example, etc.
Then, you have the Factories folder, the Header Files folder, and finally, the Source folder.
So as an example, for the hello world example, you need the hello world folder (it contains the cpp and h files), the Factories, and header files and resource files folders. The rest, you can trash. This is why I say, make a copy of the examples plugin folder, since if you deleted stuff from the original, you'd have to download or unzip from scratch.
I highly recommend experimenting with the examples, making changes, calling one from another, etc. to get an understanding of how things work with the SDK. As opposed to trying to do that, and creating an ATL program from scratch.
Try changing the 'Hello World' text to something else.
Try calling the topology example from the Hello World example. You need to know the right function in the Hello World command to do that (it is the CRcHelloWorldCmd::Execute(void) function. |
Post by weshowe // Aug 30, 2008, 8:35am
|
weshowe
Total Posts: 23
|
OK, so I have scaled myself back to modifying the examples.
I copied the examples project.
I easily found the "Hello World" string, in a call to Message Box()and modified that.
I easily compiled the entire example.
Having done it once, I installed and loaded the plugin (.rsx).
Now, here comes the hard part for me... How The Heck Do I Run It?
There is no button, no menu, no indication I can find outside of the additional item in the package manager that indicates I can do anything with this loaded code.
This must seem pretty elementary, but I am completely lost at the moment.
<* Wes *> |
Post by frootee // Aug 30, 2008, 9:49am
|
frootee
Total Posts: 2667
|
No problem weshowe. In the Examples folder there is a document called RsExamplesPlugin. It explains the functionality, as well as debugging methods.
For the hello world example, and all the Command examples, you execute them from the Truespace command line:
In the toolbar, locate the plugin manager icon. Click and drag that. A flyout window appears. Choose the C:\ prompt icon.
A command prompt window appears. In this window, type:
examplesplugin.hellworld()
The parentheses are not necessary.
You will see your command display the dialog. |
Post by weshowe // Aug 30, 2008, 10:36am
|
weshowe
Total Posts: 23
|
First, thank you very much. I can start with this and see if I can master interfacing to rosetta.
For a little humor:
I cut and pasted the command from your message. When it didn't work I looked carefully and noticed you had typed "hellworld" in it. On the odd days, I feel like that, too. :p
<* Wes *> |
Post by frootee // Aug 30, 2008, 10:46am
|
frootee
Total Posts: 2667
|
haha! Sorry about that Wes! :D
If you get tired of using the command line to type that long name in, two exercises you can do:
1. Change ExamplesPlugin to something shorter, like ep (you have to study the code to make sure you replace stuff correctly)
2. Just go into Link Editor (LE) and add a jscript command.
For the jscript command code, type:
ExamplesPlugin.HelloWorld();
Press the red arrow to commit your changes.
Then, change the tab of the jscript command to Control, and press the Start button.
Your window will then appear.
I got tired of typing that long long command line all the time. :D |
Post by weshowe // Aug 30, 2008, 12:29pm
|
weshowe
Total Posts: 23
|
I am struggling along now adapting code I wrote for another project to be compatible with the way this project is set up. Making sure it works with UniCode is one of my major issues.
I don't think that I want to leave the interface that way, people want stuff they can click on, not things they have to type. I will worry more about that after I have meshes appearing in trueSpace, though.
Thanks again for getting me started.
<* Wes *> |
Post by frootee // Aug 30, 2008, 4:27pm
|
frootee
Total Posts: 2667
|
understandable Wes. And hey, you're welcome! :D
Look at the RsAnim plugin example. It is in a folder all by itself; it is not part of the RsExamplesPlugin suite.
When you load that plugin, a toolbar is created automatically. With that plugin, you can click on the icons in the toolbar to perform various actions. That's probably the best place to start for performing functions purely from mouse clicks.
EDIT:
OH BTW... Unicode..... so far I have had to use the multibyte char set with the examples and the plugin I'm developing.
So question... what's the difference between the two? I assume multibyte allows you to use multiple languages and such? |
Post by weshowe // Aug 30, 2008, 5:21pm
|
weshowe
Total Posts: 23
|
UniCode is a Microsoft standard with two-byte characters, to support Korean and such. It is different than the MBCS. It is one of the first page of properties that are set in Visual Studio.
It vastly complicates some things, particularly using GetOpenFileName() and MessageBox(). I did find that I can compile the Examples plugin without UniCode, except I had to rework the code for a few calls to MessageBox(). I made it work, so UniCode is not required to make a plugin work.
For what I am doing I have two parallel learning challenges, one is understanding the ATL methods well enough to make a plugin shell that works like I want (and that would be much like the ANIM one) but without a lot of extra baggage in it (like the examples). I am really far from this because I do not understand the process of how the ATL is built between DllMain() and CRcHelloWorldCmd::Execute(void).
My other learning curve is learning the proper way to present my arrays of vertices and faces as the "streams" that 7.6 wants. But I made good progress today, because I got my code to compile and load packaged as a plugin, I just need to connect the dots now.
<* Wes *> |
Post by snewnham // Aug 30, 2008, 9:16pm
|
snewnham
Total Posts: 14
|
UniCode is a Microsoft standard with two-byte characters, to support Korean and such.
Actually, Unicode is an industry standard, not a Microsoft standard. Its origins, as with many IT technologies, lie with work begun at Xerox (as well as, in this case, Apple). Whilst Microsoft adopted Unicode when they created Windows NT, they did not invent Unicode nor do they control it. Microsoft is a member of the Unicode Consortium, as are many of the major IT companies (IBM, HP, Sun, Adobe, etc.).
Unicode is able to represent a vast array of characters / written symbols - not only the Roman, Greek, Cyrillic, Hebrew, Asian (Chinese, Japanese & Korean), Arabic, Sanskrit, Thai & Tibetan character sets (to mention a few) but also more obscure examples such as Egyptian hieroglyphs, Sumerian Cuneiform, runes, etc. and even, believe it or not, Klingon (albeit via Unicode's Private Use Area facility).
The ability to display all these characters depends, of course, upon the implementation. Microsoft Windows can display most of the commonly used, modern characters (though you may require additional character sets to be installed, depending upon which localisation of Windows you have installed) - but the more obscure / specialist sets are not made available by Microsoft (though they may be sourced elsewhere). |
Post by frootee // Aug 31, 2008, 2:49am
|
frootee
Total Posts: 2667
|
My other learning curve is learning the proper way to present my arrays of vertices and faces as the "streams" that 7.6 wants. But I made good progress today, because I got my code to compile and load packaged as a plugin, I just need to connect the dots now.
<* Wes *>
Hi Wes. Refer to the RnHeightFieldExample. It demonstrates the use of vertex streams, UVCoord streams, normal streams, triangle streams, and mesh creation. It constructs the mesh geometry using these streams, along with an input bitmap.
You'll probably need connectors as well. The connector example demonstrates that. Passing parameters? the parameters example is where to look. :)
For a shell, refer to the RsSamplePlugin folder. It is at the same folder-level as the RsExamplesPlugin folder, which holds all the examples you're currently viewing. |
Post by Jack Edwards // Aug 31, 2008, 6:48am
|
Jack Edwards
Total Posts: 4062
|
Also if you copy one of the existing examples to make your own plugin, you need to change all the GUIDs so that you don't have any conflicts with existing plugins. TrueSpace actually won't load a plugin that has a duplicate GUID with one already loaded.
When distributing your plugin you will need to have Visual Studio create an installer so that the GUIDs will be registered into the users registry during the installation. |
Post by jayr // Aug 31, 2008, 12:56pm
|
jayr
Total Posts: 1074
|
what is the difference between standard and Pro versions of visual basic? Can you make plugins for truespacewith the Standard version? |
Post by Jack Edwards // Aug 31, 2008, 1:14pm
|
Jack Edwards
Total Posts: 4062
|
You need Visual Studio (C++) at least until someone writes a VB wrapper for the SDK.
The Standard version of VS does work fine with the TS SDK. (That's what I'm using.) |
Post by jayr // Aug 31, 2008, 11:17pm
|
jayr
Total Posts: 1074
|
sorry i ment Visual studio, Visual basic must have been a flashback to the free versions you used to get on pc magazines. |
Post by jayr // Sep 2, 2008, 11:16am
|
jayr
Total Posts: 1074
|
well i took the plunge, started learning C++, i've been meaning to do it for a while now..... Let see how far i get before my head explodes :o |
Post by kena // Sep 2, 2008, 3:12pm
|
kena
Total Posts: 2321
|
lol - I cannot afford visual studio even with the discount just now, so I'm kinda stuck... hopefully soon.
hopefully by then there will be some tutorials out on how to do this thing. |
Post by weshowe // Sep 2, 2008, 5:39pm
|
weshowe
Total Posts: 23
|
I am probably starting too long at the wrong things.
But I am having trouble getting my code hooked up.
I dropped back to attempting to place a simple cube on the screen. To do this I replaced the portions of the code in the examples plugin RnHeightField.cpp. After recompiling, I tried to run this with the command "ExamplesPlugin.HeightField" (in the command window).
I get no cube, no error messages, nada. This is in contrast to "ExamplesPlugin.HelloWorld" which I can execute my code, but the function lacks any parameters, and it would appear I need "IRsDataCache *pDataCache" (and without having this I crash and burn trying to place the data into trueSpace).
I have all the online docs, and while not perfect, they are useful. I have readmes that tell me how to install the plugin, but how do I run this? I am guessing perhaps I am torturing the HeightField in the wrong way, and not exectuing anything. But the "command window" is fundamentally flawed if it cannot even return a "?" when you type something unrecognizable.
I have rambled on long enough tonight. So, how do you make the height field example plugin execute?
<* Wes *> |
Post by frootee // Sep 3, 2008, 2:29am
|
frootee
Total Posts: 2667
|
hi wes. Take a close look at the .cpp for each example. RnHeightField starts with Rn. RcHelloworld starts with Rc.
Rn = Rosetta NODE (RnHeightField)
Rc = Rosetta Command (RcHelloworld)
Rc Commands can be executed from the command line.
Rn Nodes can be created using the command: Node.Create('
So as an example, add a jscript command to the LE, and type in:
Node.Create('
note that, as soon as you type that first single-quote, a dropdown list will appear.
Scroll down to the Examples section. you will see your node in that area. You will also see the other nodes available in the examples plugin, since they are also part of the example plugin.
HTH!
Froo |
Post by weshowe // Sep 3, 2008, 8:20am
|
weshowe
Total Posts: 23
|
Rn = Rosetta NODE (RnHeightField)
Rc = Rosetta Command (RcHelloworld)
Well, there is a method in the madness, then. I can see (and modify and compile) the C++ files. But I am having trouble understanding how the code is tied into interacting with the application.
So as an example, add a jscript command to the LE, and type in:
Add a who to a what?
Does that mean type in Node.Create(' in the C: prompt?
Or is the LE a different popup item?
<* Wes *> |
|
