Page 1 of 17

Hikari (v0.3)

Posted: Sat Jun 07, 2008 10:31 pm
by ajs15822
Howdy again! :D

Image
(Fancy Hikari Logo)

Meet Hikari (hee-kah-ree), a small yet powerful library that makes it easy to use Flash content in Ogre3D. The possible applications include:
  • Create the interface for your game in Flash
  • Play Flash movies as cut-scenes in your game
  • Embed Flash mini-games in your game
  • Combine Flash with 3D to make novel interfaces
  • Use Flash for animated decals on 3D models
And it doesn't stop there! I'm excited to see what other uses people will dream up.


Basic overview of using Hikari:
  • Step 1) Design your interface in Flash
    Step 2) Export to SWF files.
    Step 3) Create the HikariManager.
    Step 4) Create a FlashControl for each SWF using the HikariManager.
    Step 5) Load the SWF files into each respective FlashControl.
    Step 6) Bind callbacks in ActionScript and C++.
    Step 7) Inject mouse input into the HikariManager.
    Step 8) Call HikariManager::update from your update loop.
Features:
  • Efficient updating with dirty-rectangling
  • Full transparency support
  • Load the Flash ActiveX control from the registry or a local file
  • Create a FlashControl as a movable overlay or pure material
  • Bind C++ functions to handle function calls from ActionScript
  • Call ActionScript callbacks from C++
  • Support for communication of basic ActionScript types (null, boolean, number, string)
  • International string support
  • Minimal impact on application size
License:
  • Hikari is licensed under the Lesser GNU Public License (LGPL) with one stipulation: if you use it, tell me about it! :D

Image
(Screenshot from the v0.2 Demo)


Demo:
  • The demo is extremely simple (I began learning Flash about 4 days ago) but is certainly enough to demonstrate the basic implementation. Play with the slider and color-picker and drag around the FlashControls by holding down the right-mouse-button.

    Download the Hikari Demo (v0.2)
Source: Forums:
  • For discussion and support of Hikari, you may wish to visit our forums.
Documentation:
  • The API headers are fully documented using Doxygen-compatible comments-- I will generate the online docs later.

    For articles and tutorials about use of Hikari, see the Hikari Wiki.

How is Hikari implemented?
When you create a FlashControl using the HikariManager, here's what happens:
  • The Flash ActiveX control is loaded (either from Flash.ocx in the working directory or from the registry).
  • It is embedded into a Windowless OLE site.
  • An event handler is bound to the OLE object to handle various Flash events.
  • Invalidations are caught, the dirty area is expanded.
  • Mouse input is injected by translating it into native window messages which are then sent directly to the Windowless site.
  • Keyboard input is handled by directing all keyboard messages (using a message hook) to the focused FlashControl. (To accommodate complex keyboard input)
  • During a global update, if a FlashControl is dirty, the dirty area is rendered and merged with an internal buffer, which is then blit to a dynamic texture using Ogre3D's facilities.

Have fun! <3

Posted: Sat Jun 07, 2008 11:03 pm
by betajaen
Well done! We've come along way from BetaGUI and CEGUI and it shows.

Posted: Sat Jun 07, 2008 11:40 pm
by madmarx
It seems that the fps is quite bigger than Navi's.

Well done!

Posted: Sun Jun 08, 2008 12:30 am
by Murphy
Yay! Now I have something FUN to do today!

Posted: Sun Jun 08, 2008 1:02 am
by Brocan
That's great !!! Amazing !!! I'll will use it instead CEGUI for my next project :D

Posted: Sun Jun 08, 2008 1:57 am
by metaldev
holy crap ajs. :!: :!: :!: :!: :!: :!: :!:

Posted: Sun Jun 08, 2008 2:26 am
by steven
Bravo!

Just one question: what is the licensing behind Flash and ActionScript?
Is it lgpl compatible?

I tried to find info but... well I don't have days to read all this:
http://www.adobe.com/products/eulas/ ;)

Posted: Sun Jun 08, 2008 2:28 am
by Zeal
I never lost faith sir, I knew one day you would ride down from the heavens on a cloud of glory, and bestow upon us all, FLASH SUPPORT!

Posted: Sun Jun 08, 2008 2:51 am
by Praetor
This use of Flash is not against any terms of use from Adobe. They are, however, not liable for it. They do not "support" it in any way, so it means we are all on our own.

If you make an app that uses Flash and you want to distribute it (to make sure it is on a users machine, or that they have a correct version) you must apply for a distribution license from Adobe. Or, all you can do it ask the user to download the newest Flash.

Posted: Sun Jun 08, 2008 2:55 am
by steven
Praetor wrote:If you make an app that uses Flash and you want to distribute it (to make sure it is on a users machine, or that they have a correct version) you must apply for a distribution license from Adobe. Or, all you can do it ask the user to download the newest Flash.
That was the info I needed.
Thanks.

