Mistakes, omissions in the API doc

[Buy One]

TakeFX_CopyToTake()

In the explanation

Copies (or moves) FX from src_take to dest_take. Can be used with src_track=dest_track to reorder.

Must be take instead of track as per the previous phrase "from src_take to dest_take" and the arguments

reaper.TakeFX_CopyToTake(MediaItem_Take src_take, integer src_fx, MediaItem_Take dest_take, integer dest_fx, boolean is_move)

[Buy One]

TrackFX_AddByName()

The description lacks mention of FX chain preset support.

Without it being mentioned it can only be discovered by happenstance.

[Buy One]

GetFocusedFX2()

The doc:

Return value has 1 set if track FX, 2 if take/item FX, 4 set if FX is no longer focused but still open

What i get is 5 for track FX chain and 6 for take FX chain.

When no longer focused but still open i get 0 instead of 4.

[Buy One]

RecursiveCreateDirectory()

The doc reads

returns positive value on success, 0 on failure.

The function returns 0 on success. Not sure what it returns on failure.

As per Schwa's movie below the path must not end with a separator (although the function still does work with it).
.
.

[schwa]

Originally Posted by Buy One

GetFocusedFX2()

The doc:


What i get is 5 for track FX chain and 6 for take FX chain.

When no longer focused but still open i get 0 instead of 4.

The return value is a bitfield, so for example 5 means 1|4, that is, track fx that is open but not longer focused.

[schwa]

Originally Posted by Buy One

RecursiveCreateDirectory()

The doc reads



The function returns 0 on success. Not sure what it returns on failure.

Can you give an example of this function returning 0 on success?

[Buy One]

Originally Posted by schwa

Can you give an example of this function returning 0 on success?

I have this

PHP Code:

local result = reaper.RecursiveCreateDirectory(dir, -1) 


dir is a string of directory path to be created (which it is) at the REAPER's resource path

-1 i put in because the doc says integer ignored so just to fill it out with something, i tried 0, the result is the same.

[schwa]

What OS? On windows, that code gives result==1 on success.

[Buy One]

Sorry, i'm on Windows 7 x64, portable install

I make it create two directories at once, one of which is nested.

What should i do differently to get the expected result?

[schwa]

Can you possibly post a screencap demonstrating that function returning 0 on success? I'm not able to do so.

[Buy One]

Thank you for taking the time, my path ended with a separator \\, that was the reason.

[Buy One]

GetTakeStretchMarker()

The doc reads

Returns false if stretch marker not valid

I assume this refers to retval (the first return value).

In fact, if a marker is not valid retval is -1 just like in GetTakeMarker() function

[Buy One]

GetEnvelopeInfo_Value()

The doc is ambiguous about what should be passed as the first argument, track or envelope pointer

reaper.GetEnvelopeInfo_Value(TrackEnvelope tr, string parmname)

elsewhere in the doc envelope pointer argument is named env or envelope

[Justin]

Originally Posted by Buy One

GetEnvelopeInfo_Value()

The doc is ambiguous about what should be passed as the first argument, track or envelope pointer



elsewhere in the doc envelope pointer argument is named env or envelope

The type is "TrackEnvelope" which is an envelope... but yeah "tr" is misleading

[Buy One]

Originally Posted by Justin

The type is "TrackEnvelope" which is an envelope... but yeah "tr" is misleading

Thank you, i figured that out logically and on the basis of the annotation to the function, a beginner it may confuse.

[Justin]

Fixing that inconsistency for the next release

[Buy One]

Originally Posted by Justin

Fixing that inconsistency for the next release

Great, please also take a glimpse at these

https://forum.cockos.com/showpost.ph...39&postcount=1
https://forum.cockos.com/showpost.ph...0&postcount=12

[Hypex]

Originally Posted by Buy One

GetTakeStretchMarker()

Here's another for you. When input index is -1, to find next marker using position, it returns the marker following the exact position you specified. The doc says it does return the next marker but I would have expected it to return the exact marker of the exact position specified if it exists.

[Hypex]

SetTakeStretchMarker()


When resetting a known stretch marker by specifying index and new time position, that will result in moving the stretch marker to a new position, the old index is returned. I would have expected the index of the new marker position but this isn't the case.


