Love 0.7 docs WIP

[pekka]

I'll probably get some work done on Löve 0.7 docs now and then. I will post updates to this thread. I don't think I will be putting anything in the official docs in the Wiki before 0.7 is out of beta. It's kind of impolite to crap over the docs when people still might use 0.6.2.

Also, I like working off-line better.

Anyway, to get started, we can find the documentation topics by use of some basic Unix shell tools.

The Löve Devs seem to keep almost all the Lua API in consistently named files. Their names always begin with wrap_ and end in .cpp or .h. So, we can use find to ferret them all out easily.

Going to the love-0.7.0-beta/src directory and issuing the command find * -name wrap*cpp | sort results in this data:

Code: Select all

common/wrap_Data.cpp
modules/audio/wrap_Audio.cpp
modules/audio/wrap_Source.cpp
modules/event/sdl/wrap_Event.cpp
modules/filesystem/physfs/wrap_File.cpp
modules/filesystem/physfs/wrap_FileData.cpp
modules/filesystem/physfs/wrap_Filesystem.cpp
modules/font/freetype/wrap_Font.cpp
modules/font/wrap_FontData.cpp
modules/font/wrap_GlyphData.cpp
modules/font/wrap_Rasterizer.cpp
modules/graphics/opengl/wrap_Font.cpp
modules/graphics/opengl/wrap_Framebuffer.cpp
modules/graphics/opengl/wrap_Glyph.cpp
modules/graphics/opengl/wrap_Graphics.cpp
modules/graphics/opengl/wrap_Image.cpp
modules/graphics/opengl/wrap_ParticleSystem.cpp
modules/graphics/opengl/wrap_Quad.cpp
modules/graphics/opengl/wrap_SpriteBatch.cpp
modules/image/wrap_EncodedImageData.cpp
modules/image/wrap_Image.cpp
modules/image/wrap_ImageData.cpp
modules/joystick/sdl/wrap_Joystick.cpp
modules/keyboard/sdl/wrap_Keyboard.cpp
modules/mouse/sdl/wrap_Mouse.cpp
modules/physics/box2d/wrap_Body.cpp
modules/physics/box2d/wrap_CircleShape.cpp
modules/physics/box2d/wrap_Contact.cpp
modules/physics/box2d/wrap_DistanceJoint.cpp
modules/physics/box2d/wrap_GearJoint.cpp
modules/physics/box2d/wrap_Joint.cpp
modules/physics/box2d/wrap_MouseJoint.cpp
modules/physics/box2d/wrap_Physics.cpp
modules/physics/box2d/wrap_PolygonShape.cpp
modules/physics/box2d/wrap_PrismaticJoint.cpp
modules/physics/box2d/wrap_PulleyJoint.cpp
modules/physics/box2d/wrap_RevoluteJoint.cpp
modules/physics/box2d/wrap_Shape.cpp
modules/physics/box2d/wrap_World.cpp
modules/sound/wrap_Decoder.cpp
modules/sound/wrap_Sound.cpp
modules/sound/wrap_SoundData.cpp
modules/thread/sdl/wrap_Thread.cpp
modules/timer/sdl/wrap_Timer.cpp

There is some Lua code in the scripts directory which we will look at later. We can also use grep to find all the names that are provided for the wrapped functions in Lua, because the nice and friendly dev folks have also been nice and friendly enough to list the consistently. The grep command I use to look for them might not look so nice, but let's not dwell on that.

Since most everything is in modules directory, I step into it and then issue the command grep "{.*\".*\",.*}" -r * | sort

