Some needed updates / corrections to Corona docs

Solar2D General Questions/Discussion
#1

I did report these issues via the form first, but seeing as around a month has passed and nothing has changed, I thought to post about these here as well.

#1 Lua Functions

https://docs.coronalabs.com/guide/start/introLua/index.html#luafunctions

There’s a bit that reads: “For security reasons, the dofile(), load(), loadfile(), and loadstring() functions are not available in Corona.”, however, loadstring() is in fact supported by Corona, as has been pointed out by Rob at https://forums.coronalabs.com/topic/72285-how-does-it-work-today-can-downloaded-lua-be-loaded-dynamically/ and https://forums.coronalabs.com/topic/75355-can-you-trust-loadstring-on-all-compiled-platforms/. I even sumbled upon it in Corona’s shell.lua (https://github.com/coronalabs/corona/blob/master/platform/resources/shell.lua#L988).
 

#2 timer.performWithDelay
https://docs.coronalabs.com/api/library/timer/performWithDelay.html

There has been an undocumented change with to the timer for months now, read https://forums.coronalabs.com/topic/75068-20193468-timer-fixes-are-terrible-and-unnecessary/page-2?hl=performwithdelay. This “timer.allowIterationsWithinFrame” is not documented, but it really should be because otherwise its existence will be forgotten over time.

#3 Audio formats

https://docs.coronalabs.com/guide/media/audioSystem/index.html#audio-formats

There’s a line: “.mp3 has various patent and royalty issues, but when .aac was ratified, it was agreed that there would be no royalties required for distribution.”, however, the last mp3 patents expired back in 2017. This sentence would now correctly read: “.mp3 no longer has any patent or royalty issues, but when .aac was ratified, it was agreed that there would be no royalties required for distribution.” As this sentence makes no sense anymore, it could just be removed entirely.
Sources: https://www.iis.fraunhofer.de/en/ff/amm/consumer-electronics/mp3.html and https://www.theregister.co.uk/2017/05/16/mp3_dies_nobody_noticed/

Now, for the mandatory audiovisual aid to accompany my post :smiley:
https://www.youtube.com/watch?v=9gSQg1i_q2g

#2

@XeduR

Thanks for taking time to find all that and posit.  That can be very helpful to the whole corona community.

#3

Same thing with shaders especially time-based code.

#4

I appreciate the reports. Keep them coming. Those are sitting in my in-box to update. I will hopefully get to them soon,

Rob

#5

The docs should update shortly with these updates.

Rob

#6

the tech notes section of display objects has long had some mis-characterizations with regard to “display objects are type userdata” (paraphrased), the most glaring of which is:

-- https://docs.coronalabs.com/guide/media/displayObjects/index.html#technical-notes -- "An exception to this rule is that you cannot set the metatables of display objects." -- OH YES YOU CAN: local rect = display.newRect(100,100,50,50) setmetatable(rect, { \_\_index = { message = "Hello World!", speak = function(self) print(self.message) end } }) rect:speak() -- TO CORRECT: replace "cannot" with "should not", because.. print(rect.x, rect.removeSelf) -- et al -- all original properties/methods have been wiped out, oops! -- (there are ways around, f.e. cascaded metatables, but is advanced stuff - most users "should not" do)

Most of that section reads as if it were describing things returned by the graphics library, not from the display library.  (f.e. if describing an image sheet, then most of that section would read as true, but not for display objects)

This is a very fine point/nitpick, and doubt that most casual users would ever pick up on it, but it’s nonsense as written nonetheless.

#7

The docs concerning Lua functions and audio formats have been updated. Awesome! The timer update is still to come.

@dave, I agree that “cannot” and “should not” ought to be clearly stated like so. I for one always tend to try things out like that, i.e. “Oh, I know that I shouldn’t… but can I?” :smiley:

@SGS, could you elaborate on the shaders? I’ve only toyed with them a bit and so I have no experience concerning the matter.

#8

The timer docs have been updated.

Rob

#9

Starcrunch did a fix for time dependent shaders to make them actually work.

Adding this fixes the problem 

timeTransform = { func = "pingpong", range = 5 },

But is missing on the docs - https://docs.coronalabs.com/api/library/graphics/defineEffect.html

#10

Ah, so they have been. Found it at https://docs.coronalabs.com/api/library/timer/allowIterationsWithinFrame.html

I was just looking at the wrong place. Thanks!

#11

It would be really helpful for people updating Corona via open source, to use the form at the bottom of any API they change, so we can know what needs to be updated. It’s important that we get as many details about the change as possible. In the past, Corona developers were required to update the documentation for the changes, then the DevRel team would copy edit them. We can’t guess at what should be there.

Rob

#12

@Rob Miracle Noted.  :slight_smile:

A writeup on “time transforms”, along with an analysis of the problem, can be found on my last comment for the PR in question, here. Feel free to use and / or adapt it, and let me know if any more details are needed.

Those methods aren’t necessarily exhaustive, but seemed like a good start. 1D noise might be another decent choice, for example

UPDATE : The chart on this page might give some insights into the numbers. In particular, the “half” type is all we can assume on GLES2-grade mobile devices.

#13

@XeduR

Thanks for taking time to find all that and posit.  That can be very helpful to the whole corona community.

#14

Same thing with shaders especially time-based code.

#15

I appreciate the reports. Keep them coming. Those are sitting in my in-box to update. I will hopefully get to them soon,

Rob

#16

The docs should update shortly with these updates.

Rob

#17

the tech notes section of display objects has long had some mis-characterizations with regard to “display objects are type userdata” (paraphrased), the most glaring of which is:

-- https://docs.coronalabs.com/guide/media/displayObjects/index.html#technical-notes -- "An exception to this rule is that you cannot set the metatables of display objects." -- OH YES YOU CAN: local rect = display.newRect(100,100,50,50) setmetatable(rect, { \_\_index = { message = "Hello World!", speak = function(self) print(self.message) end } }) rect:speak() -- TO CORRECT: replace "cannot" with "should not", because.. print(rect.x, rect.removeSelf) -- et al -- all original properties/methods have been wiped out, oops! -- (there are ways around, f.e. cascaded metatables, but is advanced stuff - most users "should not" do)

Most of that section reads as if it were describing things returned by the graphics library, not from the display library.  (f.e. if describing an image sheet, then most of that section would read as true, but not for display objects)

This is a very fine point/nitpick, and doubt that most casual users would ever pick up on it, but it’s nonsense as written nonetheless.

#18

The docs concerning Lua functions and audio formats have been updated. Awesome! The timer update is still to come.

@dave, I agree that “cannot” and “should not” ought to be clearly stated like so. I for one always tend to try things out like that, i.e. “Oh, I know that I shouldn’t… but can I?” :smiley:

@SGS, could you elaborate on the shaders? I’ve only toyed with them a bit and so I have no experience concerning the matter.

#19

The timer docs have been updated.

Rob

#20

Starcrunch did a fix for time dependent shaders to make them actually work.

Adding this fixes the problem 

timeTransform = { func = "pingpong", range = 5 },

But is missing on the docs - https://docs.coronalabs.com/api/library/graphics/defineEffect.html