As a side note, I investigated what can cause new marker inserts to fail. I found one case where it does fail. If a marker exists on take position zero and a new marker is attempted to insert at zero with -1 as index, it will fail. This looks due to behaviour when inserting a new marker. I have noticed that inserting a marker on a non zero postilion, when a marker already exists at that exact position, will cause the current marker to move a fraction to the left, with the new marker moving in it's place. Technically this would mean inserting a marker at an existing position in this case will not fail. If position is zero then there is no space to move a current marker to the left. I presume this causes a fail to insert at position zero.

[Buy One]

SetMediaTrackInfo_Value()


The following parameter names

I_MCPX : int * : current MCP X-position in pixels relative to mixer container
I_MCPY : int * : current MCP Y-position in pixels relative to mixer container
I_MCPW : int * : current MCP width in pixels
I_MCPH : int * : current MCP height in pixels

lack (read-only) remark unlike the following parameter names

I_WNDH : int * : current TCP window height in pixels including envelopes (read-only)
I_TCPH : int * : current TCP window height in pixels not including envelopes (read-only)
I_TCPY : int * : current TCP window Y-position in pixels relative to top of arrange view (read-only)

which may lead to belief that at least X, Y and H properties can be set programmatically with the function, the word current kind of hints at the fact that they're read only, but explicit indication would obviate guessing

[Meo-Ada Mespotine]

When I reworked my docs, I found several small errors and inconsistencies with the API-docs, mostly in the function-calls themselves.


Some issues I found:

GetSetProjectInfo_String - Description: newline missing before "PROJECT_TITLE : title field from Project Settings/Notes dialog"

Splash_GetWnd - Description: sphah should be splash instead, I think

TakeFX_SetPinMappings - name of MediaItemTake-parameter tr should be take

GetMediaSourceFileName - Description: typebuf should be filenamebuf, if I get this correctly

In reaper_plugin_functions.h
int (*StopTrackPreview2)(void* proj, preview_register_t* preview)
CPP: shouldn't parameter proj not be ReaProject* instead of void*? (Don't know CPP that well, just wondered...)


EEL2 in general:
Double/float-parameters seem to be missing a datatype in the docs.
For instance MIDI_GetCC and MIDI_GetEvt: ppqpos has no datatype(should be double/float?).
Is this intentional?

I also think, that parameters, whose value can be overwritten by the function should be somehow indicated.
Currently they often look the same as "regular" parameters, who are not overwritten, which can be confusing for
new EELers. Is there a convention I could use in my docs to indicate that(it's technically probably something like a
pointer in cpp?).


Number instead of Integer(Lua-functions):

Probably a nitpick, but in the following functions, the Lua-functions have number as datatype, despite
being integer in other languages(can occur in both, retvals and parameters). This is different in most
other functions, where integer is declared as integer/int.
As the SWS-functions BR_GetMediaItemImageResource, BR_GetMidiTakeTempoInfo, BR_GetMouseCursorContext_MIDI have
the same issue, this might be an issue in the doc-generator-code itself, but I'm not sure(couldn't figure
out a pattern).
This also includes bleeding-edge-functions like MIDI_GetRecentInputEvent.
This list is probably not complete.

GR_SelectColor - color

MIDI_CountEvts - notecnt, ccevtcnt, textsyxevtcnt

MIDI_GetCC - chanmsg, chan, msg2, msg3

MIDI_GetCCShape - shape

MIDI_GetNote - chan, pitch, vel

MIDI_GetScale - root, scale

MIDI_GetTextSysexEvt - type

my_getViewport - r.left, r.top, r.right, r.bot, sr.left, sr.top, sr.right, sr.bot

TakeFX_GetIOSize - inputPins, outputPins

TakeFX_GetPinMappings - high32

TakeFX_GetPresetIndex - numberOfPresets

TimeMap2_beatsToTime - measuresIn

TimeMap2_timeToBeats - measures, cml, cdenom

TimeMap_GetMeasureInfo - timesig_num, timesig_denom

TrackFX_GetIOSize - inputPins, inputPins

TrackFX_GetPinMappings - high32

TrackFX_GetPresetIndex - numberOfPresets

MIDI_GetRecentInputEvent - ts, devIdx, projLoopCnt


The SWS-functions, that show the same issue:

BR_GetMediaItemImageResource - imageFlags

BR_GetMidiTakeTempoInfo - num, den

