From 0fc5f7835dee6fd02b648b1649e08bbcaa63b54c Mon Sep 17 00:00:00 2001 From: nick black Date: Sat, 10 Apr 2021 09:11:04 -0400 Subject: [PATCH] [docs] cell_release -> nccell_release --- USAGE.md | 30 +++++++++++++++--------------- doc/man/man3/notcurses_cell.3.md | 8 ++++---- doc/man/man3/notcurses_plane.3.md | 2 +- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/USAGE.md b/USAGE.md index e51907ab6..b6e5ef8a3 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1389,9 +1389,9 @@ ncplane_rounded_box(struct ncplane* n, uint32_t attr, uint64_t channels, if((ret = cells_rounded_box(n, attr, channels, &ul, &ur, &ll, &lr, &hl, &vl)) == 0){ ret = ncplane_box(n, &ul, &ur, &ll, &lr, &hl, &vl, ystop, xstop, ctlword); } - cell_release(n, &ul); cell_release(n, &ur); - cell_release(n, &ll); cell_release(n, &lr); - cell_release(n, &hl); cell_release(n, &vl); + nccell_release(n, &ul); nccell_release(n, &ur); + nccell_release(n, &ll); nccell_release(n, &lr); + nccell_release(n, &hl); nccell_release(n, &vl); return ret; } @@ -1414,9 +1414,9 @@ ncplane_double_box(struct ncplane* n, uint32_t attr, uint64_t channels, if((ret = cells_double_box(n, attr, channels, &ul, &ur, &ll, &lr, &hl, &vl)) == 0){ ret = ncplane_box(n, &ul, &ur, &ll, &lr, &hl, &vl, ystop, xstop, ctlword); } - cell_release(n, &ul); cell_release(n, &ur); - cell_release(n, &ll); cell_release(n, &lr); - cell_release(n, &hl); cell_release(n, &vl); + nccell_release(n, &ul); nccell_release(n, &ur); + nccell_release(n, &ll); nccell_release(n, &lr); + nccell_release(n, &hl); nccell_release(n, &vl); return ret; } @@ -1818,7 +1818,7 @@ EGC can be provided, or a string composed of multiple EGCs. In the latter case, the first EGC from the string is loaded. Remember, backing storage for the EGC is provided by the `ncplane` passed to `cell_load()`; if this `ncplane` is destroyed (or even erased), the `nccell` cannot safely be used. If you're done -using the `nccell` before being done with the `ncplane`, call `cell_release()` +using the `nccell` before being done with the `ncplane`, call `nccell_release()` to free up the EGC resources. ```c @@ -1839,10 +1839,10 @@ cell_prime(struct ncplane* n, nccell* c, const char* gcluster, // Duplicate 'c' into 'targ'. Not intended for external use; exposed for the // benefit of unit tests. -int cell_duplicate(struct ncplane* n, nccell* targ, const cell* c); +int nccell_duplicate(struct ncplane* n, nccell* targ, const cell* c); // Release resources held by the cell 'c'. -void cell_release(struct ncplane* n, nccell* c); +void nccell_release(struct ncplane* n, nccell* c); #define NCSTYLE_MASK 0x03fful #define NCSTYLE_STANDOUT 0x0080ul @@ -1922,7 +1922,7 @@ const char* cell_extended_gcluster(const struct ncplane* n, const nccell* c); // load up six cells with the EGCs necessary to draw a box. returns 0 on // success, -1 on error. on error, any cells this function might -// have loaded before the error are cell_release()d. There must be at least +// have loaded before the error are nccell_release()d. There must be at least // six EGCs in gcluster. static inline int cells_load_box(struct ncplane* n, uint32_t style, uint64_t channels, @@ -1937,15 +1937,15 @@ cells_load_box(struct ncplane* n, uint32_t style, uint64_t channels, if(cell_prime(n, vl, gclusters + ulen, style, channels) > 0){ return 0; } - cell_release(n, hl); + nccell_release(n, hl); } - cell_release(n, lr); + nccell_release(n, lr); } - cell_release(n, ll); + nccell_release(n, ll); } - cell_release(n, ur); + nccell_release(n, ur); } - cell_release(n, ul); + nccell_release(n, ul); } return -1; } diff --git a/doc/man/man3/notcurses_cell.3.md b/doc/man/man3/notcurses_cell.3.md index 8d1faa9d3..cc9b34266 100644 --- a/doc/man/man3/notcurses_cell.3.md +++ b/doc/man/man3/notcurses_cell.3.md @@ -47,9 +47,9 @@ typedef struct nccell { **int cell_prime(struct ncplane* ***n***, nccell* ***c***, const char* ***gcluster***, uint32_t ***stylemask***, uint64_t ***channels***);** -**int cell_duplicate(struct ncplane* ***n***, nccell* ***targ***, const nccell* ***c***);** +**int nccell_duplicate(struct ncplane* ***n***, nccell* ***targ***, const nccell* ***c***);** -**void cell_release(struct ncplane* ***n***, nccell* ***c***);** +**void nccell_release(struct ncplane* ***n***, nccell* ***c***);** **void cell_styles_set(nccell* ***c***, unsigned ***stylebits***);** @@ -132,9 +132,9 @@ some backing egcpool. Egcpools are associated with **ncplane**s, so **nccell**s must be considered associated with **ncplane**s. Indeed, **ncplane_erase()** destroys the backing storage for all a plane's cells, invalidating them. This association is formed at the time of **cell_load()**, **cell_prime()**, or -**cell_duplicate()**. All of these functions first call **cell_release()**, as +**nccell_duplicate()**. All of these functions first call **nccell_release()**, as does **cell_load_simple()**. When done using a **nccell** entirely, call -**cell_release()**. **ncplane_destroy()** will free up the memory used by the +**nccell_release()**. **ncplane_destroy()** will free up the memory used by the **nccell**, but the backing egcpool has a maximum size of 16MiB, and failure to release **nccell**s can eventually block new output. diff --git a/doc/man/man3/notcurses_plane.3.md b/doc/man/man3/notcurses_plane.3.md index abb669fa1..64a7607bf 100644 --- a/doc/man/man3/notcurses_plane.3.md +++ b/doc/man/man3/notcurses_plane.3.md @@ -382,7 +382,7 @@ respectively, of the pile containing their argument. **notcurses_top** and EGC at the relevant cell, or **NULL** if the cell is invalid. The caller should free this result. **ncplane_at_yx_cell** and **ncplane_at_cursor_cell** instead load these values into an **nccell**, which is invalidated if the associated plane is -destroyed. The caller should release this **nccell** with **cell_release**. +destroyed. The caller should release this **nccell** with **nccell_release**. **ncplane_as_rgba** returns a heap-allocated array of **uint32_t** values, each representing a single RGBA pixel, or **NULL** on failure.