Inside Playdate with C

Allocates heap space if ptr is NULL, else reallocates the given pointer. If size is zero, frees the given pointer.

Calls the log function, outputting an error in red to the console, then pauses execution.

title will be the title displayed by the menu item.

Adds a new menu item to the System Menu. When invoked by the user, this menu item will:

Your game can then present an options interface to the player, or take other action, in whatever manner you choose.

The returned menu item is freed when removed from the menu; it does not need to be freed manually.

Adds a new menu item that can be checked or unchecked by the player.

title will be the title displayed by the menu item.

value should be 0 for unchecked, 1 for checked.

If this menu item is interacted with while the system menu is open, callback will be called when the menu is closed.

The returned menu item is freed when removed from the menu; it does not need to be freed manually.

Adds a new menu item that allows the player to cycle through a set of options.

title will be the title displayed by the menu item.

options should be an array of strings representing the states this menu item can cycle through. Due to limited horizontal space, the option strings and title should be kept short for this type of menu item.

optionsCount should be the number of items contained in options.

If this menu item is interacted with while the system menu is open, callback will be called when the menu is closed.

The returned menu item is freed when removed from the menu; it does not need to be freed manually.

Removes the menu item from the system menu.

Removes all custom menu items from the system menu.

Gets or sets the display title of the menu item.

Gets or sets the integer value of the menu item.

For checkmark menu items, 1 means checked, 0 unchecked. For option menu items, the value indicates the array index of the currently selected option.

Gets or sets the userdata value associated with this menu item.

Returns the number of milliseconds since…​some arbitrary point in time. This should present a consistent timebase while a game is running, but the counter will be disabled when the device is sleeping.

Returns the number of seconds (and sets milliseconds if not NULL) elapsed since midnight (hour 0), January 1, 2000.

Resets the high-resolution timer.

Returns the number of seconds since playdate.resetElapsedTime() was called. The value is a floating-point number with microsecond accuracy.

Returns the system timezone offset from GMT, in seconds.

Converts the given epoch time to a PDDateTime.

Converts the given PDDateTime to an epoch time.

Returns 1 if the user has set the 24-Hour Time preference in the Settings program.

Returns 1 if the global "flipped" system setting is set, otherwise 0.

Returns 1 if the global "reduce flashing" system setting is set, otherwise 0.

Creates a formatted string and returns it via the outstring argument. The arguments and return value match libc’s asprintf(): the format string is standard printf() style, the string returned in outstring should be freed by the caller when it’s no longer in use, and the return value is the length of the formatted string.

Allocates and formats a string using a variadic va_list argument, in the style of vasprintf(). The string returned via ret should be freed by the caller when it is no longer in use. The return value from the function is the length of the formatted string.

Like libc sscanf(), parses a string according to a format string and places the values into pointers passed in after the format. The return value is the number of items matched.

A game can optionally provide an image to be displayed alongside the system menu. bitmap must be a 400x240 LCDBitmap. All important content should be in the left half of the image in an area 200 pixels wide, as the menu will obscure the rest. The right side of the image will be visible briefly as the menu animates in and out.

Optionally, a non-zero xoffset, can be provided. This must be a number between 0 and 200 and will cause the menu image to animate to a position offset left by xoffset pixels as the menu is animated in.

This function could be called in response to the kEventPause event in your implementation of eventHandler().

Replaces the default Lua run loop function with a custom update function. The update function should return a non-zero number to tell the system to update the display, or zero if update isn’t needed.

Provides a callback to receive messages sent to the device over the serial port using the msg command. If no device is connected, you can send these messages to a game in the simulator by entering !msg <message> in the Lua console.

Calculates the current frames per second and draws that value at x, y.

Returns a value from 0-100 denoting the current level of battery charge. 0 = empty; 100 = full.

Returns the battery’s current voltage level.

Flush the CPU instruction cache, on the very unlikely chance you’re modifying instruction code on the fly. (If you don’t know what I’m talking about, you don’t need this. :smile:)

Returns a new SoundChannel object.

Frees the given SoundChannel.

Adds a SoundSource to the channel. If a source is not assigned to a channel, it plays on the default global channel.

Removes a SoundSource to the channel. Returns 1 if the source was found in (and removed from) the channel, otherwise 0.

Adds a SoundEffect to the channel.

Removes a SoundEffect from the channel.

Sets the volume for the channel, in the range [0-1].

Gets the volume for the channel, in the range [0-1].

Sets a signal to modulate the channel volume. Set to NULL to clear the modulator.

Gets a signal modulating the channel volume.

Sets the pan parameter for the channel. Valid values are in the range [-1,1], where -1 is left, 0 is center, and 1 is right.

Sets a signal to modulate the channel pan. Set to NULL to clear the modulator.

Gets a signal modulating the channel pan.