BR_GetMouseCursorContext_MIDI - noteRow, ccLane, ccLaneVal, ccLaneId

[Meo-Ada Mespotine]

Fond two issues in the docs:

GetFocusedFX2

for better clarity, the text
"4 set if FX is no longer focused but still open" should be
"&4 set if FX is no longer focused but still open" to better indicate, that this is a flag.



GetSet_ArrangeView2

the functioncall of Lua is missing the last two parameters in the docs:

Lua: number start_time, number end_time = reaper.GetSet_ArrangeView2(ReaProject proj, boolean isSet, integer screen_x_start, integer screen_x_end, integer start_time, integer end_time)

[Justin]

Originally Posted by Meo-Ada Mespotine

Fond two issues in the docs:

GetFocusedFX2

for better clarity, the text
"4 set if FX is no longer focused but still open" should be
"&4 set if FX is no longer focused but still open" to better indicate, that this is a flag.

We use "has 1 set" "has 2 set" etc in a lot of places (vs equals 1 or is 1).

GetSet_ArrangeView2

the functioncall of Lua is missing the last two parameters in the docs:

Lua: number start_time, number end_time = reaper.GetSet_ArrangeView2(ReaProject proj, boolean isSet, integer screen_x_start, integer screen_x_end, integer start_time, integer end_time)

Thanks!

[Buy One]

Originally Posted by Justin

Thanks!

Does this mean the GET function returns 4 values rather than 2, i.e. Arrange start/end in both seconds and pixels? Or does it only return time for the specified pixel values?

[Justin]

Originally Posted by Buy One

Does this mean the GET function returns 4 values rather than 2, i.e. Arrange start/end in both seconds and pixels? Or does it only return time for the specified pixel values?

It only returns start/end times

[Buy One]

Originally Posted by Justin

It only returns start/end times

OK...

[Buy One]

In description of P_EXT:xyz parameter for functions

GetSetMediaItemInfo_String()
GetSetMediaItemTakeInfo_String()
GetSetMediaTrackInfo_String()
GetSetTrackSendInfo_String()
GetSetEnvelopeInfo_String()
GetSetAutomationItemInfo_String()

would be useful to have indication that in order to delete extension-specific persistent data an empty string must be passed as stringNeedBig argument

[Hypex]

Originally Posted by Meo-Ada Mespotine

EEL2 in general:
Double/float-parameters seem to be missing a datatype in the docs.
For instance MIDI_GetCC and MIDI_GetEvt: ppqpos has no datatype(should be double/float?).
Is this intentional?

I also think, that parameters, whose value can be overwritten by the function should be somehow indicated.
Currently they often look the same as "regular" parameters, who are not overwritten, which can be confusing for
new EELers. Is there a convention I could use in my docs to indicate that(it's technically probably something like a
pointer in cpp?)

Confusing at first but EEL values are passed by reference, like a C variable &pointer. There is also decimal or string. That's my experience.



For default values that are optional on the end of a function call, they can be left blank or set to 0.


Strings are slightly quirky. They can be passed directly like "this". But as a variable need to be hashed like #this. But, it gets confusing as they can also be hashless, set like a normal variable. And passed around like a normal variable. But need the hash to be modified. I'm also not sure where they are stored nor of any limits. Since they can be variable strings, as opposed to other decimal variables.

[Buy One]

function ThemeLayout_SetParameter() description reads

note that the caller should update layouts via ??? to make changes visible.

Do question marks refer to ThemeLayout_RefreshAll()?

[Buy One]

TakeFX_GetPreset()
TrackFX_GetPreset()

Returns false if the current FX parameters do not exactly match the preset (in other words, if the user loaded the preset but moved the knobs afterward)

Isn't the case for the Video processor plugin

[Buy One]

GetSetProjectInfo_String()

Perhaps worth adding a note that retval is only relevant for setting values and getting with parameter (desc) being an invalid string, otherwise it's always true

[Buy One]

PromptForAction()

checking return value for user-selected action

I think user-run action would be more accurate as in order for its command ID to be returned by the function an action must be run and not merely selected in the Action list

[nofish]

Originally Posted by Buy One

PromptForAction()



I think user-run action would be more accurate as in order for its command ID to be returned by the function an action must be run and not merely selected in the Action list

When using this function the action list window comes up with Select / Select/close buttons instead of the 'normal' Run / Run/close buttons.

