Skip to content

[Enhance] Manual Documentation for CCE Objects #250

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamesb93 merged 12 commits into from
Jun 8, 2022
Merged

[Enhance] Manual Documentation for CCE Objects #250

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
01c5eb7
install the contents of manual_docs to release-packaging docs
Jun 7, 2022
0bad75d
add manual docs
Jun 7, 2022
8b7ddb1
rename manual_docs to local_docs
Jun 7, 2022
9130520
update CMake to respect new path name
Jun 7, 2022
2b4e43e
use more robust path for local docs
Jun 7, 2022
8b9e06c
add default arguments and buffer messages
Jun 7, 2022
396be28
en-quote
Jun 7, 2022
bdaed46
add max list size as argument
Jun 7, 2022
5b1ff3e
provide use case for spectrogram
Jun 7, 2022
b290c6e
caveat about manual interaction with slices
Jun 7, 2022
f5c8f4f
update descriptions and digest
Jun 8, 2022
7493815
return destination -> source
Jun 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,14 +172,17 @@ foreach(PACKAGE_DIRECTORY examples;extras;help;init;patchers;interfaces;javascri
endforeach(PACKAGE_DIRECTORY)

install(DIRECTORY "${flucoma-core_SOURCE_DIR}/Resources/AudioFiles/"
DESTINATION ${MAX_PACKAGE_ROOT}/media)
DESTINATION "${MAX_PACKAGE_ROOT}/media")
install(DIRECTORY "${flucoma-core_SOURCE_DIR}/Resources/Data/"
DESTINATION ${MAX_PACKAGE_ROOT}/misc)
DESTINATION "${MAX_PACKAGE_ROOT}/misc")
install(FILES icon.png package-info.json QuickStart.md
DESTINATION ${MAX_PACKAGE_ROOT})
install(FILES ${flucoma-core_SOURCE_DIR}/distribution.lic
DESTINATION ${MAX_PACKAGE_ROOT}
RENAME LICENSE.md)
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/local_docs/"
DESTINATION "${MAX_PACKAGE_ROOT}/docs")