(It would be more efficient to only grep thru the files we found in step one, and I'm sure you could come up with a better regexp. But this command works so fast there's no sense in wasting time on this.

As it turned out, the output is so big it would post this posting over the limit of characters for one post. So you get two posts for the price of one. To be continued.

[pekka]

The grep outputted this data. I apparently have to attach it, because it is still too big.

Now, I'll be posting updates on this thread about the doc stuff. Do NOT let this keep YOU from also working on the docs. Day and night. No sleep until it is done.

[bartbes]

find * -name wrap*cpp | sort
grep "{.*\".*\",.*}" -r * | sort

Well, let's combine the two:

Code: Select all

grep "{.*\".*\",.*}" `find * -name wrap*cpp` | sort

[pekka]

EDIT: Re: Bartbes. Yes, thanks for the tip. I did want the output from the find as a separate file, though! (Now you'll have to post one with a tee in it, don't you? Go ahead )

The headers in the scripts directory contain some Lua code, which is available in plain form from the Bitbucket repository. The files are in here (EDIT: linked to the dir, not a lua file)

http://bitbucket.org/rude/love/src/tip/src/scripts/

They contain some functions that are part of the Löve API.

graphics.lua contains the definitions for

newFont
setFont
print
printf

audio.lua contains the definition for

newSource

(These are actually mostly thin wrappers around other code.)

boot.lua contains the code that is used to start up Löve. It can be a useful reference for finding out what exactly to put in conf.lua and how the default event loop works.

In the API listing above there are actually three entries that have been commented out. They are in wrap_Audio.cpp and are these:

record
getRecordedData
stopRecording

It isn't quite clear from the sorted list that these interesting functions don't yet exist. We'll probably see them in the future, since they are already sort of included

To make it clear, I am mostly using the downloadable 0.7.0 Linux source beta package when working on the docs. But I do occasionally refer to the version in the repository, like I did with the decoded forms of the Lua headers. Hexadecimal literals surprisingly are not my favorite way of reading Lua code.

Anyway, I'll post more in couple of days or so. I'll start digging out the actual arguments accepted and meanings of the new stuff that's in 0.7.0, so there'll be something you can use here, probably. Soon. Ish.

(Don't hold your breath.)

[Robin]

I made a new template, which you can add to all new functions and whatnots by putting

Code: Select all

{{newin|[[0.7.0]]}}

at the top.

I'm thinking maybe we should have a removedin or deprecatedin template as well.

[pekka]

Apparently the function in the physics module to create a new world now takes an extra parameter now. How do we mark that so that the 0.6.2 form still stays up and remains clearly marked as the 0.6.2 way to do it?

Maybe we can just add a synopsis entry with the heading saying it is new in 0.7 and later phase out the 0.6.2 versions.

No matter what, I'll stick to working on the docs off-line for now. Once I know what to write to the Wiki it'll be easier to add the stuff and leave the docs in consistent state throughout the updates. And to be honest, when I am off-line, there are fewer distractions!

[bartbes]

Small note about these recording functions: They don't work (yet) and as such they will be postponed to a later version.

[pekka]

So, most new stuff is in the Wiki already? Good job guys.

Here's some info that I don't know where to put in the Wiki. There are two new callbacks.

love.focus

If you define love.focus(hasFocus) as a callback, it will be called every time the Löve window gains and loses the focus. The parameter it receives is a boolean that is false when the window has lost the focus and true when it has gained it.

When the window doesn't have the focus, it doesn't receive any input events. On your desktop these always go into the active window. It can be a good idea to enter a pause state in such a situation, or just make the game more sleepy so it doesn't eat CPU cycles.

love.quit

The love.quit() callback is called when the game is being closed. It takes no parameters, but you can return a boolean to indicate whether you want to continue without quitting or not. The return value should be true if you want to continue and false to confirm that the game will be closed.

One possible use for this callback is putting up a menu where you can save the current game, quit without saving or continue playing. (You know, apparently some shoddy people hit that little cross with their mouse by accident now and then ).

(I hope I got the boolean return value right way around. I'm typing this up from memory.)

[bartbes]

The return value should be true if you want to continue and false to confirm that the game will be closed.

While this might seem illogical at first, it is indeed correct because that means if you don't return anything it will just close.

One possible use for this callback is putting up a menu where you can save the current game, quit without saving or continue playing. (You know, apparently some shoddy people hit that little cross with their mouse by accident now and then ).

Well, I guess you don't even have to show a menu like that, but at least you can (auto)save before closing, which might not be a bad feature.

[pekka]

One possible use for this callback is putting up a menu where you can save the current game, quit without saving or continue playing. (You know, apparently some shoddy people hit that little cross with their mouse by accident now and then ).

Well, I guess you don't even have to show a menu like that, but at least you can (auto)save before closing, which might not be a bad feature.

Well, Bartbes, when we give examples of what we've just explained, we usually try to include the key functionality of what was explained there. In this case I wanted to show how the possibility of continuing instead of quitting can fit with the other options in a way that is used in many programs. It wouldn't really make much sense to first tell the reader he can prevent Löve from quitting with this callback, and then give an example where this facility is not used. That's why I wrote it like that.

Since you are in an explanatory mood, maybe you can explain us why Löve allows us to open a file in closed mode, or what we can do with files opened in closed mode, with an operation like this:

Code: Select all

myFile:open("c")

Actually, there's no need to explain. I can guess how this feature slipped in, from reading the source. Though, for a moment, I was tempted to send this in to the guys in the Daily WTF--but I am not going to be that rude.