True that merely selecting in the Action list doesn't suffice, but with the Select buttons it's clear enough imo.

[Buy One]

Originally Posted by nofish

When using this function the action list window comes up with Select / Select/close buttons instead of the 'normal' Run / Run/close buttons.

Indeed, i didn't notice that because i never run actions in the Action list with buttons, double click is much more convenient to me.

But why change button titles with a function? Just so they conform to its description or are these alternative names a holdover from older versions?

[Indiscipline]

What's the meaning of the type names for parmname values for GetMediaItemInfo_Value?

I expected it to be the real type simply cast to double to allow passing multiple types over the same function, but the values I'm getting (at least for "int" params which were the only ones I checked) are really double.

So it's all a bit confusing and requires some clarification on what to expect.

 Get media item numerical-value attributes.
    B_MUTE : bool * : muted (item solo overrides). setting this value will clear C_MUTE_SOLO.
    B_MUTE_ACTUAL : bool * : muted (ignores solo). setting this value will not affect C_MUTE_SOLO.
    C_MUTE_SOLO : char * : solo override (-1=soloed, 0=no override, 1=unsoloed). note that this API does not automatically unsolo other items when soloing (nor clear the unsolos when clearing the last soloed item), it must be done by the caller via action or via this API.
    B_LOOPSRC : bool * : loop source
    B_ALLTAKESPLAY : bool * : all takes play
    B_UISEL : bool * : selected in arrange view
    C_BEATATTACHMODE : char * : item timebase, -1=track or project default, 1=beats (position, length, rate), 2=beats (position only). for auto-stretch timebase: C_BEATATTACHMODE=1, C_AUTOSTRETCH=1
    C_AUTOSTRETCH: : char * : auto-stretch at project tempo changes, 1=enabled, requires C_BEATATTACHMODE=1
    C_LOCK : char * : locked, &1=locked, &2=lock to active take
    D_VOL : double * : item volume, 0=-inf, 0.5=-6dB, 1=+0dB, 2=+6dB, etc
    D_POSITION : double * : item position in seconds
    D_LENGTH : double * : item length in seconds
    D_SNAPOFFSET : double * : item snap offset in seconds
    D_FADEINLEN : double * : item manual fadein length in seconds
    D_FADEOUTLEN : double * : item manual fadeout length in seconds
    D_FADEINDIR : double * : item fadein curvature, -1..1
    D_FADEOUTDIR : double * : item fadeout curvature, -1..1
    D_FADEINLEN_AUTO : double * : item auto-fadein length in seconds, -1=no auto-fadein
    D_FADEOUTLEN_AUTO : double * : item auto-fadeout length in seconds, -1=no auto-fadeout
    C_FADEINSHAPE : int * : fadein shape, 0..6, 0=linear
    C_FADEOUTSHAPE : int * : fadeout shape, 0..6, 0=linear
    I_GROUPID : int * : group ID, 0=no group
    I_LASTY : int * : Y-position (relative to top of track) in pixels (read-only)
    I_LASTH : int * : height in pixels (read-only)
    I_CUSTOMCOLOR : int * : custom color, OS dependent color|0x1000000 (i.e. ColorToNative(r,g,b)|0x1000000). If you do not |0x1000000, then it will not be used, but will store the color
    I_CURTAKE : int * : active take number
    IP_ITEMNUMBER : int : item number on this track (read-only, returns the item number directly)
    F_FREEMODE_Y : float * : free item positioning Y-position, 0=top of track, 1=bottom of track (will never be 1)
    F_FREEMODE_H : float * : free item positioning height, 0=no height, 1=full height of track (will never be 0)
    P_TRACK : MediaTrack * : (read-only)

PS: Using C.

[Justin]

Originally Posted by Indiscipline

What's the meaning of the type names for parmname values for GetMediaItemInfo_Value?

I expected it to be the real type simply cast to double to allow passing multiple types over the same function, but the values I'm getting (at least for "int" params which were the only ones I checked) are really double.