if(DOCS)
install(DIRECTORY "${MAX_DOC_OUT}/"
DESTINATION "${MAX_PACKAGE_ROOT}/docs"
Expand Down
153 changes: 153 additions & 0 deletions local_docs/fluid.buf2list.maxref.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>
<!--
Part of the Fluid Corpus Manipulation Project (http://www.flucoma.org/)
Copyright 2017-2019 University of Huddersfield.
Licensed under the BSD-3 License.
See license.md file in the project root for full license information.
This project has received funding from the European Research Council (ERC)
under the European Union’s Horizon 2020 research and innovation programme
(grant agreement No 725899).
-->
<c74object name='fluid.buf2list' category='FluidCorpusManuipulation'>
<digest>Copy the contents of a buffer~ to a list</digest>
<description>A simplified workflow for extracting numerical data from buffers as lists of numbers.</description>
<discussion>
<h4><openfilelink filename="Fluid Corpus Manipulation Toolkit.maxpat">Open the Overview Patch</openfilelink></h4>
Given a source buffer that is valid, fluid.buf2list copies its contents to a new list when it receives a bang.

This is a convenient way of extracting data from a buffer to be used elsewhere.

<p>fluid.buf2list is part of the Fluid Decomposition Toolkit of the FluCoMa project. For more explanations, learning material, and discussions on its musicianly uses, visit <a href="http://www.flucoma.org/">flucoma.org</a>.</p>
</discussion>
<!--METADATA-->
<metadatalist>
<metadata name='author'>FluCoMa</metadata>
<metadata name='tag'>Fluid Decomposition</metadata>
<metadata name='tag'>corpus</metadata>
</metadatalist>

<inletlist>
</inletlist>

<outletlist>
</outletlist>

<objarglist>
<objarg name='maxsize' optional='1' type=''>
<digest>
Maximum list size
</digest>
<description>
Sets a maximum size for the internal list. The absolute maximum in Max is 32767.
</description>
<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='256' />
</attributelist>
</objarg>
</objarglist>

<!--MESSAGES-->
<methodlist>
Copy link
Member

@weefuzzy weefuzzy Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also a buffer message. Check the redundant xml I sent you just to see if we agree on the content?

Copy link
Member Author

@jamesb93 jamesb93 Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, so if a buffer object render that? I'll check the text in due course.

Copy link
Member Author

@jamesb93 jamesb93 Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Solved I think in 8b9e06c

<method name='bang'>
<arglist>
</arglist>
<description>


</description>
</method>

<method name="bang">
<arglist />
<digest>
Trigger processing
</digest>
<description>
Extract data from the <at>source</at> <o>buffer~</o>, given the current values of <at>startframe</at>, <at>numframes</at>, <at>startchan</at> and <at>numchans</at>.
</description>
</method>
<method name="buffer">
<arglist>
<!-- This should be true but isn't yet -->
Copy link
Member

@weefuzzy weefuzzy Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Glad you grabbed this: I'll probably push the update to make buffer do this tomorrow (it already does for the mainstream objects)

Copy link
Member Author

@jamesb93 jamesb93 Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great. It's a really handy shortcut for many things and cuts down on @ttribute hell.

<!-- <arg name= "buffer" optional='0' type="symbol" />
<arg name= "start frame" optional='1' type="long" />
<arg name= "number of frames" optional='1' type="long" />
<arg name= "start channel" optional='1' type="long" />
<arg name= "number of channels" optional='1' type="long" /> -->
</arglist>
<digest>
Set the source buffer~ and trigger processing
</digest>
<description>
Sets the value of <at>source</at><!-- and optionally <at>startframe</at>, <at>numframes</at>, <at>startchan</at>, <at>numchans</at>.--> Then processes as if <m>bang</m> had been called.
</description>
</method>
</methodlist>
<!--MESSAGES-->

<!--ATTRIBUTES-->
<attributelist>
<attribute name='axis' get='1' set='1' type='int' size='1'>
<digest>
Direction in which to copy from the <at>source</at>.
</digest>
<description>
In what direction to copy data from the <at>source</at>. <m>0</m> copies frame by frame, <m>1</m> copies channel-by-channel.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='0'>
</attribute>
</attributelist>

</attribute>
<attribute name='source' get='1' set='1' type='symbol' size='1'>
<digest>
The <o>buffer~</o> to copy the values from.
</digest>
<description>
Sets the source <o>buffer~</o> to copy data from.
</description>


</attribute>
<attribute name='startchan' get='1' set='1' type='int' size='1'>
<digest>
Start channel in <at>destination</at>.
</digest>
<description>
For multichannel input buffers, which channel to begin copying from. The default is 0.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='0'>
</attribute>
</attributelist>

</attribute>
<attribute name='startframe' get='1' set='1' type='int' size='1'>
<digest>
Start frame in <at>destination</at>.
</digest>
<description>
The starting index (in samples) to copy values from the <at>source</at> <o>buffer~</o>.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='0'>
</attribute>
</attributelist>

</attribute>
</attributelist>
<!--ATTRIBUTES-->

<!--RELATED-->
<seealsolist>
<seealso name='fluid.list2buf'/>
<seealso name='peek~'/>
<seealso name='poke~'/>
</seealsolist>
<!--RELATED-->
</c74object>
144 changes: 144 additions & 0 deletions local_docs/fluid.list2buf.maxref.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>
<!--
Part of the Fluid Corpus Manipulation Project (http://www.flucoma.org/)
Copyright 2017-2019 University of Huddersfield.
Licensed under the BSD-3 License.
See license.md file in the project root for full license information.
This project has received funding from the European Research Council (ERC)
under the European Union’s Horizon 2020 research and innovation programme
(grant agreement No 725899).
-->
<c74object name='fluid.list2buf' category='FluidCorpusManuipulation'>
<digest>Copy a list to a buffer~</digest>
<description>Copies the values of a list to a buffer~.</description>
<discussion>
<h4><openfilelink filename="Fluid Corpus Manipulation Toolkit.maxpat">Open the Overview Patch</openfilelink></h4>
fluid.list2buf copies the values of a list to a buffer~.

This is a convenient way of transforming data such that it can interface with other FluCoMa objects that expect to receive a buffer.

Be aware that if a buffer of a predefined size is not supplied as the output it will defer the copying. If you need the copying to occur in the high priority thread, supply a buffer with the size of the input.

<p>fluid.list2buf is part of the Fluid Decomposition Toolkit of the FluCoMa project. For more explanations, learning material, and discussions on its musicianly uses, visit <a href="http://www.flucoma.org/">flucoma.org</a>.</p>
</discussion>
<!--METADATA-->
<metadatalist>
<metadata name='author'>FluCoMa</metadata>
<metadata name='tag'>Fluid Decomposition</metadata>
<metadata name='tag'>corpus</metadata>
</metadatalist>

<inletlist>
</inletlist>

<outletlist>
</outletlist>

<objarglist>
<objarg name='maxsize' optional='1' type=''>
<digest>
Maximum list size
</digest>
<description>
Sets a maximum size for the internal list. The absolute maximum in Max is 32767.
</description>
<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='256' />
</attributelist>
</objarg>
</objarglist>

Copy link
Member

@weefuzzy weefuzzy Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'll be worth comparing mine and your XMLs for this file too: e.g. I have some docs for the list method and, more stuff in the description for the various bits

Copy link
Member Author

@jamesb93 jamesb93 Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah... it was commented out I think!

image

Copy link
Member Author

@jamesb93 jamesb93 Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this now in bdaed46

<!--MESSAGES-->
<methodlist>
<method name='list'>
<arglist>
</arglist>
Copy link
Member

@weefuzzy weefuzzy Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
</arglist>
<digest>
Trigger processing
</digest>

<description>

Copy link
Member

@weefuzzy weefuzzy Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Copy the values from the incoming list to the <at>destination</at> <o>buffer~</o>. If the buffer~ is not big enough, <at>autosize</at> is enabled and procesing is triggered from the main thread, then the buffer~ will be resized. If called from scheduler thread, no resize will be attempted and a warning will be printed to the console.


</description>
</method>

</methodlist>
<!--MESSAGES-->

<!--ATTRIBUTES-->
<attributelist>
<attribute name='autosize' get='1' set='1' type='int' size='1'>
<digest>
Determines if the output buffer will be resized according to the size of the input list.
</digest>
<description>
Sets whether the <at>destination</at> <o>buffer~</o> should be resized as needed. Note that this only applies when invoking from the main thread: buffer~s can not be resized from the high priority thread.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='1'>
</attribute>
</attributelist>

</attribute>
<attribute name='axis' get='1' set='1' type='int' size='1'>
<digest>
Direction in which to write to <at>destination</at>.
</digest>
<description>
In what direction to write data to <at>destination</at>. <m>0</m> writes frame by frame, <m>1</m> writes channel-by-channel.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='0'>
</attribute>
</attributelist>

</attribute>
<attribute name='destination' get='1' set='1' type='symbol' size='1'>
<digest>
The <o>buffer~</o> to copy the list values to.
</digest>
<description>
Sets the destination <o>buffer~</o> into which to write list data. If this is unset then the object will use its own automatically named <o>buffer~</o>.
</description>


</attribute>
<attribute name='startchan' get='1' set='1' type='int' size='1'>
<digest>
Start channel in <at>destination</at>.
</digest>
<description>
For multichannel output buffers, which channel to begin copying to. The default is 0.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='0'>
</attribute>
</attributelist>

</attribute>
<attribute name='startframe' get='1' set='1' type='int' size='1'>
<digest>
Start frame in <at>destination</at>.
</digest>
<description>
The starting index (in samples) to copy list to the <at>destination</at> <o>buffer~</o>.
</description>

<attributelist>
<attribute name='default' get='1' set='1' type='int' size='1' value='0'>
</attribute>
</attributelist>

</attribute>
</attributelist>
<!--ATTRIBUTES-->

<!--RELATED-->
<seealsolist>
<seealso name='fluid.buf2list'/>
<seealso name='peek~'/>
<seealso name='poke~'/>
</seealsolist>
<!--RELATED-->
</c74object>
Loading