Joseph: Do not be embarrassed. Understanding the engine is relatively opaque IMO and info is scattered in different places.
Christof: IMO these kinds of important details should really by in m_pd.h. The API is pretty stable at this point, so it would pay to fill out the header. This was my approach with libpd:
https://github.com/pure-data/pure-data/blob/master/src/z_libpd.h
We originally had docs for libpd on a wiki page but once things stabilized I did the painful, but IMO necessary, step to move it into minimal header documentation. This also made it trivial to include basic docs when libpd was integrated into the pure-data repo.
On Aug 23, 2023, at 5:05 PM, pd-dev-request@lists.iem.at wrote:
Message: 1 Date: Wed, 23 Aug 2023 17:04:41 +0200 From: Christof Ressi <info@christofressi.com mailto:info@christofressi.com> To: pd-dev@lists.iem.at mailto:pd-dev@lists.iem.at Subject: Re: [PD-dev] why must one never send a message from a perform routine ? Message-ID: <7a96c4d0-10ec-1d18-b016-df0304498623@christofressi.com mailto:7a96c4d0-10ec-1d18-b016-df0304498623@christofressi.com> Content-Type: text/plain; charset="utf-8"; Format="flowed"
Glad that I could help! Very little of this is really documented (accurately). Personally, I figured this out by reading the source code.
Ideally, we should improve the official documentation in http://msp.ucsd.edu/Pd_documentation/x3.htm#s1.0. Some things are outdated, misleading or just plain wrong (in particular the section "audio buffer size and block size"). I just put this on my (ever-growing) TODO list.
Christof
-------- Dan Wilcox @danomatika http://twitter.com/danomatika danomatika.com http://danomatika.com/ robotcowboy.com http://robotcowboy.com/
so it would pay to fill out the header.
Yeah, all API functions in "m_pd.h" should really have minimal documentation (preferrably doxygen).
However, I'm not sure that "m_pd.h" is the place for documenting the inner workings of Pd... I think the official manual would be a more natural place, as it already serves this purpose.
Anyway, once these things are written down /somewhere/, we can just post a link whenever someone asks about them :)
Christof
On 23.08.2023 17:20, Dan Wilcox wrote:
Joseph: Do not be embarrassed. Understanding the engine is relatively opaque IMO and info is scattered in different places.
Christof: IMO these kinds of important details should really by in m_pd.h. The API is pretty stable at this point, so it would pay to fill out the header. This was my approach with libpd:
https://github.com/pure-data/pure-data/blob/master/src/z_libpd.h
We originally had docs for libpd on a wiki page but once things stabilized I did the painful, but IMO necessary, step to move it into minimal header documentation. This also made it trivial to include basic docs when libpd was integrated into the pure-data repo.
On Aug 23, 2023, at 5:05 PM, pd-dev-request@lists.iem.at wrote:
Message: 1 Date: Wed, 23 Aug 2023 17:04:41 +0200 From: Christof Ressi info@christofressi.com To:pd-dev@lists.iem.at Subject: Re: [PD-dev] why must one never send a message from a perform routine ? Message-ID: 7a96c4d0-10ec-1d18-b016-df0304498623@christofressi.com Content-Type: text/plain; charset="utf-8"; Format="flowed"
Glad that I could help! Very little of this is really documented (accurately). Personally, I figured this out by reading the source code.
Ideally, we should improve the official documentation in http://msp.ucsd.edu/Pd_documentation/x3.htm#s1.0. Some things are outdated, misleading or just plain wrong (in particular the section "audio buffer size and block size"). I just put this on my (ever-growing) TODO list.
Christof
Dan Wilcox @danomatika http://twitter.com/danomatika danomatika.com http://danomatika.com robotcowboy.com http://robotcowboy.com
Well, I don't mean documentation all internal mechanisms but, in this case, it might have been helpful to at least note *which* functions should or shouldn't be called in which situations. For instance, I note which libpd functions *not* call when DSP is running.
On Aug 23, 2023, at 5:30 PM, Christof Ressi info@christofressi.com wrote:
so it would pay to fill out the header.
Yeah, all API functions in "m_pd.h" should really have minimal documentation (preferrably doxygen).
However, I'm not sure that "m_pd.h" is the place for documenting the inner workings of Pd... I think the official manual would be a more natural place, as it already serves this purpose.
Anyway, once these things are written down somewhere, we can just post a link whenever someone asks about them :)
Christof
-------- Dan Wilcox @danomatika http://twitter.com/danomatika danomatika.com http://danomatika.com/ robotcowboy.com http://robotcowboy.com/
Ah, I thought you were talking about the "polling mode vs callback mode" thing. Yes, the API docs should mention in which context a function may or may not be called.
For example, functions that can be safely called in perform routines may be annotated with something like "\qualifier dspsafe".
Christof
On 23.08.2023 17:32, Dan Wilcox wrote:
Well, I don't mean documentation all internal mechanisms but, in this case, it might have been helpful to at least note *which* functions should or shouldn't be called in which situations. For instance, I note which libpd functions *not* call when DSP is running.
On Aug 23, 2023, at 5:30 PM, Christof Ressi info@christofressi.com wrote:
so it would pay to fill out the header.
Yeah, all API functions in "m_pd.h" should really have minimal documentation (preferrably doxygen).
However, I'm not sure that "m_pd.h" is the place for documenting the inner workings of Pd... I think the official manual would be a more natural place, as it already serves this purpose.
Anyway, once these things are written down/somewhere/, we can just post a link whenever someone asks about them :)
Christof
Dan Wilcox @danomatika http://twitter.com/danomatika danomatika.com http://danomatika.com robotcowboy.com http://robotcowboy.com
-
Christof Ressi -
Dan Wilcox