diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile index 551d02111d..a88ec8070a 100644 --- a/doxygen/Doxyfile +++ b/doxygen/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.9.1 +# Doxyfile 1.8.10 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -343,6 +343,13 @@ IDL_PROPERTY_SUPPORT = YES DISTRIBUTE_GROUP_DOC = NO +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent @@ -758,7 +765,7 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = ../modules +INPUT = build # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -771,12 +778,17 @@ INPUT_ENCODING = UTF-8 # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank the -# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, -# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, -# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, -# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, -# *.qsf, *.as and *.js. +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, +# *.vhdl, *.ucf, *.qsf, *.as and *.js. FILE_PATTERNS = juce_*.h \ juce_*.dox @@ -794,53 +806,21 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = ../modules/juce_graphics/image_formats \ - ../modules/juce_core/zip/zlib \ - ../modules/juce_audio_formats/codecs/flac \ - ../modules/juce_audio_formats/codecs/oggvorbis \ - ../modules/juce_audio_basics/juce_audio_basics.h \ - ../modules/juce_audio_basics/juce_audio_basics.cpp \ - ../modules/juce_audio_devices/juce_audio_devices.h \ - ../modules/juce_audio_devices/juce_audio_devices.cpp \ - ../modules/juce_audio_devices/native \ - ../modules/juce_audio_formats/juce_audio_formats.h \ - ../modules/juce_audio_formats/juce_audio_formats.cpp \ - ../modules/juce_audio_plugin_client/juce_audio_plugin_client.h \ - ../modules/juce_audio_plugin_client/AU/CoreAudioUtilityClasses \ - ../modules/juce_audio_processors/juce_audio_processors.h \ - ../modules/juce_audio_processors/juce_audio_processors.cpp \ - ../modules/juce_audio_utils/juce_audio_utils.h \ - ../modules/juce_audio_utils/juce_audio_utils.cpp \ - ../modules/juce_browser_plugin_client/juce_browser_plugin.h \ - ../modules/juce_browser_plugin_client/juce_browser_plugin.cpp \ - ../modules/juce_core/juce_core.h \ - ../modules/juce_core/juce_core.cpp \ - ../modules/juce_core/native \ - ../modules/juce_cryptography/juce_cryptography.h \ - ../modules/juce_cryptography/juce_cryptography.cpp \ - ../modules/juce_data_structures/juce_data_structures.h \ - ../modules/juce_data_structures/juce_data_structures.cpp \ - ../modules/juce_events/juce_events.h \ - ../modules/juce_events/juce_events.cpp \ - ../modules/juce_events/native \ - ../modules/juce_graphics/juce_graphics.h \ - ../modules/juce_graphics/juce_graphics.cpp \ - ../modules/juce_graphics/native \ - ../modules/juce_gui_basics/juce_gui_basics.h \ - ../modules/juce_gui_basics/juce_gui_basics.cpp \ - ../modules/juce_gui_basics/native \ - ../modules/juce_gui_extra/juce_gui_extra.h \ - ../modules/juce_gui_extra/juce_gui_extra.cpp \ - ../modules/juce_gui_extra/native \ - ../modules/juce_opengl/juce_opengl.h \ - ../modules/juce_opengl/juce_opengl.cpp \ - ../modules/juce_opengl/native \ - ../modules/juce_tracktion_marketplace/juce_tracktion_marketplace.h \ - ../modules/juce_video/juce_video.h \ - ../modules/juce_video/juce_video.cpp \ - ../modules/juce_video/native \ - ../modules/juce_dsp/juce_dsp.h \ - ../modules/juce_dsp/juce_dsp.cpp +EXCLUDE = build/juce_graphics/image_formats \ + build/juce_core/zip/zlib \ + build/juce_audio_formats/codecs/flac \ + build/juce_audio_formats/codecs/oggvorbis \ + build/juce_audio_devices/native \ + build/juce_audio_plugin_client/AU/CoreAudioUtilityClasses \ + build/juce_browser_plugin_client/juce_browser_plugin.h \ + build/juce_core/native \ + build/juce_events/native \ + build/juce_graphics/native \ + build/juce_gui_basics/native \ + build/juce_gui_extra/native \ + build/juce_opengl/native \ + build/juce_video/native \ + build/juce_dsp/native # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1129,7 +1109,7 @@ HTML_HEADER = # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_FOOTER = footer.html +HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of @@ -1198,8 +1178,9 @@ HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: YES. +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_TIMESTAMP = YES @@ -1673,9 +1654,12 @@ COMPACT_LATEX = NO PAPER_TYPE = a4wide # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names -# that should be included in the LaTeX output. To get the times font for -# instance you can specify -# EXTRA_PACKAGES=times +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} # If left blank no extra packages will be included. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2057,9 +2041,12 @@ PREDEFINED = WIN32=1 \ JUCE_LINUX=1 \ DOXYGEN=1 \ JUCE_COMPILER_SUPPORTS_NOEXCEPT=1 \ + JUCE_COMPILER_SUPPORTS_NULLPTR=1 \ + JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS=1 \ JUCE_COMPILER_SUPPORTS_INITIALIZER_LISTS=1 \ JUCE_COMPILER_SUPPORTS_VARIADIC_TEMPLATES=1 \ JUCE_COMPILER_SUPPORTS_OVERRIDE_AND_FINAL=1 \ + JUCE_COMPILER_SUPPORTS_LAMBDAS=1 \ JUCE_MODAL_LOOPS_PERMITTED=1 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this @@ -2175,7 +2162,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: NO. -HAVE_DOT = NO +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of @@ -2287,7 +2274,8 @@ INCLUDED_BY_GRAPH = NO # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2298,7 +2286,8 @@ CALL_GRAPH = NO # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2321,15 +2310,19 @@ GRAPHICAL_HIERARCHY = NO DIRECTORY_GRAPH = NO # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, jpg, gif and svg. +# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_IMAGE_FORMAT = png +DOT_IMAGE_FORMAT = svg # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. @@ -2347,7 +2340,7 @@ INTERACTIVE_SVG = NO # found. If left blank, it is assumed the dot tool can be found in the path. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_PATH = +DOT_PATH = # The DOTFILE_DIRS tag can be used to specify one or more directories that # contain dot files that are included in the documentation (see the \dotfile @@ -2415,7 +2408,7 @@ MAX_DOT_GRAPH_DEPTH = 0 # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_TRANSPARENT = NO +DOT_TRANSPARENT = YES # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This @@ -2432,7 +2425,7 @@ DOT_MULTI_TARGETS = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -GENERATE_LEGEND = YES +GENERATE_LEGEND = NO # If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot # files that are used to generate the various graphs. diff --git a/doxygen/Makefile b/doxygen/Makefile new file mode 100644 index 0000000000..5b17c37169 --- /dev/null +++ b/doxygen/Makefile @@ -0,0 +1,16 @@ +SHELL := /bin/bash + +SOURCE_FILES := $(shell find ../modules -type f -name "juce_*.h" -or -name "juce_*.dox" | sed 's/ /\\ /g') + +.PHONEY: clean + +doc/index.html: build/juce_modules.dox Doxyfile + doxygen + +build/juce_modules.dox: process_source_files.py $(SOURCE_FILES) + rm -rf build + python $< ../modules build + +clean: + rm -rf build doc + diff --git a/doxygen/README.txt b/doxygen/README.txt index 3c39391cca..60a1511d35 100644 --- a/doxygen/README.txt +++ b/doxygen/README.txt @@ -6,5 +6,5 @@ How to: 1. install doxygen 2. cd into this directory on the command line -3. run doxygen (no additional arguments needed) -4. doxygen will create a new subfolder "doc". Open doc/index.html in your browser to access the generated HTML documentation. \ No newline at end of file +3. run `make` +4. doxygen will create a new subfolder "doc" - open doc/index.html in your browser to access the generated HTML documentation diff --git a/doxygen/footer.html b/doxygen/footer.html deleted file mode 100644 index e0635bceb9..0000000000 --- a/doxygen/footer.html +++ /dev/null @@ -1,14 +0,0 @@ -
-
All content © ROLI Ltd.