Creates a new SoundSource using the given data provider callback and adds it to the channel.

This function should fill the passed-in left buffer (and right if it’s a stereo source) with len samples each and return 1, or return 0 if the source is silent through the cycle. The caller takes ownership of the allocated SoundSource, and should free it with

when it is not longer in use.

Returns a signal that follows the volume of the channel before effects are applied.

Returns a signal that follows the volume of the channel after effects are applied.

Sets the playback volume (0.0 - 1.0) for left and right channels of the source.

Gets the playback volume (0.0 - 1.0) for left and right channels of the source.

Returns 1 if the source is currently playing.

Sets a function to be called when the source has finished playing.

Allocates and returns a new AudioSample with a buffer large enough to load a file of length bytes.

Loads the sound data from the file at path into an existing AudioSample, sample.

Allocates and returns a new AudioSample, with the sound data loaded in memory. If there is no file at path, the function returns null.

If the sample is ADPCM compressed, decompresses the sample data to 16-bit PCM data. This increases the sample’s memory footprint by 4x and does not affect the quality in any way, but it is necessary if you want to use the sample in a synth or play the file backwards. Returns 1 if successful, 0 if there’s not enough memory for the uncompressed data.

Returns a new AudioSample referencing the given audio data. If shouldFreeData is set, data is freed when the sample object is freed. The sample keeps a pointer to the data instead of copying it, so the data must remain valid while the sample is active. format is one of the following values:

pd_api_sound.h also provides some helper macros and functions:

Frees the given sample. If the sample was created with playdate→sound→sample→newSampleFromData() and the shouldFreeData flag was set, the sample’s source data is also freed.

Returns the length, in seconds, of sample.

Allocates a new FilePlayer.

Frees the given player.

Prepares player to stream the file at path. Returns 1 if the file exists, otherwise 0.

Pauses the file player.

Starts playing the file player. If repeat is greater than one, it loops the given number of times. If zero, it loops endlessly until it is stopped with playdate->sound->fileplayer->stop(). Returns 1 on success, 0 if buffer allocation failed.

Returns one if player is playing, zero if not.

Sets the buffer length of player to bufferLen seconds;

Returns the length, in seconds, of the file loaded into player.

Sets a function to be called when playback has completed. This is an alias for playdate→sound→source→setFinishCallback().

Returns one if player has underrun, zero if not.

Sets the start and end of the loop region for playback, in seconds. If end is omitted, the end of the file is used.

Sets the current offset in seconds.

Returns the current offset in seconds for player.

Sets the playback rate for the player. 1.0 is normal speed, 0.5 is down an octave, 2.0 is up an octave, etc. Unlike sampleplayers, fileplayers can’t play in reverse (i.e., rate < 0).

Returns the playback rate for player.

If flag evaluates to true, the player will restart playback (after an audible stutter) as soon as data is available.

Sets the playback volume for left and right channels of player.

Gets the left and right channel playback volume for player.

Stops playing the file.

Changes the volume of the fileplayer to left and right over a length of len sample frames, then calls the provided callback (if set).

Returns the length, in seconds, of the sample assigned to player.

Returns one if player is playing a sample, zero if not.

Allocates and returns a new SamplePlayer.

Starts playing the sample in player.

If repeat is greater than one, it loops the given number of times. If zero, it loops endlessly until it is stopped with playdate->sound->sampleplayer->stop(). If negative one, it does ping-pong looping.

rate is the playback rate for the sample; 1.0 is normal speed, 0.5 is down an octave, 2.0 is up an octave, etc.

Returns 1 on success (which is always, currently).

Sets a function to be called when playback has completed. See sndCallbackProc.

Sets the current offset of the SamplePlayer, in seconds.

Returns the current offset in seconds for player.

When used with a repeat of -1, does ping-pong looping, with a start and end position in frames.

Pauses or resumes playback.

Sets the playback rate for the player. 1.0 is normal speed, 0.5 is down an octave, 2.0 is up an octave, etc. A negative rate produces backwards playback for PCM files, but does not work for ADPCM-encoded files.

Returns the playback rate for player.

Assigns sample to player.

Sets the playback volume for left and right channels.

Gets the current left and right channel volume of the sampleplayer.

Stops playing the sample.

Frees the given player.

Creates a new synth object.

Frees a synth object, first removing it from the sound engine if needed.

Returns a copy of the given synth. Caller assumes ownership of the returned object and should free it when it is no longer in use.

Sets the waveform of the synth. The SoundWaveform enum contains the following values:

Provides custom waveform generator functions for the synth. These functions are called on the audio render thread, so they should return as quickly as possible. synthRenderFunc, the data provider callback, is the only required function.