Posted: Sun Jun 08, 2008 3:13 am
by ajs15822
Yup, the main restrictions seem to be about the distribution of the player. Hikari doesn't require you to distribute the Flash ActiveX control with your application, it is simply an option for those who wish to ensure compatibility. For those who wish to distribute the Flash ActiveX control and stay legally within bounds, you can apply for a free license by filling out this form.
Praetor wrote:They do not "support" it in any way, so it means we are all on our own.
This lack of support (there is no documentation on embedding the Flash ActiveX control) gave me quite an exercise in OLE while I was writing this thing. In fact, I still can't get the text caret working for text inputs. :?
Zeal wrote:I never lost faith sir, I knew one day you would ride down from the heavens on a cloud of glory, and bestow upon us all, FLASH SUPPORT!
Haha, I was thinking of you when I began this library. :P

Posted: Sun Jun 08, 2008 7:53 am
by marshmonkey
aj, you rock . . . I hope someone ( maybe us! ) uses this to create some awesome GUI masterpieces!

Posted: Sun Jun 08, 2008 8:02 am
by Noman
Wow.

Looks like game over for most of the other GUI libs =)

Congrats!

(Edit : Had compilation problems - missing shlwapi.h. Turns out that you need to install the Web Workshop component of the Platform SDK in order for this to exist)

Posted: Sun Jun 08, 2008 10:09 am
by handcircus
This is fantastic news, thanks!

Posted: Sun Jun 08, 2008 11:31 am
by johnhpus
The demo is very cool, but I noticed a slight lag when dragging the slider back and forth.

Any idea on the cause? In Navi there can be a similar lag when using non-Flash sliders and I think it's because it's copying the entire buffer instead of just the dirty area (not at all sure about that). Are you copying the buffer entirely or concentrating on parts that have changed?

Posted: Sun Jun 08, 2008 12:34 pm
by Gillian_Seed
Hi,


Hikari seems so cool that I quickly tried it.

First I ran the demo and it worked fine, then I just added the code of the demo to my app,
but I can't have it work :( (please, see the screenshot below for the errors during the compilation).

Do you know what's wrong ?
(I use the latest OgreSDK and I added the relevant path for the ".h" files to my proj,
but I didn't add the path to the ".idb" lib file because CodeBlocks doesn't recognize ".idb" files).

Do I have to compile Hikari from scratch in order to get a ".lib" file and, then, make Hikari work in my app ?


Thank you for your answers, and, of course, thank you, ajs15822, for Hikari ! You've done a very good job !


Image
Image

Posted: Sun Jun 08, 2008 1:43 pm
by Dodzey
Do I have to compile Hikari from scratch in order to get a ".lib" file and, then, make Hikari work in my app ?
Yes, the errors show that you are not linking to the library

Posted: Sun Jun 08, 2008 2:31 pm
by lf3thn4d
Nice work. :-) This might work very well for those who have money for flash IDE. :-P
Noman wrote:Wow.
Looks like game over for most of the other GUI libs =)
Nah.. It only works in windows. And requires a flash IDE to do any good. Unless you want to stick to flex which isn't quite what flash is. :P

Posted: Sun Jun 08, 2008 4:01 pm
by Gillian_Seed
Dodzey wrote:
Do I have to compile Hikari from scratch in order to get a ".lib" file and, then, make Hikari work in my app ?
Yes, the errors show that you are not linking to the library

Ok, thank you for your reply.


I downloaded Flash9 + MSVC2005, and, then, I tried to compile Hikari using CodeBlocks, but I can't resolve these errors
(please, see the screenshot below).

What do I miss ? Do I need "glib" or something to make the compilation work ?
I ask that because of the 3rd error (see the "sort()" call + the "gnu" stuff)
If yes, will I have to compile glib or is there any pre-made ".lib/.a/.dll/..." file available ? (PS : I use Windows)


Thanks for your answers !


Image

Posted: Sun Jun 08, 2008 4:03 pm
by vinhk
oh my, what a fantastic job ~ ! I think I'll use this for GUI.

Posted: Sun Jun 08, 2008 5:29 pm
by DanielSefton
O____O I love you.

Effortless GUI's here I come! :D

Posted: Sun Jun 08, 2008 5:50 pm
by DanielSefton
Uhh... Got the libs, now what? :P

I literally have no idea what I'm doing - Where's this 'HikariManager'? :?

And what ActionScript do you need? An example FLA file would be nice. =]

Posted: Sun Jun 08, 2008 8:55 pm
by ajs15822
Noman wrote:Wow.

Looks like game over for most of the other GUI libs =)

Congrats!

(Edit : Had compilation problems - missing shlwapi.h. Turns out that you need to install the Web Workshop component of the Platform SDK in order for this to exist)
Naw, other GUI libs will have their place-- I've just expanded the playing field to allow more Flash talent to get in the game.

As for the shwlapi dependency, it's used for "PathFileExists" to test if a ".swf" file exists before opening it (for debugging purposes, really). If obtaining shwlapi turns out to be an issue, I can always just replace it with the little hack of using ifstream to open the path to test for existence.
Gillian_Seed wrote:Ok, thank you for your reply.

I downloaded Flash9 + MSVC2005, and, then, I tried to compile Hikari using CodeBlocks, but I can't resolve these errors
(please, see the screenshot below).