- - - diff --git a/doxygen/process_source_files.py b/doxygen/process_source_files.py new file mode 100644 index 0000000000..ebd6a77ebc --- /dev/null +++ b/doxygen/process_source_files.py @@ -0,0 +1,174 @@ +#!/usr/bin/env python + +import os +import shutil +import re +import argparse + + +def get_curly_brace_scope_end(string, start_pos): + """Given a string and the position of an opening curly brace, find the + position of the closing brace. + """ + if string[start_pos] != "{": + raise ValueError("string must have \"{\" at start pos") + string_end = len(string) + bracket_counter = 1 + start_pos += 1 + while start_pos < string_end: + if string[start_pos] == "{": + bracket_counter += 1 + elif string[start_pos] == "}": + bracket_counter -= 1 + if bracket_counter == 0: + return start_pos + start_pos += 1 + return -1 + + +def add_doxygen_group(path, group_name): + """Add a Doxygen group to the file at 'path'. + + Namespaces cause all kinds of problems, and we need to ensure that if + the classes in a source file are contained within a namespace then we + also put the @weakgroup inside the namespace. + """ + + filename = os.path.basename(path) + if re.match(r"^juce_.*\.(h|dox)", filename): + group_definition_start = ("\r\n/** @weakgroup " + + group_name + + "\r\n * @{\r\n */\r\n") + group_definition_end = "\r\n/** @}*/\r\n" + + with open(path, "r") as f: + content = f.read() + + # Put the group definitions inside all namespaces. + namespace_regex = re.compile(r"\s+namespace\s+\S+\s+{") + match = namespace_regex.search(content) + while (match is not None): + namespace_end = get_curly_brace_scope_end(content, match.end() - 1) + if namespace_end == -1: + raise ValueError("error finding end of namespace " + + match.group() + + " in " + + path) + content = (content[:match.end()] + + group_definition_start + + content[match.end():namespace_end] + + group_definition_end + + content[namespace_end:]) + search_start = (namespace_end + + len(group_definition_start) + + len(group_definition_end)) + + match = namespace_regex.search(content, search_start) + + with open(path, "w") as f: + f.write(group_definition_start) + f.write(content) + f.write(group_definition_end) + + +############################################################################### + +if __name__ == "__main__": + + parser = argparse.ArgumentParser() + parser.add_argument("source_dir", + help="the directory to search for source files") + parser.add_argument("dest_dir", + help="the directory in which to place processed files") + parser.add_argument("--subdirs", + help="if specified, only include these comma separated" + "subdirectories") + args = parser.parse_args() + + # Get the list of JUCE modules to include. + if args.subdirs: + juce_modules = args.subdirs.split(",") + else: + juce_modules = [] + for item in os.listdir(args.source_dir): + if os.path.isdir(os.path.join(args.source_dir, item)): + juce_modules.append(item) + + # Copy the JUCE modules to the temporary directory, and process the source + # files. + module_definitions = [] + for module_name in juce_modules: + + # Copy the required modules. + original_module_dir = os.path.join(args.source_dir, module_name) + module_path = os.path.join(args.dest_dir, module_name) + shutil.copytree(original_module_dir, module_path) + + # Parse the module header to get module information. + module_header = os.path.join(module_path, module_name + ".h") + with open(module_header, "r") as f: + content = f.read() + block_info_result = re.match(r".*BEGIN_JUCE_MODULE_DECLARATION" + "(.*)" + "END_JUCE_MODULE_DECLARATION.*", + content, + re.DOTALL) + detail_lines = [] + for line in block_info_result.group(1).split("\n"): + stripped_line = line.strip() + if stripped_line: + result = re.match(r"^.*?description:\s*(.*)$", stripped_line) + if result: + short_description = result.group(1) + else: + detail_lines.append(stripped_line) + + # The module header causes problems for Doxygen, so delete it. + os.remove(module_header) + + # Create a Doxygen group definition for the module. + module_definiton = [] + module_definiton.append("/** @defgroup {n} {n}".format(n=module_name)) + module_definiton.append(" {d}".format(d=short_description)) + module_definiton.append("") + for line in detail_lines: + module_definiton.append(" - {l}".format(l=line)) + module_definiton.append("") + module_definiton.append(" @{") + module_definiton.append("*/") + + # Create a list of the directories in the module that we can use as + # subgroups and create the Doxygen group hierarchy string. + dir_contents = os.listdir(module_path) + subdirs = [x for x in dir_contents + if os.path.isdir(os.path.join(module_path, x))] + module_groups = {} + for subdir in subdirs: + subgroup_name = "{n}-{s}".format(n=module_name, s=subdir) + module_groups[subgroup_name] = os.path.join(module_path, subdir) + module_definiton.append("") + module_definiton.append( + "/** @defgroup {tag} {n} */".format(tag=subgroup_name, n=subdir) + ) + module_definiton.append("") + module_definiton.append("/** @} */") + + module_definitions.append("\r\n".join(module_definiton)) + + # Put the top level files into the main group. + for filename in (set(dir_contents) - set(subdirs)): + add_doxygen_group(os.path.join(module_path, filename), module_name) + + # Put subdirectory files into their respective groups. + for group_name in module_groups: + for dirpath, dirnames, filenames in os.walk(module_groups[group_name]): + for filename in filenames: + try: + add_doxygen_group(os.path.join(dirpath, filename), group_name) + except: + print("Error preprocessing " + filename) + continue + + # Create an extra header file containing the module hierarchy. + with open(os.path.join(args.dest_dir, "juce_modules.dox"), "w") as f: + f.write("\r\n\r\n".join(module_definitions)) diff --git a/extras/BLOCKS/doxygen/Makefile b/extras/BLOCKS/doxygen/Makefile index e160a10aba..8f12d700f4 100644 --- a/extras/BLOCKS/doxygen/Makefile +++ b/extras/BLOCKS/doxygen/Makefile @@ -1,6 +1,8 @@ SHELL := /bin/bash -SOURCE_FILES := $(shell find ../../../modules -type f -name "juce_*.h" | sed 's/ /\\ /g') +INCLUDED_MODULES := juce_audio_basics,juce_audio_devices,juce_blocks_basics,juce_core,juce_events + +SOURCE_FILES := $(shell find ../../../modules -type f -name "juce_*.h" -or -name "juce_*.dox"| sed 's/ /\\ /g') EXAMPLE_DIRS := ../standalone_sdk/examples ../../../examples/BLOCKS EXAMPLE_SOURCE_FILES := $(foreach DIR,$(EXAMPLE_DIRS),$(shell find $(DIR) -type f -name "*.h" -or -name "*.cpp" | sed 's/ /\\ /g')) DOCUMENTATION_FILES := $(shell find pages -type f -name "*.dox" | sed 's/ /\\ /g') @@ -11,8 +13,9 @@ IMAGES := $(shell find images -type f | sed 's/ /\\ /g') doc/index.html: build/juce_modules.dox Doxyfile DoxygenLayout.xml footer.html header.html stylesheet.css $(DOCUMENTATION_FILES) $(EXAMPLE_SOURCE_FILES) $(IMAGES) doxygen -build/juce_modules.dox: process_source_files.py $(SOURCE_FILES) - python $< +build/juce_modules.dox: ../../../doxygen/process_source_files.py $(SOURCE_FILES) + rm -rf build + python $< ../../../modules build --subdirs=$(INCLUDED_MODULES) clean: rm -rf build doc diff --git a/extras/BLOCKS/doxygen/process_source_files.py b/extras/BLOCKS/doxygen/process_source_files.py deleted file mode 100644 index 01f7ab3e4e..0000000000 --- a/extras/BLOCKS/doxygen/process_source_files.py +++ /dev/null @@ -1,163 +0,0 @@ -import os -import shutil -import re - - -def get_curly_brace_scope_end(string, start_pos): - """Given a string and the position of an opening curly brace, find the - position of the closing brace. - """ - if string[start_pos] != "{": - raise ValueError("string must have \"{\" at start pos") - string_end = len(string) - bracket_counter = 1 - start_pos += 1 - while start_pos < string_end: - if string[start_pos] == "{": - bracket_counter += 1 - elif string[start_pos] == "}": - bracket_counter -= 1 - if bracket_counter == 0: - return start_pos - start_pos += 1 - return -1 - - -def add_doxygen_group(path, group_name): - """Add a Doxygen group to the file at 'path'. - - Namespaces cause all kinds of problems, and we need to ensure that if - the classes in a source file are contained within a namespace then we - also put the @weakgroup inside. - """ - filename = os.path.basename(path) - if filename.startswith("juce_") and filename.endswith(".h"): - - group_definition_start = ("\r\n/** @weakgroup " - + group_name - + "\r\n * @{\r\n */\r\n") - group_definition_end = "\r\n/** @}*/\r\n" - - with open(path, "r") as f: - content = f.read() - - # Put the group definitions inside all namespaces. - namespace_regex = re.compile(r"\s+namespace\s+\S+\s+{") - match = namespace_regex.search(content) - while (match is not None): - namespace_end = get_curly_brace_scope_end(content, match.end() - 1) - if namespace_end == -1: - raise ValueError("error finding end of namespace " - + match.group() - + " in " - + path) - content = (content[:match.end()] - + group_definition_start - + content[match.end():namespace_end] - + group_definition_end - + content[namespace_end:]) - search_start = (namespace_end - + len(group_definition_start) - + len(group_definition_end)) - - match = namespace_regex.search(content, search_start) - - with open(path, "w") as f: - f.write(group_definition_start) - f.write(content) - f.write(group_definition_end) - - -############################################################################### - -# Get the list of JUCE modules to include. -juce_modules = ("juce_audio_basics", "juce_audio_devices", - "juce_blocks_basics", "juce_core", "juce_events") - -# A temporary directory to hold our preprocessed source files. -build_directory = "build" - -# Make sure we have a clean temporary directory. -try: - shutil.rmtree(build_directory) -except OSError as e: - if e.errno != 2: - # An errno of 2 indicates that the directory does not exist, which is - # fine! - raise e - -# Copy the JUCE modules to the temporary directory, and process the source -# files. -module_definitions = [] -for module_name in juce_modules: - - # Copy the required modules. - original_module_dir = os.path.join("..", "..", "..", "modules", - module_name) - module_path = os.path.join(build_directory, module_name) - shutil.copytree(original_module_dir, module_path) - - # Parse the module header to get module information. - module_header = os.path.join(module_path, module_name + ".h") - with open(module_header, "r") as f: - content = f.read() - block_info_result = re.match(r".*BEGIN_JUCE_MODULE_DECLARATION" - "(.*)" - "END_JUCE_MODULE_DECLARATION.*", - content, - re.DOTALL) - detail_lines = [] - for line in block_info_result.group(1).split("\n"): - stripped_line = line.strip() - if stripped_line: - result = re.match(r"^.*?description:\s*(.*)$", stripped_line) - if result: - short_description = result.group(1) - else: - detail_lines.append(stripped_line) - - # The module header causes problems for Doxygen, so delete it. - os.remove(module_header) - - # Create a Doxygen group definition for the module. - module_definiton = [] - module_definiton.append("/** @defgroup {n} {n}".format(n=module_name)) - module_definiton.append(" {d}".format(d=short_description)) - module_definiton.append("") - for line in detail_lines: - module_definiton.append(" - {l}".format(l=line)) - module_definiton.append("") - module_definiton.append(" @{") - module_definiton.append("*/") - - # Create a list of internal directories we can use as subgroups and create - # the Doxygen group hierarchy string. - dir_contents = os.listdir(module_path) - subdirs = [x for x in dir_contents - if os.path.isdir(os.path.join(module_path, x))] - module_groups = {} - for subdir in subdirs: - subgroup_name = "{n}-{s}".format(n=module_name, s=subdir) - module_groups[subgroup_name] = os.path.join(module_path, subdir) - module_definiton.append("") - module_definiton.append( - "/** @defgroup {tag} {n} */".format(tag=subgroup_name, n=subdir) - ) - module_definiton.append("") - module_definiton.append("/** @} */") - - module_definitions.append("\r\n".join(module_definiton)) - - # Put the top level files into the main group. - for filename in (set(dir_contents) - set(subdirs)): - add_doxygen_group(os.path.join(module_path, filename), module_name) - - # Put subdirectory files into their respective groups. - for group_name in module_groups: - for dirpath, dirnames, filenames in os.walk(module_groups[group_name]): - for filename in filenames: - add_doxygen_group(os.path.join(dirpath, filename), group_name) - -# Create an extra header file containing the module hierarchy. -with open(os.path.join(build_directory, "juce_modules.dox"), "w") as f: - f.write("\r\n\r\n".join(module_definitions)) diff --git a/modules/juce_blocks_basics/LittleFootFunctions.txt b/modules/juce_blocks_basics/juce_LittleFootFunctions.dox similarity index 79% rename from modules/juce_blocks_basics/LittleFootFunctions.txt rename to modules/juce_blocks_basics/juce_LittleFootFunctions.dox index 92c7ad8395..9ebdb286eb 100644 --- a/modules/juce_blocks_basics/LittleFootFunctions.txt +++ b/modules/juce_blocks_basics/juce_LittleFootFunctions.dox @@ -1,981 +1,985 @@ -/** - * @defgroup Graphics Graphics functions - * @defgroup Midi Midi functions - * @defgroup Callbacks Callbacks from the OS - * @defgroup Maths Math functions - * @defgroup Memory Memory Access functions - * @defgroup Debug Debugging functions - * @defgroup Configs Configuration functions - * @defgroup Messaging Messaging functions - * @defgroup Clustering Cluster functions - * @defgroup Topology Topology functions - * @defgroup Touch Touch functions - * @defgroup Lightpad Lightpad specific functions - * @defgroup ControlBlock Control Block specific functions - * @defgroup Seaboard Seaboard specific functions - * @defgroup Power Power functions - * @defgroup Utility Utility functions - * @defgroup Internal Internal functions (not for general usage) - */ - - -/** Reads and returns the value of a single byte from the heap. - - @param byteIndex the index (in bytes) of the byte to read - @returns the value of the byte - - @ingroup Memory -*/ -int getHeapByte (int byteIndex); - -/** Reads 4 bytes from the heap and returns the value as an integer. - - @param byteIndex the index (in bytes) of the start of the 4 bytes to read - @returns the value of the 4 bytes as an integer - - @ingroup Memory -*/ -int getHeapInt (int byteIndex); - -/** Reads a sequence of bits from the heap and returns the value as an integer. - - @param startBitIndex the index (in bits) of the start of the sequence of bits to read - @param numBits how many bits to read - @returns the value of the sequence of bits as an integer - - @ingroup Memory -*/ -int getHeapBits (int startBitIndex, int numBits); - -/** Writes a single byte to the heap. - - @param byteIndex the index (in bytes) of the byte to set - @param newValue the new value to set this byte to - - @ingroup Memory -*/ -void setHeapByte (int byteIndex, int newValue); - -/** Writes 4 bytes to the heap. - - @param byteIndex the index (in bytes) of the start of the 4 bytes to set - @param newValue the new value to set the 4 bytes to - - @ingroup Memory -*/ -void setHeapInt (int byteIndex, int newValue); - -/** Returns the smaller of two integer values. - - @param a The first parameter - @param b The second parameter - @retval The minimum of a and b - - @ingroup Maths - */ -int min (int a, int b); - -/** Returns the smaller of two floating point values. - - @param a The first parameter - @param b The second parameter - @retval The minimum of a and b - - @ingroup Maths - */ -float min (float a, float b); - -/** Returns the larger of two integer values. - - @param a The first parameter - @param b The second parameter - @retval The maximum of a and b - - @ingroup Maths - */ -int max (int a, int b); - -/** Returns the larger of two floating point values. - - @param a The first parameter - @param b The second parameter - @retval The maximum of a and b - - @ingroup Maths - */ -float max (float a, float b); - -/** Constrains an integer value to keep it within a given range. - - @param lowerLimit the minimum value to return - @param upperLimit the maximum value to return - @param valueToConstrain the value to try to return - @returns the closest value to valueToConstrain which lies between lowerLimit - and upperLimit (inclusive) - - @ingroup Maths -*/ -int clamp (int lowerLimit, int upperLimit, int valueToConstrain); - -/** Constrains a floating point value to keep it within a given range. - - @param lowerLimit the minimum value to return - @param upperLimit the maximum value to return - @param valueToConstrain the value to try to return - @returns the closest value to valueToConstrain which lies between lowerLimit - and upperLimit (inclusive) - - @ingroup Maths -*/ -float clamp (float lowerLimit, float upperLimit, float valueToConstrain); - -/** Returns the absolute value of an integer value. - - @param arg The argument to compute the absolute value of - @retval either -arg if arg is negative or arg if arg is positive - - @ingroup Maths -*/ -int abs (int arg); - -/** Returns the absolute value of a floating point value. - - @param arg The argument to compute the absolute value of - @retval either -arg if arg is negative or arg if arg is positive - - @ingroup Maths -*/ -float abs (float arg); - -/** Remaps a value from a source range to a target range. - - @param value the value within the source range to map - @param sourceMin the minimum value of the source range - @param sourceMax the maximum value of the source range - @param destMin the minumum value of the destination range - @param destMax the maximum value of the destination range - @returns the original value mapped to the destination range - - @ingroup Maths -*/ -float map (float value, float sourceMin, float sourceMax, float destMin, float destMax); - -/** Remaps a value from a source range to the range 0 - 1.0. - - @param value the value within the source range to map - @param sourceMin the minimum value of the source range - @param sourceMax the maximum value of the source range - @returns the original value mapped to the range 0 - 1.0 - - @ingroup Maths -*/ -float map (float value, float sourceMin, float sourceMax); - -/** Performs a modulo operation (can cope with the dividend being negative). - The divisor must be greater than zero. - - @returns the result of the modulo operation - - @ingroup Maths -*/ -int mod (int dividend, int divisor); - -/** Returns a random floating-point number. - - @returns a random value in the range 0 (inclusive) to 1.0 (exclusive) - - @ingroup Maths -*/ -float getRandomFloat(); - -/** Returns a random integer, limited to a given range. - - @returns a random integer between 0 (inclusive) and maxValue (exclusive). - - @ingroup Maths -*/ -int getRandomInt (int maxValue); - -/** Returns the number of milliseconds since a fixed event (usually system startup). - - @returns a monotonically increasing value which is unaffected by changes to the - system clock. It should be accurate to within a few millisecseconds. - - @ingroup Maths -*/ -int getMillisecondCounter(); - -/** Returns the length of time spent in the current function call in milliseconds. - - @returns the length of time spent in the current function call in milliseconds. - - @ingroup Maths -*/ -int getTimeInCurrentFunctionCall(); - -/** Logs an integer value to the console. - - @param data The 32 bit signed integer to log to the topology as an integer - - @ingroup Debug - */ -void log (int data); - -/** Logs a hexadecimal value to the console. - - @param data The 32 bit signed integer to log to the topology as a hexidecimal int - - @ingroup Debug - */ -void logHex (int data); - -/** Sends a 1-byte short midi message. - @ingroup Midi -*/ -void sendMIDI (int byte0); - -/** Sends a 2-byte short midi message. - @ingroup Midi -*/ -void sendMIDI (int byte0, int byte1); - -/** Sends a 3-byte short midi message. - @ingroup Midi -*/ -void sendMIDI (int byte0, int byte1, int byte2); - -/** Sends a key-down message. - - @param channel the midi channel, in the range 0 to 15 - @param noteNumber the key number, in the range 0 to 127 - @param velocity the velocity, in the range 0 to 127 - - @ingroup Midi -*/ -void sendNoteOn (int channel, int noteNumber, int velocity); - -/** Sends a key-up message. - - @param channel the midi channel, in the range 0 to 15 - @param noteNumber the key number, in the range 0 to 127 - @param velocity the velocity, in the range 0 to 127 - - @ingroup Midi -*/ -void sendNoteOff (int channel, int noteNumber, int velocity); - -/** Sends an aftertouch message. - - @param channel the midi channel, in the range 0 to 15 - @param noteNumber the key number, in the range 0 to 127 - @param level the amount of aftertouch, in the range 0 to 127 - - @ingroup Midi -*/ -void sendAftertouch (int channel, int noteNumber, int level); - -/** Sends a controller message. - - @param channel the midi channel, in the range 0 to 15 - @param controller the type of controller - @param value the controller value - - @ingroup Midi -*/ -void sendCC (int channel, int controller, int value); - -/** Sends a pitch bend message. - - @param channel the midi channel, in the range 0 to 15 - @param position the wheel position, in the range 0 to 16383 - - @ingroup Midi -*/ -void sendPitchBend (int channel, int position); - -/** Sends a channel-pressure change event. - - @param channel the midi channel, in the range 0 to 15 - @param pressure the pressure, in the range 0 to 127 - - @ingroup Midi -*/ -void sendChannelPressure (int channel, int pressure); - -/** Sets the MIDI channel range. - - @param useMPE - @param lowChannel - @param highChannel - - @ingroup Midi -*/ -void setChannelRange (bool useMPE, int lowChannel, int highChannel); - -/** Assigns a MIDI channel to a note number. - - @param noteNumber the note number to assign the channel to - @returns the MIDI channel that has been assigned - - @ingroup Midi -*/ -int assignChannel (int noteNumber); - -/** Deassigns a channel from a note number. - - @param noteNumber the note number to deassign - @param channel the MIDI channel - - @ingroup Midi -*/ -void deassignChannel (int noteNumber, int channel); - -/** Returns the channel that is being used for control messages. - - @returns the channel that is being used for control messages. (If MPE is enabled then this will be the first channel.) - - @ingroup Midi -*/ -int getControlChannel(); - -/** Sets whether duplicate notes should be filtered out when MPE is enabled. - - @ingroup Midi -*/ -void useMPEDuplicateFilter (bool active); - -/** Use this method to draw the display. - The block will call this approximately 25 times per second. - - @ingroup Callbacks -*/ -void repaint() - -/** Called when a button is pushed. - - @param index the index of the button that was pushed - - @ingroup Callbacks -*/ -void handleButtonDown (int index); - -/** Called when a button is released. - - @param index the index of the button that was released - - @ingroup Callbacks -*/ -void handleButtonUp (int index); - -/** Called when a control block button is pressed. - - @param buttonIndex the index of the button - - @ingroup Callbacks - - @note Requires >= 0.2.5 firmware - @note Only valid with a control block - */ -void onControlPress (int buttonIndex); - -/** Called when a control block button is released. - - @param buttonIndex the index of the button - - @ingroup Callbacks - - @note Requires >= 0.2.5 firmware - @note Only valid with a control block - */ -void onControlRelease (int buttonIndex); - -/** Called when a touch event starts. - - @param index the touch index, which will stay constant for each finger as it is tracked - @param x the X position of this touch on the device, in block units starting from 0 (left) - @param y the Y position of this touch on the device, in block units starting from 0 (top) - @param z the current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard) - @param vz the rate at which pressure is currently changing, measured in units/second - - @ingroup Touch -*/ -void touchStart (int index, float x, float y, float z, float vz); - -/** Called when a touch event moves. - - @param index the touch index, which will stay constant for each finger as it is tracked - @param x the X position of this touch on the device, in block units starting from 0 (left) - @param y the Y position of this touch on the device, in block units starting from 0 (top) - @param z the current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard) - @param vz the rate at which pressure is currently changing, measured in units/second - - @ingroup Touch -*/ -void touchMove (int index, float x, float y, float z, float vz); - -/** Called when a touch event ends. - - @param index the touch index, which will stay constant for each finger as it is tracked - @param x the X position of this touch on the device, in block units starting from 0 (left) - @param y the Y position of this touch on the device, in block units starting from 0 (top) - @param z the current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard) - @param vz the rate at which pressure is currently changing, measured in units/second - - @ingroup Touch -*/ -void touchEnd (int index, float x, float y, float z, float vz); - -/** Called when a program is loaded onto the block and is about to start. Do any setup here. - - @ingroup Callbacks -*/ -void initialise(); - -/** Called when a block receives a MIDI message. - - @ingroup Midi -*/ -void handleMIDI (int byte0, int byte1, int byte2); - -/** Called when a block receives a message. - - @see sendMessageToBlock - @ingroup Messaging - */ -void handleMessage (int param1, int param2, int param3); - -/** Combines a set of 8-bit ARGB values into a 32-bit colour and returns the result. - - @return a 32-bit colour - @param alpha The alpha in range 0 - 255 inclusive - @param red The red in range 0 - 255 inclusive - @param green The green in range 0 - 255 inclusive - @param blue The blue in range 0 - 255 inclusive - - @ingroup Graphics -*/ -int makeARGB (int alpha, int red, int green, int blue); - -/** Blends the overlaid ARGB colour onto the base one and returns the new colour. - - @param baseColour the colour to blend on to - @param overlaidColour The colour to blend in to the baseColour - @returns The blended colour - - @ingroup Graphics -*/ -int blendARGB (int baseColour, int overlaidColour); - -/** Displays an animation indicating the current battery level of this block. - A control block will light up its top LEDs indicating battery level and a lightpad - block will draw the battery level on the display. - - @ingroup Graphics - - @note Requires >= 0.2.5 firmware -*/ -void displayBatteryLevel(); - -/** Clears the display and sets all the LEDs to black. - - @ingroup Graphics -*/ -void clearDisplay(); - -/** Clears the display and sets all the LEDs to a specified colour. - - @param rgb the colour to use (0xff...) - - @ingroup Graphics -*/ -void clearDisplay (int rgb); - -/** Sets a pixel to a specified colour with full alpha. - - @param rgb the colour to use (0xff...) - @param x the x coordinate of the pixel to fill - @param y the y coordinate of the pixel to fill - - @ingroup Graphics -*/ -void fillPixel (int rgb, int x, int y); - -/** Blends the current pixel colour with a specified colour. - - @param argb the colour to use - @param x the x coordinate of the pixel to blend - @param y the y coordinate of the pixel to blend - - @ingroup Graphics -*/ -void blendPixel (int argb, int x, int y); - -/** Fills a rectangle on the display with a specified colour. - - @param rgb the colour to use (0xff...) - @param x the x coordinate of the rectangle to draw - @param y the y coordinate of the rectangle to draw - @param width the width of the rectangle to draw - @param height the height of the rectangle to draw - - @ingroup Graphics -*/ -void fillRect (int rgb, int x, int y, int width, int height); - -/** Blends a rectangle on the display with a specified colour. - - @param argb the colour to use - @param x the x coordinate of the rectangle to blend - @param y the y coordinate of the rectangle to blend - @param width the width of the rectangle to blend - @param height the height of the rectangle to blend - - @ingroup Graphics -*/ -void blendRect (int argb, int x, int y, int width, int height); - -/** Fills a rectangle on the display with four corner colours blended together. - - @param colourNW the colour to use in the north west corner of the rectangle - @param colourNE the colour to use in the north east corner of the rectangle - @param colourSE the colour to use in the south east corner of the rectangle - @param colourSW the colour to use in the south west corner of the rectangle - @param x the x coordinate of the rectangle - @param y the y coordinate of the rectangle - @param width the width of the rectangle - @param height the height of the rectangle - - @ingroup Graphics -*/ -void blendGradientRect (int colourNW, int colourNE, int colourSE, int colourSW, int x, int y, int width, int height); - -/** Blends a circle on the display with a specified colour. - - @param argb the colour to use - @param xCentre the x position of the circle's centre in block units - @param yCentre the y position of the circle's centre in block units - @param radius the radius of the circle in block units - @param fill if true then the circle will be filled, if false the circle will be an outline - - @ingroup Graphics - - @note Requires >= 0.2.5 firmware -*/ -void blendCircle (int argb, float xCentre, float yCentre, float radius, bool fill); - -/** Draws a number on the display. - - @param value the number to draw between 0 and 99 - @param colour the colour to use - @param x the x coordinate to use - @param y the y coordinate to use - - @ingroup Graphics -*/ -void drawNumber (int value, int colour, int x, int y); - -/** Returns the current firmware version of this block. - - @returns The firmware version of the form 0xMJMIRV (where MJ = Major, MI = Minor, RV = Revision) - - @ingroup Utility - - @note Requires >= 0.2.5 firmware -*/ -int getFirmwareVersion(); - -/** Returns the battery level of this block, between 0 and 1.0. - - @returns the battery level of this block, between 0 and 1.0. - - @ingroup Power - - @note Requires >= 0.2.5 firmware -*/ -float getBatteryLevel(); - -/** Returns true if this block's battery is charging. - - @returns true if this block's battery is charging - - @ingroup Power - - @note Requires >= 0.2.5 firmware -*/ -bool isBatteryCharging(); - -/** Sets whether status overlays should be displayed on this block. - - @ingroup Utility - - @note Requires >= 0.2.5 firmware -*/ -void setStatusOverlayActive (bool active); - -/** Sets whether power saving mode should be enabled on this block. - - @ingroup Power - - @note Requires >= 0.2.5 firmware -*/ -void setPowerSavingEnabled (bool enabled); - -/** Returns the type of the block with a given ID. - - @returns an enum indicating the type of block @see Block::Type - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getBlockTypeForID (int blockID); - -/** Sends a message to the block with the specified ID. - This will be processed in the handleMessage() callback. - - @param blockID the ID of the block to send this message to - @param param1 the first chunk of data to send - @param param2 the second chunk of data to send - @param param3 the third chunk of data to send - - @ingroup Messaging -*/ -void sendMessageToBlock (int blockID, int param1, int param2, int param3); - -/** Sends a message to the host. To receive this the host will need to implement - the Block::ProgramEventListener::handleProgramEvent() method. - - @param param1 the first chunk of data to send - @param param2 the second chunk of data to send - @param param3 the third chunk of data to send - - @ingroup Messaging -*/ -void sendMessageToHost (int param1, int param2, int param3); - -/** Draws a pressure point with a specified colour and pressure. - - @param argb the colour to use - @param touchX the x position of the touch in block units - @param touchY the y position of the touch in block units - @param touchZ the pressure value of the touch - - @ingroup Lightpad -*/ -void addPressurePoint (int argb, float touchX, float touchY, float touchZ); - -/** Draws the pressure map on the display. - @ingroup Lightpad -*/ -void drawPressureMap(); - -/** Fades the pressure map on the display. - @ingroup Lightpad -*/ -void fadePressureMap(); - -/** Links a another block to this control block. - - @param blockID the ID of the block to link - - @ingroup ControlBlock - - @note Requires >= 0.2.5 firmware - @note Only valid with a control block -*/ -void linkBlockIDtoController (int blockID); - -/** Repaints the control block display. - - @ingroup ControlBlock - - @note Requires >= 0.2.5 firmware - @note Only valid with a control block -*/ -void repaintControl(); - -/** Initialises one of the control block buttons. - - @param buttonIndex the index of the button to initialise - @param modeToUse the mode to use for this button @see ControlMode - @param outputType the control type to use @see ControlType - @param val the current value to set this button to - @param min the minimum value for this button - @param max the maximum value for this button - @param index the item index - @param onColourToUse the colour to use when this button is on - @param offColourToUse the colour to use when this button is off - - @ingroup ControlBlock - - @note Requires >= 0.2.5 firmware - @note Only valid with a control block -*/ -void initControl (int buttonIndex, int modeToUse, int outputType, int val, int min, int max, - int index, int onColourToUse, int offColourToUse); - -/** Control type for use with initControl - - @see initControl - - @ingroup ControlBlock -*/ -enum ControlType -{ - internalConfig = 0, - midiCC, - sysex -}; - -/** Control mode for use with initControl - - @see initControl - - @ingroup ControlBlock -*/ -enum ControlMode -{ - toggle = 0, - togglePulse, - gate, - trigger, - cycle, - incDec, - triState -}; - -/** Forces a touch event to be handled as seaboard playing. - - @param touchIndex the index of the touch event - - @ingroup Seaboard - - @note Requires >= 0.2.5 firmware - @note Only valid on a Seaboard -*/ -void handleTouchAsSeaboard (int touchIndex); - -/** Returns the number of blocks in the current topology. - @ingroup Topology - - @note Requires >= 0.2.5 firmware -*/ -int getNumBlocksInTopology(); - -/** Returns the ID of a block at a given index in the topology. - - @param index The index of the block to find in the topology - @returns int The id of the block - - @ingroup Topology - - @note Requires >= 0.2.5 firmware -*/ -int getBlockIDForIndex (int index); - -/** Returns true if this block is directly connected to the host, - as opposed to only being connected to a different block via a connection port. - - @ingroup Topology - - @note Requires >= 0.2.5 firmware -*/ -bool isMasterBlock(); - -/** Returns true if this block is connected to the host computer, this can be - directly or through connections to other blocks. - - @ingroup Topology - - @note Requires >= 0.2.5 firmware -*/ -bool isConnectedToHost(); - -/** Returns the ID of a block connected to a specified port on this block. - @ingroup Topology - - @note Requires >= 0.2.5 firmware -*/ -int getBlockIDOnPort (int port); - -/** Returns the port number that is connected to the master block. Returns 0xFF if there is - no port connected to master. - - @returns the port number that is connected to the master block. Returns 0xFF if there is - no port connected to master. - - @ingroup Topology - - @note Requires >= 0.2.5 firmware -*/ -int getPortToMaster(); - -/** Returns the horizontal distance between this block and the master block in block units. - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getHorizontalDistFromMaster(); - -/** Returns the vertical distance between this block and the master block in block units. - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getVerticalDistFromMaster(); - -/** Returns the angle of this block relative to the master block in degrees. - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getAngleFromMaster(); - -/** Sets whether this block should auto-rotate when its angle relative to the master block changes. - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -void setAutoRotate (bool enabled); - -/** Returns the index of this block in the current cluster. - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getClusterIndex(); - -/** Returns how many blocks wide the current cluster is. - - @returns the width of the cluster (note that a single block will return 1 here) - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getClusterWidth(); - -/** Returns how many blocks high the current cluster is. - - @returns the height of the cluster (note that a single block will return 1 here) - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getClusterHeight(); - -/** Returns the x index of this block in the current cluster. - - @returns int The cluster x position. (0, 0) is considered to be the top left block - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getClusterXpos(); - -/** Returns the y index of this block in the current cluster. - - @returns int The cluster x position. (0, 0) is considered to be the top left block - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getClusterYpos(); - -/** Returns the number of blocks in the current cluster. - - @returns the number of blocks in the current cluster. - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getNumBlocksInCurrentCluster(); - -/** Returns the block ID for a block in the current cluster. - - @param index the cluster index of the block to get the ID of - - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -int getBlockIdForBlockInCluster (int index); - -/** Returns true if the master block is in the current cluster. - @ingroup Clustering - - @note Requires >= 0.2.5 firmware -*/ -bool isMasterInCurrentCluster(); - -/** Returns current value of one of the local config items. - - @param item the config item to get (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) - - @ingroup Configs - - @note Requires >= 0.2.5 firmware -*/ -int getLocalConfig (int item); - -/** Sets the current value of one of the local config items. - - @param item the config item to set the value of (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) - @param value the value to set the config to - - @ingroup Configs - - @note Requires >= 0.2.5 firmware -*/ -void setLocalConfig (int item, int value); - -/** Sets the local config of a block to the config item of a remote block. - - @param longAddress the address of the remote block - @param item the config item (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) - - @ingroup Configs - - @note Requires >= 0.2.5 firmware -*/ -void requestRemoteConfig (int longAddress, int item); - -/** Sets the config of a remote block. - - @param longAddress the address of the remote block - @param item the config item (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) - @param value the value to set the config to - - @ingroup Configs - - @note Requires >= 0.2.5 firmware -*/ -void setRemoteConfig (int longAddress, int item, int value); - -/** Sets the range of one of the local config items. - - @param item the config item to set the range of (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) - @param min the minimum value this config item should use - @param max the maximum value this config item should use - - @ingroup Configs - - @note Requires >= 0.2.5 firmware -*/ -void setLocalConfigItemRange (int item, int min, int max); - -/** Sets whether a local config item should be active. - - @param item the config item to set active (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) - @param isActive sets whether the config should be active or not - @param saveToFlash if true then this config item will be saved to the flash memory of the block - - @ingroup Configs - - @note Requires >= 0.2.5 firmware -*/ -void setLocalConfigActiveState (int item, bool isActive, bool saveToFlash); +/** @defgroup LittleFootFunctions LittleFoot Functions + Functions available in the LittleFoot language + @{ + + @defgroup LittleFootFunctions-Graphics Graphics functions + @defgroup LittleFootFunctions-MIDI MIDI functions + @defgroup LittleFootFunctions-Callbacks Callbacks from the OS + @defgroup LittleFootFunctions-Maths Math functions + @defgroup LittleFootFunctions-Memory Memory Access functions + @defgroup LittleFootFunctions-Debug Debugging functions + @defgroup LittleFootFunctions-Configs Configuration functions + @defgroup LittleFootFunctions-Messaging Messaging functions + @defgroup LittleFootFunctions-Clustering Cluster functions + @defgroup LittleFootFunctions-Topology Topology functions + @defgroup LittleFootFunctions-Touch Touch functions + @defgroup LittleFootFunctions-Lightpad Lightpad specific functions + @defgroup LittleFootFunctions-ControlBlock Control Block specific functions + @defgroup LittleFootFunctions-Seaboard Seaboard specific functions + @defgroup LittleFootFunctions-Power Power functions + @defgroup LittleFootFunctions-Utility Utility functions + @defgroup LittleFootFunctions-Internal Internal functions (not for general usage) +*/ + +/** Reads and returns the value of a single byte from the heap. + + @param byteIndex the index (in bytes) of the byte to read + @returns the value of the byte + + @ingroup LittleFootFunctions-Memory +*/ +int getHeapByte (int byteIndex); + +/** Reads 4 bytes from the heap and returns the value as an integer. + + @param byteIndex the index (in bytes) of the start of the 4 bytes to read + @returns the value of the 4 bytes as an integer + + @ingroup LittleFootFunctions-Memory +*/ +int getHeapInt (int byteIndex); + +/** Reads a sequence of bits from the heap and returns the value as an integer. + + @param startBitIndex the index (in bits) of the start of the sequence of bits to read + @param numBits how many bits to read + @returns the value of the sequence of bits as an integer + + @ingroup LittleFootFunctions-Memory +*/ +int getHeapBits (int startBitIndex, int numBits); + +/** Writes a single byte to the heap. + + @param byteIndex the index (in bytes) of the byte to set + @param newValue the new value to set this byte to + + @ingroup LittleFootFunctions-Memory +*/ +void setHeapByte (int byteIndex, int newValue); + +/** Writes 4 bytes to the heap. + + @param byteIndex the index (in bytes) of the start of the 4 bytes to set + @param newValue the new value to set the 4 bytes to + + @ingroup LittleFootFunctions-Memory +*/ +void setHeapInt (int byteIndex, int newValue); + +/** Returns the smaller of two integer values. + + @param a The first parameter + @param b The second parameter + @retval The minimum of a and b + + @ingroup LittleFootFunctions-Maths +*/ +int min (int a, int b); + +/** Returns the smaller of two floating point values. + + @param a The first parameter + @param b The second parameter + @retval The minimum of a and b + + @ingroup LittleFootFunctions-Maths +*/ +float min (float a, float b); + +/** Returns the larger of two integer values. + + @param a The first parameter + @param b The second parameter + @retval The maximum of a and b + + @ingroup LittleFootFunctions-Maths +*/ +int max (int a, int b); + +/** Returns the larger of two floating point values. + + @param a The first parameter + @param b The second parameter + @retval The maximum of a and b + + @ingroup LittleFootFunctions-Maths +*/ +float max (float a, float b); + +/** Constrains an integer value to keep it within a given range. + + @param lowerLimit the minimum value to return + @param upperLimit the maximum value to return + @param valueToConstrain the value to try to return + @returns the closest value to valueToConstrain which lies between lowerLimit + and upperLimit (inclusive) + + @ingroup LittleFootFunctions-Maths +*/ +int clamp (int lowerLimit, int upperLimit, int valueToConstrain); + +/** Constrains a floating point value to keep it within a given range. + + @param lowerLimit the minimum value to return + @param upperLimit the maximum value to return + @param valueToConstrain the value to try to return + @returns the closest value to valueToConstrain which lies between lowerLimit + and upperLimit (inclusive) + + @ingroup LittleFootFunctions-Maths +*/ +float clamp (float lowerLimit, float upperLimit, float valueToConstrain); + +/** Returns the absolute value of an integer value. + + @param arg The argument to compute the absolute value of + @retval either -arg if arg is negative or arg if arg is positive + + @ingroup LittleFootFunctions-Maths +*/ +int abs (int arg); + +/** Returns the absolute value of a floating point value. + + @param arg The argument to compute the absolute value of + @retval either -arg if arg is negative or arg if arg is positive + + @ingroup LittleFootFunctions-Maths +*/ +float abs (float arg); + +/** Remaps a value from a source range to a target range. + + @param value the value within the source range to map + @param sourceMin the minimum value of the source range + @param sourceMax the maximum value of the source range + @param destMin the minumum value of the destination range + @param destMax the maximum value of the destination range + @returns the original value mapped to the destination range + + @ingroup LittleFootFunctions-Maths +*/ +float map (float value, float sourceMin, float sourceMax, float destMin, float destMax); + +/** Remaps a value from a source range to the range 0 - 1.0. + + @param value the value within the source range to map + @param sourceMin the minimum value of the source range + @param sourceMax the maximum value of the source range + @returns the original value mapped to the range 0 - 1.0 + + @ingroup LittleFootFunctions-Maths +*/ +float map (float value, float sourceMin, float sourceMax); + +/** Performs a modulo operation (can cope with the dividend being negative). + The divisor must be greater than zero. + + @returns the result of the modulo operation + + @ingroup LittleFootFunctions-Maths +*/ +int mod (int dividend, int divisor); + +/** Returns a random floating-point number. + + @returns a random value in the range 0 (inclusive) to 1.0 (exclusive) + + @ingroup LittleFootFunctions-Maths +*/ +float getRandomFloat(); + +/** Returns a random integer, limited to a given range. + + @returns a random integer between 0 (inclusive) and maxValue (exclusive). + + @ingroup LittleFootFunctions-Maths +*/ +int getRandomInt (int maxValue); + +/** Returns the number of milliseconds since a fixed event (usually system startup). + + @returns a monotonically increasing value which is unaffected by changes to the + system clock. It should be accurate to within a few millisecseconds. + + @ingroup LittleFootFunctions-Maths +*/ +int getMillisecondCounter(); + +/** Returns the length of time spent in the current function call in milliseconds. + + @returns the length of time spent in the current function call in milliseconds. + + @ingroup LittleFootFunctions-Maths +*/ +int getTimeInCurrentFunctionCall(); + +/** Logs an integer value to the console. + + @param data The 32 bit signed integer to log to the topology as an integer + + @ingroup LittleFootFunctions-Debug +*/ +void log (int data); + +/** Logs a hexadecimal value to the console. + + @param data The 32 bit signed integer to log to the topology as a hexidecimal int + + @ingroup LittleFootFunctions-Debug +*/ +void logHex (int data); + +/** Sends a 1-byte short midi message. + @ingroup LittleFootFunctions-MIDI +*/ +void sendMIDI (int byte0); + +/** Sends a 2-byte short midi message. + @ingroup LittleFootFunctions-MIDI +*/ +void sendMIDI (int byte0, int byte1); + +/** Sends a 3-byte short midi message. + @ingroup LittleFootFunctions-MIDI +*/ +void sendMIDI (int byte0, int byte1, int byte2); + +/** Sends a key-down message. + + @param channel the midi channel, in the range 0 to 15 + @param noteNumber the key number, in the range 0 to 127 + @param velocity the velocity, in the range 0 to 127 + + @ingroup LittleFootFunctions-MIDI +*/ +void sendNoteOn (int channel, int noteNumber, int velocity); + +/** Sends a key-up message. + + @param channel the midi channel, in the range 0 to 15 + @param noteNumber the key number, in the range 0 to 127 + @param velocity the velocity, in the range 0 to 127 + + @ingroup LittleFootFunctions-MIDI +*/ +void sendNoteOff (int channel, int noteNumber, int velocity); + +/** Sends an aftertouch message. + + @param channel the midi channel, in the range 0 to 15 + @param noteNumber the key number, in the range 0 to 127 + @param level the amount of aftertouch, in the range 0 to 127 + + @ingroup LittleFootFunctions-MIDI +*/ +void sendAftertouch (int channel, int noteNumber, int level); + +/** Sends a controller message. + + @param channel the midi channel, in the range 0 to 15 + @param controller the type of controller + @param value the controller value + + @ingroup LittleFootFunctions-MIDI +*/ +void sendCC (int channel, int controller, int value); + +/** Sends a pitch bend message. + + @param channel the midi channel, in the range 0 to 15 + @param position the wheel position, in the range 0 to 16383 + + @ingroup LittleFootFunctions-MIDI +*/ +void sendPitchBend (int channel, int position); + +/** Sends a channel-pressure change event. + + @param channel the midi channel, in the range 0 to 15 + @param pressure the pressure, in the range 0 to 127 + + @ingroup LittleFootFunctions-MIDI +*/ +void sendChannelPressure (int channel, int pressure); + +/** Sets the MIDI channel range. + + @param useMPE + @param lowChannel + @param highChannel + + @ingroup LittleFootFunctions-MIDI +*/ +void setChannelRange (bool useMPE, int lowChannel, int highChannel); + +/** Assigns a MIDI channel to a note number. + + @param noteNumber the note number to assign the channel to + @returns the MIDI channel that has been assigned + + @ingroup LittleFootFunctions-MIDI +*/ +int assignChannel (int noteNumber); + +/** Deassigns a channel from a note number. + + @param noteNumber the note number to deassign + @param channel the MIDI channel + + @ingroup LittleFootFunctions-MIDI +*/ +void deassignChannel (int noteNumber, int channel); + +/** Returns the channel that is being used for control messages. + + @returns the channel that is being used for control messages. (If MPE is enabled then this will be the first channel.) + + @ingroup LittleFootFunctions-MIDI +*/ +int getControlChannel(); + +/** Sets whether duplicate notes should be filtered out when MPE is enabled. + + @ingroup LittleFootFunctions-MIDI +*/ +void useMPEDuplicateFilter (bool active); + +/** Use this method to draw the display. + The block will call this approximately 25 times per second. + + @ingroup LittleFootFunctions-Callbacks +*/ +void repaint(); + +/** Called when a button is pushed. + + @param index the index of the button that was pushed + + @ingroup LittleFootFunctions-Callbacks +*/ +void handleButtonDown (int index); + +/** Called when a button is released. + + @param index the index of the button that was released + + @ingroup LittleFootFunctions-Callbacks +*/ +void handleButtonUp (int index); + +/** Called when a control block button is pressed. + + @param buttonIndex the index of the button + + @ingroup LittleFootFunctions-Callbacks + + @note Requires >= 0.2.5 firmware + @note Only valid with a control block +*/ +void onControlPress (int buttonIndex); + +/** Called when a control block button is released. + + @param buttonIndex the index of the button + + @ingroup LittleFootFunctions-Callbacks + + @note Requires >= 0.2.5 firmware + @note Only valid with a control block +*/ +void onControlRelease (int buttonIndex); + +/** Called when a touch event starts. + + @param index the touch index, which will stay constant for each finger as it is tracked + @param x the X position of this touch on the device, in block units starting from 0 (left) + @param y the Y position of this touch on the device, in block units starting from 0 (top) + @param z the current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard) + @param vz the rate at which pressure is currently changing, measured in units/second + + @ingroup LittleFootFunctions-Touch +*/ +void touchStart (int index, float x, float y, float z, float vz); + +/** Called when a touch event moves. + + @param index the touch index, which will stay constant for each finger as it is tracked + @param x the X position of this touch on the device, in block units starting from 0 (left) + @param y the Y position of this touch on the device, in block units starting from 0 (top) + @param z the current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard) + @param vz the rate at which pressure is currently changing, measured in units/second + + @ingroup LittleFootFunctions-Touch +*/ +void touchMove (int index, float x, float y, float z, float vz); + +/** Called when a touch event ends. + + @param index the touch index, which will stay constant for each finger as it is tracked + @param x the X position of this touch on the device, in block units starting from 0 (left) + @param y the Y position of this touch on the device, in block units starting from 0 (top) + @param z the current pressure of this touch, in the range 0.0 (no pressure) to 1.0 (very hard) + @param vz the rate at which pressure is currently changing, measured in units/second + + @ingroup LittleFootFunctions-Touch +*/ +void touchEnd (int index, float x, float y, float z, float vz); + +/** Called when a program is loaded onto the block and is about to start. Do any setup here. + + @ingroup LittleFootFunctions-Callbacks +*/ +void initialise(); + +/** Called when a block receives a MIDI message. + + @ingroup LittleFootFunctions-MIDI +*/ +void handleMIDI (int byte0, int byte1, int byte2); + +/** Called when a block receives a message. + + @see sendMessageToBlock + @ingroup LittleFootFunctions-Messaging +*/ +void handleMessage (int param1, int param2, int param3); + +/** Combines a set of 8-bit ARGB values into a 32-bit colour and returns the result. + + @return a 32-bit colour + @param alpha The alpha in range 0 - 255 inclusive + @param red The red in range 0 - 255 inclusive + @param green The green in range 0 - 255 inclusive + @param blue The blue in range 0 - 255 inclusive + + @ingroup LittleFootFunctions-Graphics +*/ +int makeARGB (int alpha, int red, int green, int blue); + +/** Blends the overlaid ARGB colour onto the base one and returns the new colour. + + @param baseColour the colour to blend on to + @param overlaidColour The colour to blend in to the baseColour + @returns The blended colour + + @ingroup LittleFootFunctions-Graphics +*/ +int blendARGB (int baseColour, int overlaidColour); + +/** Displays an animation indicating the current battery level of this block. + A control block will light up its top LEDs indicating battery level and a lightpad + block will draw the battery level on the display. + + @ingroup LittleFootFunctions-Graphics + + @note Requires >= 0.2.5 firmware +*/ +void displayBatteryLevel(); + +/** Clears the display and sets all the LEDs to black. + + @ingroup LittleFootFunctions-Graphics +*/ +void clearDisplay(); + +/** Clears the display and sets all the LEDs to a specified colour. + + @param rgb the colour to use (0xff...) + + @ingroup LittleFootFunctions-Graphics +*/ +void clearDisplay (int rgb); + +/** Sets a pixel to a specified colour with full alpha. + + @param rgb the colour to use (0xff...) + @param x the x coordinate of the pixel to fill + @param y the y coordinate of the pixel to fill + + @ingroup LittleFootFunctions-Graphics +*/ +void fillPixel (int rgb, int x, int y); + +/** Blends the current pixel colour with a specified colour. + + @param argb the colour to use + @param x the x coordinate of the pixel to blend + @param y the y coordinate of the pixel to blend + + @ingroup LittleFootFunctions-Graphics +*/ +void blendPixel (int argb, int x, int y); + +/** Fills a rectangle on the display with a specified colour. + + @param rgb the colour to use (0xff...) + @param x the x coordinate of the rectangle to draw + @param y the y coordinate of the rectangle to draw + @param width the width of the rectangle to draw + @param height the height of the rectangle to draw + + @ingroup LittleFootFunctions-Graphics +*/ +void fillRect (int rgb, int x, int y, int width, int height); + +/** Blends a rectangle on the display with a specified colour. + + @param argb the colour to use + @param x the x coordinate of the rectangle to blend + @param y the y coordinate of the rectangle to blend + @param width the width of the rectangle to blend + @param height the height of the rectangle to blend + + @ingroup LittleFootFunctions-Graphics +*/ +void blendRect (int argb, int x, int y, int width, int height); + +/** Fills a rectangle on the display with four corner colours blended together. + + @param colourNW the colour to use in the north west corner of the rectangle + @param colourNE the colour to use in the north east corner of the rectangle + @param colourSE the colour to use in the south east corner of the rectangle + @param colourSW the colour to use in the south west corner of the rectangle + @param x the x coordinate of the rectangle + @param y the y coordinate of the rectangle + @param width the width of the rectangle + @param height the height of the rectangle + + @ingroup LittleFootFunctions-Graphics +*/ +void blendGradientRect (int colourNW, int colourNE, int colourSE, int colourSW, int x, int y, int width, int height); + +/** Blends a circle on the display with a specified colour. + + @param argb the colour to use + @param xCentre the x position of the circle's centre in block units + @param yCentre the y position of the circle's centre in block units + @param radius the radius of the circle in block units + @param fill if true then the circle will be filled, if false the circle will be an outline + + @ingroup LittleFootFunctions-Graphics + + @note Requires >= 0.2.5 firmware +*/ +void blendCircle (int argb, float xCentre, float yCentre, float radius, bool fill); + +/** Draws a number on the display. + + @param value the number to draw between 0 and 99 + @param colour the colour to use + @param x the x coordinate to use + @param y the y coordinate to use + + @ingroup LittleFootFunctions-Graphics +*/ +void drawNumber (int value, int colour, int x, int y); + +/** Returns the current firmware version of this block. + + @returns The firmware version of the form 0xMJMIRV (where MJ = Major, MI = Minor, RV = Revision) + + @ingroup LittleFootFunctions-Utility + + @note Requires >= 0.2.5 firmware +*/ +int getFirmwareVersion(); + +/** Returns the battery level of this block, between 0 and 1.0. + + @returns the battery level of this block, between 0 and 1.0. + + @ingroup LittleFootFunctions-Power + + @note Requires >= 0.2.5 firmware +*/ +float getBatteryLevel(); + +/** Returns true if this block's battery is charging. + + @returns true if this block's battery is charging + + @ingroup LittleFootFunctions-Power + + @note Requires >= 0.2.5 firmware +*/ +bool isBatteryCharging(); + +/** Sets whether status overlays should be displayed on this block. + + @ingroup LittleFootFunctions-Utility + + @note Requires >= 0.2.5 firmware +*/ +void setStatusOverlayActive (bool active); + +/** Sets whether power saving mode should be enabled on this block. + + @ingroup LittleFootFunctions-Power + + @note Requires >= 0.2.5 firmware +*/ +void setPowerSavingEnabled (bool enabled); + +/** Returns the type of the block with a given ID. + + @returns an enum indicating the type of block @see Block::Type + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getBlockTypeForID (int blockID); + +/** Sends a message to the block with the specified ID. + This will be processed in the handleMessage() callback. + + @param blockID the ID of the block to send this message to + @param param1 the first chunk of data to send + @param param2 the second chunk of data to send + @param param3 the third chunk of data to send + + @ingroup LittleFootFunctions-Messaging +*/ +void sendMessageToBlock (int blockID, int param1, int param2, int param3); + +/** Sends a message to the host. To receive this the host will need to implement + the Block::ProgramEventListener::handleProgramEvent() method. + + @param param1 the first chunk of data to send + @param param2 the second chunk of data to send + @param param3 the third chunk of data to send + + @ingroup LittleFootFunctions-Messaging +*/ +void sendMessageToHost (int param1, int param2, int param3); + +/** Draws a pressure point with a specified colour and pressure. + + @param argb the colour to use + @param touchX the x position of the touch in block units + @param touchY the y position of the touch in block units + @param touchZ the pressure value of the touch + + @ingroup LittleFootFunctions-Lightpad +*/ +void addPressurePoint (int argb, float touchX, float touchY, float touchZ); + +/** Draws the pressure map on the display. + @ingroup LittleFootFunctions-Lightpad +*/ +void drawPressureMap(); + +/** Fades the pressure map on the display. + @ingroup LittleFootFunctions-Lightpad +*/ +void fadePressureMap(); + +/** Links a another block to this control block. + + @param blockID the ID of the block to link + + @ingroup LittleFootFunctions-ControlBlock + + @note Requires >= 0.2.5 firmware + @note Only valid with a control block +*/ +void linkBlockIDtoController (int blockID); + +/** Repaints the control block display. + + @ingroup LittleFootFunctions-ControlBlock + + @note Requires >= 0.2.5 firmware + @note Only valid with a control block +*/ +void repaintControl(); + +/** Initialises one of the control block buttons. + + @param buttonIndex the index of the button to initialise + @param modeToUse the mode to use for this button @see ControlMode + @param outputType the control type to use @see ControlType + @param val the current value to set this button to + @param min the minimum value for this button + @param max the maximum value for this button + @param index the item index + @param onColourToUse the colour to use when this button is on + @param offColourToUse the colour to use when this button is off + + @ingroup LittleFootFunctions-ControlBlock + + @note Requires >= 0.2.5 firmware + @note Only valid with a control block +*/ +void initControl (int buttonIndex, int modeToUse, int outputType, int val, int min, int max, + int index, int onColourToUse, int offColourToUse); + +/** Control type for use with initControl + + @see initControl + + @ingroup LittleFootFunctions-ControlBlock +*/ +enum ControlType +{ + internalConfig = 0, + midiCC, + sysex +}; + +/** Control mode for use with initControl + + @see initControl + + @ingroup LittleFootFunctions-ControlBlock +*/ +enum ControlMode +{ + toggle = 0, + togglePulse, + gate, + trigger, + cycle, + incDec, + triState +}; + +/** Forces a touch event to be handled as seaboard playing. + + @param touchIndex the index of the touch event + + @ingroup LittleFootFunctions-Seaboard + + @note Requires >= 0.2.5 firmware + @note Only valid on a Seaboard +*/ +void handleTouchAsSeaboard (int touchIndex); + +/** Returns the number of blocks in the current topology. + @ingroup LittleFootFunctions-Topology + + @note Requires >= 0.2.5 firmware +*/ +int getNumBlocksInTopology(); + +/** Returns the ID of a block at a given index in the topology. + + @param index The index of the block to find in the topology + @returns int The id of the block + + @ingroup LittleFootFunctions-Topology + + @note Requires >= 0.2.5 firmware +*/ +int getBlockIDForIndex (int index); + +/** Returns true if this block is directly connected to the host, + as opposed to only being connected to a different block via a connection port. + + @ingroup LittleFootFunctions-Topology + + @note Requires >= 0.2.5 firmware +*/ +bool isMasterBlock(); + +/** Returns true if this block is connected to the host computer, this can be + directly or through connections to other blocks. + + @ingroup LittleFootFunctions-Topology + + @note Requires >= 0.2.5 firmware +*/ +bool isConnectedToHost(); + +/** Returns the ID of a block connected to a specified port on this block. + @ingroup LittleFootFunctions-Topology + + @note Requires >= 0.2.5 firmware +*/ +int getBlockIDOnPort (int port); + +/** Returns the port number that is connected to the master block. Returns 0xFF if there is + no port connected to master. + + @returns the port number that is connected to the master block. Returns 0xFF if there is + no port connected to master. + + @ingroup LittleFootFunctions-Topology + + @note Requires >= 0.2.5 firmware +*/ +int getPortToMaster(); + +/** Returns the horizontal distance between this block and the master block in block units. + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getHorizontalDistFromMaster(); + +/** Returns the vertical distance between this block and the master block in block units. + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getVerticalDistFromMaster(); + +/** Returns the angle of this block relative to the master block in degrees. + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getAngleFromMaster(); + +/** Sets whether this block should auto-rotate when its angle relative to the master block changes. + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +void setAutoRotate (bool enabled); + +/** Returns the index of this block in the current cluster. + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getClusterIndex(); + +/** Returns how many blocks wide the current cluster is. + + @returns the width of the cluster (note that a single block will return 1 here) + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getClusterWidth(); + +/** Returns how many blocks high the current cluster is. + + @returns the height of the cluster (note that a single block will return 1 here) + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getClusterHeight(); + +/** Returns the x index of this block in the current cluster. + + @returns int The cluster x position. (0, 0) is considered to be the top left block + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getClusterXpos(); + +/** Returns the y index of this block in the current cluster. + + @returns int The cluster x position. (0, 0) is considered to be the top left block + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getClusterYpos(); + +/** Returns the number of blocks in the current cluster. + + @returns the number of blocks in the current cluster. + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getNumBlocksInCurrentCluster(); + +/** Returns the block ID for a block in the current cluster. + + @param index the cluster index of the block to get the ID of + + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +int getBlockIdForBlockInCluster (int index); + +/** Returns true if the master block is in the current cluster. + @ingroup LittleFootFunctions-Clustering + + @note Requires >= 0.2.5 firmware +*/ +bool isMasterInCurrentCluster(); + +/** Returns current value of one of the local config items. + + @param item the config item to get (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) + + @ingroup LittleFootFunctions-Configs + + @note Requires >= 0.2.5 firmware +*/ +int getLocalConfig (int item); + +/** Sets the current value of one of the local config items. + + @param item the config item to set the value of (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) + @param value the value to set the config to + + @ingroup LittleFootFunctions-Configs + + @note Requires >= 0.2.5 firmware +*/ +void setLocalConfig (int item, int value); + +/** Sets the local config of a block to the config item of a remote block. + + @param longAddress the address of the remote block + @param item the config item (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) + + @ingroup LittleFootFunctions-Configs + + @note Requires >= 0.2.5 firmware +*/ +void requestRemoteConfig (int longAddress, int item); + +/** Sets the config of a remote block. + + @param longAddress the address of the remote block + @param item the config item (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) + @param value the value to set the config to + + @ingroup LittleFootFunctions-Configs + + @note Requires >= 0.2.5 firmware +*/ +void setRemoteConfig (int longAddress, int item, int value); + +/** Sets the range of one of the local config items. + + @param item the config item to set the range of (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) + @param min the minimum value this config item should use + @param max the maximum value this config item should use + + @ingroup LittleFootFunctions-Configs + + @note Requires >= 0.2.5 firmware +*/ +void setLocalConfigItemRange (int item, int min, int max); + +/** Sets whether a local config item should be active. + + @param item the config item to set active (see ConfigItemId enum in juce_BlocksProtocolDefinitions.h) + @param isActive sets whether the config should be active or not + @param saveToFlash if true then this config item will be saved to the flash memory of the block + + @ingroup LittleFootFunctions-Configs + + @note Requires >= 0.2.5 firmware +*/ +void setLocalConfigActiveState (int item, bool isActive, bool saveToFlash); + +/** @} */