synthRenderFunc: called every audio cycle to get the samples for playback. left (and right if setGenerator() was called with the stereo flag set) are sample buffers in Q8.24 format. rate is the amount to change a (Q32) phase accumulator each sample, and drate is the amount to change rate each sample. Custom synths can ignore this and use the note paramter in the noteOn function to handle pitch, but synth→setFrequencyModulator() won’t work as expected.

synthNoteOnFunc: called when the synth receives a note on event. len is the length of the note in seconds, or -1 if it’s not known yet when the note will end.

synthReleaseFunc: called when the synth receives a note off event. endoffset is how many samples into the current render cycle the note ends, allowing for sample-accurate timing.

synthSetParameterFunc: called when a parameter change is received from synth→setParameter() or a modulator.

synthDeallocFunc: called when the synth is being dealloced. This function should free anything that was allocated for the synth and also free the userdata itself.

synthCopyUserdata: called when synth→copy() needs a unique copy of the synth’s userdata. External objects should be retained or copied so that the object isn’t freed while the synth is still using it.

Provides a sample for the synth to play. Sample data must be uncompressed PCM, not ADPCM.

Sets a wavetable for the synth to play. Sample data must be 16-bit mono uncompressed. log2size is the base 2 logarithm of the number of samples in each waveform "cell" in the table, and columns and rows gives the number of cells in each direction; for example, if the wavetable is arranged in an 8x8 grid, columns and rows are both 8 and log2size is 6, since 2^6 = 8x8.

The function returns 1 on success. If it fails, use playdate→sound→getError() to get a human-readable error message.

The synth’s "position" in the wavetable is set manually with setParameter() or automated with setParameterModulator(). In some cases it’s easier to use a parameter that matches the waveform position in the table, in others (notably when using envelopes and lfos) it’s more convenient to use a 0-1 scale, so there’s some redundancy here. Parameters are

For 2-D tables (height > 1):

Sets the parameters of the synth’s ADSR envelope.

Returns the synth’s envelope. The PDSynth object owns this envelope, so it must not be freed.

Transposes the synth’s output by the given number of half steps. For example, if the transpose is set to 2 and a C note is played, the synth will output a D instead.

Sets a signal to modulate the synth’s frequency. The signal is scaled so that a value of 1 doubles the synth pitch (i.e. an octave up) and -1 halves it (an octave down). Set to NULL to clear the modulator.

Returns the currently set frequency modulator.

Sets a signal to modulate the synth’s output amplitude. Set to NULL to clear the modulator.

Returns the currently set amplitude modulator.

Plays a note on the synth, at the given frequency. Specify len = -1 to leave the note playing until a subsequent noteOff() call. If when is 0, the note is played immediately, otherwise the note is scheduled for the given time. Use playdate→sound→getCurrentTime() to get the current time.