So it's all a bit confusing and requires some clarification on what to expect.

 Get media item numerical-value attributes.
    B_MUTE : bool * : muted (item solo overrides). setting this value will clear C_MUTE_SOLO.
    B_MUTE_ACTUAL : bool * : muted (ignores solo). setting this value will not affect C_MUTE_SOLO.
    C_MUTE_SOLO : char * : solo override (-1=soloed, 0=no override, 1=unsoloed). note that this API does not automatically unsolo other items when soloing (nor clear the unsolos when clearing the last soloed item), it must be done by the caller via action or via this API.
    B_LOOPSRC : bool * : loop source
    B_ALLTAKESPLAY : bool * : all takes play
    B_UISEL : bool * : selected in arrange view
    C_BEATATTACHMODE : char * : item timebase, -1=track or project default, 1=beats (position, length, rate), 2=beats (position only). for auto-stretch timebase: C_BEATATTACHMODE=1, C_AUTOSTRETCH=1
    C_AUTOSTRETCH: : char * : auto-stretch at project tempo changes, 1=enabled, requires C_BEATATTACHMODE=1
    C_LOCK : char * : locked, &1=locked, &2=lock to active take
    D_VOL : double * : item volume, 0=-inf, 0.5=-6dB, 1=+0dB, 2=+6dB, etc
    D_POSITION : double * : item position in seconds
    D_LENGTH : double * : item length in seconds
    D_SNAPOFFSET : double * : item snap offset in seconds
    D_FADEINLEN : double * : item manual fadein length in seconds
    D_FADEOUTLEN : double * : item manual fadeout length in seconds
    D_FADEINDIR : double * : item fadein curvature, -1..1
    D_FADEOUTDIR : double * : item fadeout curvature, -1..1
    D_FADEINLEN_AUTO : double * : item auto-fadein length in seconds, -1=no auto-fadein
    D_FADEOUTLEN_AUTO : double * : item auto-fadeout length in seconds, -1=no auto-fadeout
    C_FADEINSHAPE : int * : fadein shape, 0..6, 0=linear
    C_FADEOUTSHAPE : int * : fadeout shape, 0..6, 0=linear
    I_GROUPID : int * : group ID, 0=no group
    I_LASTY : int * : Y-position (relative to top of track) in pixels (read-only)
    I_LASTH : int * : height in pixels (read-only)
    I_CUSTOMCOLOR : int * : custom color, OS dependent color|0x1000000 (i.e. ColorToNative(r,g,b)|0x1000000). If you do not |0x1000000, then it will not be used, but will store the color
    I_CURTAKE : int * : active take number
    IP_ITEMNUMBER : int : item number on this track (read-only, returns the item number directly)
    F_FREEMODE_Y : float * : free item positioning Y-position, 0=top of track, 1=bottom of track (will never be 1)
    F_FREEMODE_H : float * : free item positioning height, 0=no height, 1=full height of track (will never be 0)
    P_TRACK : MediaTrack * : (read-only)

PS: Using C.

GetMediaItemInfo_Value converts the underlying type to/from double for use from ReaScript.

[Buy One]

CSurf_OnScroll()

Warrants a bit of a description stating that scrolling left/up requires a negative integer, because it's not immediately follows from the argument names

Also a mention that the passed values are multiplied by 16 for horizontal and by 8 for vertical scrolls, so must be offset.

[mpl]

Would be nice to document:
1) retval, buf = reaper.TrackFX_GetNamedConfigParm( track, fx, parmname )
with all available plugins/variables

2) reaper.Undo_EndBlock2( proj, descchange, extraflags )
with a flags definition from here: https://forum.cockos.com/showpost.ph...9&postcount=12

3) Something more informative about "Undo flag is a performance/caching hint" for all get/set chunk functions

[Hypex]

I think I found another one with SetTempoTimeSigMarker(). A slight flaw here. It says:
If timesig_num and timesig_denom are zero, the previous time signature will be used.

And:
ptidx=-1 will insert a new tempo/time signature marker.

However, I recently found out if it is used where a time signature marker is already present, with ptidx=-1 it won't insert a new marker but modify existing marker.

This means there is no way to reset a marker and erase any time signature or insert a new marker with only tempo at that time position since it can't be told to leave the time signature blank.

So, if it is intended to set new BPM with blank time signature, then one must first search for any markers first and erase them, since a BPM and blank time signature cannot be specified with SetTempoTimeSigMarker().

[Buy One]

GetMediaItemInfo_Value()
SetMediaItemInfo_Value()

In the value list of C_BEATATTACHMODE parameter 'time' option is missing whose value is 0.0

In the list of corresponding track parameter values it's included