What do I miss ? Do I need "glib" or something to make the compilation work ?
I ask that because of the 3rd error (see the "sort()" call + the "gnu" stuff)
If yes, will I have to compile glib or is there any pre-made ".lib/.a/.dll/..." file available ? (PS : I use Windows)
You will need to compile the Hikari library with Microsoft Visual C++ 2005 or higher (with the Platform SDK installed) because it uses the #import directive to generate the Flash headers. I don't see this as a major issue because the Express version (which I myself use!) is completely free.

As for the 'sort' issues, I think CodeBlocks just doesn't like my non-standard binary predicate declarations. I could replace that with more compatible code but due to the issue specified above, there's not much of a point.
Daniel Sefton wrote:Uhh... Got the libs, now what? :P

I literally have no idea what I'm doing - Where's this 'HikariManager'? :?
And what ActionScript do you need? An example FLA file would be nice. =]
I apologize for not having the introductory tutorials ready, I'm switching hosting providers right now.

First, compile Hikari from source using MSVC2005 (with the OgreSDK and Flash 9) in both the Debug and Release modes. If successful, it should generate Hikari.lib/Hikari.dll and Hikari_d.lib/Hikari_d.dll in the "Hikari\lib" directory.

Next, create a basic Ogre/OIS application (see the HikariDemo for an example).

For the debug build, you will need to link against the "Hikari_d.lib" you created earlier and copy "Hikari_d.dll" to the directory where you will run the executable.

Similarly, for the release build, you will need to link against the "Hikari.lib" you created earlier and copy "Hikari.dll" to the directory where you will run the executable.

In your application, add the "Hikari/include" path to your project's include directories. In your source, to include the entire Hikari API, simply declare:

Code: Select all

#include "Hikari.h"
I highly recommend reading the documentation within Hikari.h, FlashControl.h, and FlashValue.h.


To instantiate the HikariManager singleton in your application, you will need to "new" it (similar to the Ogre Root singleton):

Code: Select all

using namespace Hikari;

HikariManager* mgr = new HikariManager("myFlashFiles");
Then, after you've created Ogre::Root, camera, viewport, and scenemanager, you can create FlashControl overlays:

Code: Select all

using namespace Hikari;

FlashControl* myControl = mgr->createFlashOverlay("myControl", viewport, 300, 200, Position(Center), 0);

myControl->load("movie.swf");
Then, you need to update the HikariManager in your update loop:

Code: Select all

mgr->update();
And you also need to inject mouse input into the HikariManager, for example, this is how the HikariDemo does it:

Code: Select all

bool HikariDemo::mouseMoved(const OIS::MouseEvent &arg)
{
	return hikariMgr->injectMouseMove(arg.state.X.abs, arg.state.Y.abs);
}

bool HikariDemo::mousePressed(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
{
	return hikariMgr->injectMouseDown(id);
}

bool HikariDemo::mouseReleased(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
{
	return hikariMgr->injectMouseUp(id);
}
That's pretty much the basics of getting started (don't forget to delete the HikariManager in your Application's destructor!). If you look over the code of the HikariDemo and the code within the FLA files (in the demo's media folder), you should get a pretty good idea of the callback system. I'll try to find some time to write up a proper tutorial.
johnpus wrote:The demo is very cool, but I noticed a slight lag when dragging the slider back and forth.

Any idea on the cause? In Navi there can be a similar lag when using non-Flash sliders and I think it's because it's copying the entire buffer instead of just the dirty area (not at all sure about that). Are you copying the buffer entirely or concentrating on parts that have changed?
That slider is quite the stress-test because of several factors: it employs "live-dragging" (constantly notifies listeners during the drag), updates a small bit of text below the slider, invalidates the area, and alters the material's opacity with every pixel the slider is dragged.

Hikari definitely employs dirty-rectangling-- during updates, only the dirty area is rendered by Flash. This isn't to say that the dirty-rectangling is perfect: I had several issues getting the HardwarePixelBuffer to lock with arbitrary rectangles and so I instead maintain an internal shadow buffer to handle rectangle merging and then blit the entire shadow buffer to the pixel buffer using simple row-memcpy. The method, though imperfect, is still quite effective because profiling shows that the Flash software renderer is, naturally, the biggest CPU hog in the chain-- comparatively, the memcpy is negligible.

Nevertheless, I'll see if I can't find a compatible way to do dirty-rectangle updates directly in Ogre3D, to squeeze the maximum amount of performance out.

Posted: Sun Jun 08, 2008 9:01 pm
by DanielSefton
Cheers ajs, I'll give it a go. :)

But it doesn't come with any .fla's... Only .swf's.

Posted: Sun Jun 08, 2008 9:17 pm
by ajs15822
DanielSefton wrote:Cheers ajs, I'll give it a go. :)

But it doesn't come with any .fla's... Only .swf's.
Oh, forgot, the FLA's are included with the source release. ;)

By the way, if you're looking for ready-made Flash UI components and have Flash CS3, check it out. (The HikariDemo used Slider, ColorPicker, and Button)