The same as playNote but uses MIDI note (where 60 = C4) instead of frequency. Note that MIDINote is a typedef for `float', meaning fractional values are allowed (for all you microtuning enthusiasts).

Sends a note off event to the synth, either immediately (when = 0) or at the scheduled time.

Sets the playback volume (0.0 - 1.0) for the left and, if the synth is stereo, right channels of the synth. This is equivalent to

Gets the playback volume for the left and right (if stereo) channels of the synth. This is equivalent to

Returns 1 if the synth is currently playing.

Returns the number of parameters advertised by the synth.

Sets the (1-based) parameter at position num to the given value. Returns 0 if num is not a valid parameter index.

Sets a signal to modulate the parameter at index num. Set to NULL to clear the modulator.

Returns the currently set parameter modulator for the given index.

Creates a new PDSynthInstrument object.

Frees the given instrument, first removing it from the sound engine if needed.

Adds the given PDSynth to the instrument. The synth will respond to playNote events between rangeState and rangeEnd, inclusive. The transpose argument is in half-step units, and is added to the instrument’s transpose parameter. The function returns 1 if successful, or 0 if the synth is already in another instrument or channel.

The instrument passes the playNote/playMIDINote() event to the synth in its collection that has been off for the longest, or has been playing longest if all synths are currently playing. See also playdate→sound→synth→playNote(). The PDSynth that received the playNote event is returned.

Forwards the noteOff() event to the synth currently playing the given note. See also playdate→sound→synth→noteOff().

Sets the pitch bend and pitch bend range to be applied to the voices in the instrument.

Sets the transpose parameter for all voices in the instrument.

Sends a noteOff event to all voices in the instrument.

Sets and gets the playback volume (0.0 - 1.0) for left and right channels of the synth. This is equivalent to

Returns the number of voices in the instrument currently playing.

Provides a custom implementation for the signal. signalStepFunc step is the only required function, returning the value at the end of the current frame. When called, the ioframes pointer contains the number of samples until the end of the frame. If the signal needs to provide a value in the middle of the frame (e.g. an LFO that needs to be sample-accurate) it should return the "interframe" value in ifval and set iosamples to the sample offset of the value. The functions are called on the audio render thread, so they should return as quickly as possible.

Frees a signal created with playdate→sound→signal→newSignal().

Returns the current output value of signal. The signal can be a custom signal created with newSignal(), or any of the PDSynthSignal subclasses.

Offsets the signal’s output by the given amount.

Scales the signal’s output by the given factor. The scale is applied before the offset.

Returns a new LFO object, which can be used to modulate sounds. The type argument is one of the following values:

Frees the LFO.

Sets the LFO shape to one of the values given above.

Sets the LFO’s rate, in cycles per second.

Sets the LFO’s phase, from 0 to 1.

Sets the LFO’s initial phase, from 0 to 1.

Sets the center value for the LFO.

Sets the depth of the LFO.

Sets the LFO type to arpeggio, where the given values are in half-steps from the center note. For example, the sequence (0, 4, 7, 12) plays the notes of a major chord.

Provides a custom function for LFO values.

Sets an initial holdoff time for the LFO where the LFO remains at its center value, and a ramp time where the value increases linearly to its maximum depth. Values are in seconds.

If retrigger is on, the LFO’s phase is reset to its initial phase (default 0) when a synth using the LFO starts playing a note.

Return the current output value of the LFO.

If global is set, the LFO is continuously updated whether or not it’s currently in use.

Creates a new envelope with the given parameters.

Frees the envelope.

Sets the ADSR parameters of the envelope.

Smoothly changes the envelope’s shape from linear (amount=0) to exponential (amount=1).

Changes the amount by which note velocity scales output level. At the default value of 1, output is proportional to velocity; at 0 velocity has no effect on output level.

Scales the envelope rate according to the played note. For notes below start, the envelope’s set rate is used; for notes above end envelope rates are scaled by the scaling parameter. Between the two notes the scaling factor is interpolated from 1.0 to scaling.

Sets whether to use legato phrasing for the envelope. If the legato flag is set, when the envelope is re-triggered before it’s released, it remains in the sustain phase instead of jumping back to the attack phase.

If retrigger is on, the envelope always starts from 0 when a note starts playing, instead of the current value if it’s active.

Return the current output value of the envelope.

Creates a new effect using the given processing function. bufactive is 1 if samples have been set in the left or right buffers. The function should return 1 if it changed the buffer samples, otherwise 0. left and right (if the effect is on a stereo channel) are sample buffers in Q8.24 format.

Frees the given effect.

Sets the wet/dry mix for the effect. A level of 1 (full wet) replaces the input with the effect output; 0 leaves the effect out of the mix (which is useful if you’re using a delay line with taps and don’t want to hear the delay line itself).

Sets a signal to modulate the effect’s mix level. Set to NULL to clear the modulator.

Returns the current mix modulator for the effect.

Sets or gets a userdata value for the effect.

Creates a new two pole filter effect.

Frees the given filter.

Sets the type of the filter.

Sets the center/corner frequency of the filter. Value is in Hz.

Sets a signal to modulate the effect’s frequency. The signal is scaled so that a value of 1.0 corresponds to half the sample rate. Set to NULL to clear the modulator.

Returns the filter’s current frequency modulator.

Sets the filter gain.

Sets the filter resonance.

Sets a signal to modulate the filter resonance. Set to NULL to clear the modulator.

Returns the filter’s current resonance modulator.

Creates a new one pole filter.

Frees the filter.

Sets the filter’s single parameter (cutoff frequency) to p. Values above 0 (up to 1) are high-pass, values below 0 (down to -1) are low-pass.

Sets a signal to modulate the filter parameter. Set to NULL to clear the modulator.

Returns the filter’s current parameter modulator.

Returns a new BitCrusher effect.

Frees the given effect.

Sets the amount of crushing to amount. Valid values are 0 (no effect) to 1 (quantizing output to 1-bit).

Sets a signal to modulate the crushing amount. Set to NULL to clear the modulator.

Returns the currently set modulator.

Sets the number of samples to repeat, quantizing the input in time. A value of 0 produces no undersampling, 1 repeats every other sample, etc.

Sets a signal to modulate the undersampling amount. Set to NULL to clear the modulator.

Returns the currently set modulator.

Returns a new ring modulator effect.

Sets the frequency of the modulation signal.

Sets a signal to modulate the frequency of the ring modulator. Set to NULL to clear the modulator.

Returns the currently set frequency modulator.

Returns a new overdrive effect.

Frees the given effect.

Sets the gain of the overdrive effect.

Sets the level where the amplified input clips.

Sets a signal to modulate the limit parameter. Set to NULL to clear the modulator.

Returns the currently set limit modulator.

Adds an offset to the upper and lower limits to create an asymmetric clipping.

Sets a signal to modulate the offset parameter. Set to NULL to clear the modulator.

Returns the currently set offset modulator.

Creates a new delay line effect. The length parameter is given in samples.

Frees the delay line.

Changes the length of the delay line, clearing its contents. This function reallocates the audio buffer, so it is not safe to call while the delay line is in use.

Sets the feedback level of the delay line.

Returns a new tap on the delay line, at the given position. delay must be less than or equal to the length of the delay line.

Frees a tap previously created with playdate→sound→delayline→addTap(), first removing it from the sound engine if needed.

Sets the position of the tap on the delay line, up to the delay line’s length.

Sets a signal to modulate the tap delay. If the signal is continuous (e.g. an envelope or a triangle LFO, but not a square LFO) playback is sped up or slowed down to compress or expand time. Set to NULL to clear the modulator.

Returns the current delay modulator.

If the delay line is stereo and flip is set, the tap outputs the delay line’s left channel to its right output and vice versa.

Creates or destroys a SoundSequence object.

If the sequence is empty, attempts to load data from the MIDI file at path into the sequence. Returns 1 on success, 0 on failure.

Starts or stops playing the sequence. finishCallback is an optional function to be called when the sequence finishes playing or is stopped.

Returns 1 if the sequence is currently playing, otherwise 0.

Gets or sets the current time in the sequence, in samples since the start of the file. Note that which step this moves the sequence to depends on the current tempo.

Sets the looping range of the sequence. If loops is 0, the loop repeats endlessly.

Sets or gets the tempo of the sequence, in steps per second.

Returns the length of the longest track in the sequence, in steps. See also playdate.sound.track.getLength().

Returns the number of tracks in the sequence.

Adds the given playdate.sound.track to the sequence.

Sets or gets the given SoundTrack object at position idx in the sequence.

Sends a stop signal to all playing notes on all tracks.

Returns the step number the sequence is currently at. If timeOffset is not NULL, its contents are set to the current sample offset within the step.

Set the current step for the sequence. timeOffset is a sample offset within the step. If playNotes is set, notes at the given step (ignoring timeOffset) are played.

Creates a new control signal object.

Frees the given signal.

Clears all events from the given signal.

Adds a value to the signal’s timeline at the given step. If interpolate is set, the value is interpolated between the previous step+value and this one.

Removes the control event at the given step.

Returns the MIDI controller number for this ControlSignal, if it was created from a MIDI file via playdate→sound→sequence→loadMIDIFile().

Returns a new SequenceTrack.

Frees the SequenceTrack.

Sets or gets the PDSynthInstrument assigned to the track.

Adds a single note event to the track.

Removes the event at step playing note.

Clears all notes from the track.

Returns the length, in steps, of the track—​that is, the step where the last note in the track ends.

Returns the internal array index for the first note at the given step.

If the given index is in range, sets the data in the out pointers and returns 1; otherwise, returns 0.

Returns the number of ControlSignal objects in the track.

Returns the ControlSignal at index idx.

Returns the ControlSignal for MIDI controller number controller, creating it if the create flag is set and it doesn’t yet exist.

Clears all ControlSignals from the track.

Returns the number of voices currently playing in the track’s instrument.

Returns the maximum number of simultaneously playing notes in the track. (Currently, this value is only set when the track was loaded from a MIDI file. We don’t yet track polyphony for user-created events.)

Mutes or unmutes the track.

Clears bitmap, filling with the given bgcolor.

Returns a new LCDBitmap that is an exact copy of bitmap.

Returns 1 if any of the opaque pixels in bitmap1 when positioned at x1, y1 with flip1 overlap any of the opaque pixels in bitmap2 at x2, y2 with flip2 within the non-empty rect, or 0 if no pixels overlap or if one or both fall completely outside of rect.

Draws the bitmap with its upper-left corner at location x, y, using the given flip orientation.

Draws the bitmap scaled to xscale and yscale with its upper-left corner at location x, y. Note that flip is not available when drawing scaled bitmaps but negative scale values will achieve the same effect.

Draws the bitmap scaled to xscale and yscale then rotated by degrees with its center as given by proportions centerx and centery at x, y; that is: if centerx and centery are both 0.5 the center of the image is at (x,y), if centerx and centery are both 0 the top left corner of the image (before rotation) is at (x,y), etc.

Frees the given bitmap.

Gets various info about bitmap including its width and height and raw pixel data. The data is 1 bit per pixel packed format, in MSB order; in other words, the high bit of the first byte in data is the top left pixel of the image. If the bitmap has a mask, a pointer to its data is returned in mask, else NULL is returned.

Gets the color of the pixel at (x,y) in the given bitmap. If the coordinate is outside the bounds of the bitmap, or if the bitmap has a mask and the pixel is marked transparent, the function returns kColorClear; otherwise the return value is kColorWhite or kColorBlack.

Allocates and returns a new LCDBitmap from the file at path. If there is no file at path, the function returns null.

Loads the image at path into the previously allocated bitmap.

Allocates and returns a new width by height LCDBitmap filled with bgcolor.

Draws the bitmap with its upper-left corner at location x, y tiled inside a width by height rectangle.

Returns a new, rotated and scaled LCDBitmap based on the given bitmap.

Sets a mask image for the given bitmap. The set mask must be the same size as the target bitmap.

Gets a mask image for the given bitmap, or returns NULL if the bitmap doesn’t have a mask layer. The returned image points to bitmap's data, so drawing into the mask image affects the source bitmap directly. The caller takes ownership of the returned LCDBitmap and is responsible for freeing it when it’s no longer in use.

Returns the idx bitmap in table, If idx is out of bounds, the function returns NULL.

Allocates and returns a new LCDBitmap from the file at path. If there is no file at path, the function returns null.

Loads the imagetable at path into the previously allocated table.

Allocates and returns a new LCDBitmapTable that can hold count width by height LCDBitmaps.

Frees the given bitmap table. Note that this will invalidate any bitmaps returned by getTableBitmap().

Returns the bitmap table’s image count in the count pointer (if not NULL) and number of cells across in the cellswide pointer (ditto).

Returns the height of the given font.

Returns an LCDFontPage object for the given character code. Each LCDFontPage contains information for 256 characters; specifically, if (c1 & ~0xff) == (c2 & ~0xff), then c1 and c2 belong to the same page and the same LCDFontPage can be used to fetch the character data for both instead of searching for the page twice.

Returns an LCDFontGlyph object for character c in LCDFontPage page, and optionally returns the glyph’s bitmap and advance value.

Returns the kerning adjustment between characters c1 and c2 as specified by the font.

Returns the width of the given text in the given font.

Returns the LCDFont object for the font file at path. In case of error, outErr points to a string describing the error. The returned font can be freed with playdate→system→realloc(font, 0) when it is no longer in use.

Returns an LCDFont object wrapping the LCDFontData data comprising the contents (minus 16-byte header) of an uncompressed pft file. wide corresponds to the flag in the header indicating whether the font contains glyphs at codepoints above U+1FFFF.

Draws an ellipse inside the rectangle {x, y, width, height} of width lineWidth (inset from the rectangle bounds). If startAngle != _endAngle, this draws an arc between the given angles. Angles are given in degrees, clockwise from due north.

Fills an ellipse inside the rectangle {x, y, width, height}. If startAngle != _endAngle, this draws a wedge/Pacman between the given angles. Angles are given in degrees, clockwise from due north.

Manually flushes the current frame buffer out to the display. This function is automatically called after each pass through the run loop, so there shouldn’t be any need to call it yourself.

Only valid in the Simulator; function is NULL on device. Returns the debug framebuffer as a bitmap. White pixels drawn in the image are overlaid on the display in 50% transparent red.

Returns the raw bits in the display buffer, the last completed frame.

Returns a bitmap containing the contents of the display buffer. The system owns this bitmap—​do not free it!

Returns the current display frame buffer. Rows are 32-bit aligned, so the row stride is 52 bytes, with the extra 2 bytes per row ignored. Bytes are MSB-ordered; i.e., the pixel in column 0 is the 0x80 bit of the first byte of the row.

Returns a copy the contents of the working frame buffer as a bitmap. The caller is responsible for freeing the returned bitmap with playdate->graphics->freeBitmap().

Returns the current language of the system.

After updating pixels in the buffer returned by getFrame(), you must tell the graphics system which rows were updated. This function marks a contiguous range of rows as updated (e.g., markUpdatedRows(0,LCD_ROWS-1) tells the system to update the entire display). Both “start” and “end” are included in the range.

Sets color to an 8 x 8 pattern using the given bitmap. x, y indicates the top left corner of the 8 x 8 pattern.

Sets the pixel at (x,y) in the current drawing context (by default the screen) to the given color. Be aware that setting a pixel at a time is not very efficient: In our testing, more than around 20,000 calls in a tight loop will drop the frame rate below 30 fps.

Returns the last-read accelerometer data.

Sets the value pointed to by current to a bitmask indicating which buttons are currently down. pushed and released reflect which buttons were pushed or released over the previous update cycle—at the nominal frame rate of 50 ms, fast button presses can be missed if you just poll the instantaneous state.

As an alternative to polling for button presses using getButtonState(), this function allows a callback function to be set. The function is called for each button up/down event (possibly multiple events on the same button) that occurred during the previous update cycle. At the default 30 FPS, a queue size of 5 should be adequate. At lower frame rates/longer frame times, the queue size should be extended until all button presses are caught. The function should return 0 on success or a non-zero value to signal an error.

Returns the current position of the crank, in the range 0-360. Zero is pointing up, and the value increases as the crank moves clockwise, as viewed from the right side of the device.

Returns the angle change of the crank since the last time this function was called. Negative values are anti-clockwise.

Returns 1 or 0 indicating whether or not the crank is folded into the unit.

Decodes a JSON file or string with the given decoder. An instance of json_decoder must implement decodeError. The remaining functions are optional although you’ll probably want to implement at least didDecodeTableValue and didDecodeArrayValue. The outval pointer, if set, contains the value retured from the top-level didDecodeSublist callback.

Note that a whole number encoded to JSON as a float might be decoded as an int. The above convenience functions can be used to convert a json_value to the required type.

Populates the given json_encoder encoder with the functions necessary to encode arbitrary data into a JSON string. userdata is passed as the first argument of the given writeFunc write. When pretty is 1 the string is written with human-readable formatting.

Adds the Lua function f to the Lua runtime, with name name. (name can be a table path using dots, e.g. if name = “mycode.myDrawingFunction” adds the function “myDrawingFunction” to the global table “myCode”.) Returns 1 on success or 0 with an error message in outErr.

Adds the function list reg to the Lua runtime, with the class name name. As above, name can be a table path. The list is terminated with a {NULL, NULL} entry.

Creates a new "class" (i.e., a Lua metatable containing functions) with the given name and adds the given functions and constants to it. If the table is simply a list of functions that won’t be used as a metatable, isstatic should be set to 1 to create a plain table instead of a metatable. Please see C_API/Examples/Array for an example of how to use registerClass to create a Lua table-like object from C.

If a class includes an __index function, it should call this first to check if the indexed variable exists in the metatable. If the indexMetatable() call returns 1, it has located the variable and put it on the stack, and the __index function should return 1 to indicate a value was found. If indexMetatable() doesn’t find a value, the __index function can then do its custom getter magic.

Starts the run loop back up.

Stops the run loop.

Returns the type of the variable at stack position pos. If the type is kTypeObject and outClass is non-NULL, it returns the name of the object’s metatable.

Returns the number of arguments passed to the function.

Returns 1 if the argument at the given position pos is nil.

Returns one if the argument at position pos is true, zero if not.

Returns the argument at position pos as a float.

Returns the argument at position pos as an int.

Returns the argument at position pos as a string.

Returns the argument at position pos as an LCDSprite.

Returns the argument at position pos as a string and sets outlen to its length.

Returns the argument at position pos as an LCDBitmap.

Pushes the int val onto the stack.

Pushes the float val onto the stack.

Pushes the int val onto the stack.

Pushes nil onto the stack.

Pushes the string str onto the stack.

Like pushString(), but pushes an arbitrary byte array to the stack, ignoring \0 characters.

Pushes a lua_CFunction onto the stack.

Pushes the LCDBitmap bitmap onto the stack.

Pushes the LCDSprite sprite onto the stack.

Pushes the given custom object obj onto the stack and returns a pointer to the opaque LuaUDObject. type must match the class name used in playdate->lua->registerClass(). nValues is the number of slots to allocate for Lua values (see set/getObjectValue()).

Checks the object type of the argument at position pos and returns a pointer to it if it’s the correct type. Optionally sets outud to a pointer to the opaque LuaUDObject for the given stack.

Retains the opaque LuaUDObject obj and returns same.

Releases the opaque LuaUDObject obj.

Sets the value of object obj's uservalue slot number slot (starting at 1, not zero) to the value at the top of the stack.

Copies the value at obj's given uservalue slot to the top of the stack and returns its stack position.

Calls the Lua function name and and indicates that nargs number of arguments have already been pushed to the stack for the function to use. name can be a table path using dots, e.g. “playdate.apiVersion”. Returns 1 on success; on failure, returns 0 and puts an error message into the outerr pointer, if it’s set. Calling Lua from C is slow, so use sparingly.

Sets the bounds of the given sprite with bounds.

Returns the bounds of the given sprite as an PDRect;

Moves the given sprite to x, y and resets its bounds based on the bitmap dimensions and center.

Moves the given sprite to by offsetting its current position by dx, dy.

Sets x and y to the current position of sprite.

Sets the sprite’s drawing center as a fraction (ranging from 0.0 to 1.0) of the height and width. Default is 0.5, 0.5 (the center of the sprite). This means that when you call sprite→moveTo(sprite, x, y), the center of your sprite will be positioned at x, y. If you want x and y to represent the upper left corner of your sprite, specify the center as 0, 0.

Sets the values in outx and outy to the sprite’s drawing center as a fraction (ranging from 0.0 to 1.0) of the height and width.

Sets the given sprite's image to the given bitmap.

Returns the LCDBitmap currently assigned to the given sprite.

Sets the size. The size is used to set the sprite’s bounds when calling moveTo().

Sets the Z order of the given sprite. Higher Z sprites are drawn on top of those with lower Z order.

Returns the Z index of the given sprite.

Sets the tag of the given sprite. This can be useful for identifying sprites or types of sprites when using the collision API.

Returns the tag of the given sprite.

Sets the mode for drawing the sprite’s bitmap.

Flips the bitmap.

Returns the flip setting of the sprite’s bitmap.

Specifies a stencil image to be set on the frame buffer before the sprite is drawn.

Specifies a stencil image to be set on the frame buffer before the sprite is drawn. If tile is set, the stencil will be tiled. Tiled stencils must have width evenly divisible by 32.

Sets the sprite’s stencil to the given pattern.

Clears the sprite’s stencil.

Sets the clipping rectangle for sprite drawing.

Clears the sprite’s clipping rectangle.

Sets the clipping rectangle for all sprites with a Z index within startZ and endZ inclusive.

Clears the clipping rectangle for all sprites with a Z index within startZ and endZ inclusive.

Set the updatesEnabled flag of the given sprite (determines whether the sprite has its update function called). One is true, 0 is false.

Get the updatesEnabled flag of the given sprite.

Set the visible flag of the given sprite (determines whether the sprite has its draw function called). One is true, 0 is false.

Get the visible flag of the given sprite.

Marking a sprite opaque tells the sprite system that it doesn’t need to draw anything underneath the sprite, since it will be overdrawn anyway. If you set an image without a mask/alpha channel on the sprite, it automatically sets the opaque flag.

When flag is set to 1, this causes all sprites to draw each frame, whether or not they have been marked dirty. This may speed up the performance of your game if the system’s dirty rect tracking is taking up too much time - for example if there are many sprites moving around on screen at once.

Forces the given sprite to redraw.

Marks the given dirtyRect (in screen coordinates) as needing a redraw. Graphics drawing functions now call this automatically, adding their drawn areas to the sprite’s dirty list, so there’s usually no need to call this manually.

When flag is set to 1, the sprite will draw in screen coordinates, ignoring the currently-set drawOffset.

This only affects drawing, and should not be used on sprites being used for collisions, which will still happen in world-space.

Sets the update function for the given sprite.

Sets the draw function for the given sprite. Note that the callback is only called when the sprite is on screen and has a size specified via playdate→sprite→setSize() or playdate→sprite→setBounds().

Sets and gets the sprite’s userdata, an arbitrary pointer used for associating the sprite with other data.

Adds the given sprite to the display list, so that it is drawn in the current scene.

Removes the given sprite from the display list.

Removes the given count sized array of sprites from the display list.

Removes all sprites from the display list.

Returns the total number of sprites in the display list.

Draws every sprite in the display list.

Updates and draws every sprite in the display list.

Frees and reallocates internal collision data, resetting everything to its default state.

Set the collisionsEnabled flag of the given sprite (along with the collideRect, this determines whether the sprite participates in collisions). One is true, 0 is false. Set to 1 by default.

Get the collisionsEnabled flag of the given sprite.

Marks the area of the given sprite, relative to its bounds, to be checked for collisions with other sprites' collide rects.

Returns the given sprite’s collide rect.

Clears the given sprite’s collide rect.

Set a callback that returns a SpriteCollisionResponseType for a collision between sprite and other.

Returns the same values as playdate->sprite->moveWithCollisions() but does not actually move the sprite. The caller is responsible for freeing the returned array.

Moves the given sprite towards goalX, goalY taking collisions into account and returns an array of SpriteCollisionInfo. len is set to the size of the array and actualX, actualY are set to the sprite’s position after collisions. If no collisions occurred, this will be the same as goalX, goalY. The caller is responsible for freeing the returned array.

Returns an array of all sprites with collision rects containing the point at x, y. len is set to the size of the array. The caller is responsible for freeing the returned array.

Returns an array of all sprites with collision rects that intersect the width by height rect at x, y. len is set to the size of the array. The caller is responsible for freeing the returned array.

Returns an array of all sprites with collision rects that intersect the line connecting x1, y1 and x2, y2. len is set to the size of the array. The caller is responsible for freeing the returned array.

Returns an array of SpriteQueryInfo for all sprites with collision rects that intersect the line connecting x1, y1 and x2, y2. len is set to the size of the array. If you don’t need this information, use querySpritesAlongLine() as it will be faster. The caller is responsible for freeing the returned array.

Returns an array of sprites that have collide rects that are currently overlapping the given sprite’s collide rect. len is set to the size of the array. The caller is responsible for freeing the returned array.

Returns an array of all sprites that have collide rects that are currently overlapping. Each consecutive pair of sprites is overlapping (eg. 0 & 1 overlap, 2 & 3 overlap, etc). len is set to the size of the array. The caller is responsible for freeing the returned array.